Printago API
POST /v2/builds

Create and queue prints

Queue parts and SKUs for printing. One request can mix any number of individual parts (parts) and SKUs (skus). Every entry becomes a part build, and every part build expands into print jobs in your queue.

Send Authorization: ApiKey <your-api-key> with every request.

How quantities become print jobs

What you send Print jobs created
A single-file part (STL, STEP, OpenSCAD, ...) with quantity: 3 3
A 3MF or GCODE 3MF part with quantity: 2 and no plateQuantities 2 per plate in the file
A 3MF or GCODE 3MF part with plateQuantities: { "1": 2, "3": 1 } 2 of plate 1, 1 of plate 3 (quantity is ignored)
A SKU with quantity: 2 For each linked part: its quantity in the SKU (plate quantities for a 3MF linked part), or the linkedPartConfigs override, multiplied by 2

What happens after the call

The response comes back as soon as the builds are recorded, with each part build in status: "pending". The rest is asynchronous:

  1. Parts that need rendering first (OpenSCAD, CadQuery and build123d models, STEP files, 3MF files with text parameters) are rendered.
  2. The print jobs are added to the queue with status: "pending", and the part build's status becomes success.
  3. Printago matches each job to a compatible idle printer, slices it for that printer (assigned, slicing, sliced) and sends it (sending-to-printer, printing).

To follow the jobs a build created, list them with GET /v1/print-jobs?partBuildId=<partBuild.id>. Jobs created for a SKU also carry skuId, so GET /v1/print-jobs?skuId=<skuId> works too.

Customizing a SKU print

  • options selects variant values for the SKU's variant options, by option id or name. The value can be a value name ("Red") or a value ID. Selected values drive the parameter, material and plate-quantity bindings you set up on the SKU's linked parts (see POST /v1/sku-variants).
  • linkedPartConfigs overrides settings for individual linked parts. It is keyed by the linked part ID (the id of an entry in the SKU's linkedParts, from GET /v1/skus/{id}), not by the part ID.

Call POST /v2/builds/preview with the same body first to see exactly which jobs (labels, plates, counts) a request will create, without queueing anything.

Every part must have finished file processing. A part whose processingStatus is "processing" or "failed" makes the whole request fail with 400. A SKU referenced by an unknown sku code is skipped rather than rejected, so check that skuBuilds in the response contains every SKU you sent.

Requires: build.create

Request Body

- Build configuration specifying parts and SKUs to include

BuildConfigV2
partsoptional
object[]

Individual parts to print. Each entry becomes one part build. Get part IDs from GET /v1/parts.

consolidationoptional
object

Pack this build's copies onto shared plates instead of printing one copy per job. Off unless enabled is true. partSpacingMm and plateMarginMm override your store's spacing settings for this build, and bedSize sets the target plate (defaults to the smallest bed among your printers).

bedSizeoptional
object
{x,y,z} mm build volume of the target plate.
xrequired
number
yrequired
number
zrequired
number
enabledrequired
boolean
Off by default. When true, this build's copies are consolidated.
partSpacingMmoptional
number
Per-build override of the store's part spacing (mm).
plateMarginMmoptional
number
Per-build override of the store's plate edge margin (mm).
labeloptional
string

Label shown on the print jobs in the queue. Defaults to the part name. For 3MF and GCODE 3MF parts, the plate name is appended.

materialsoptionalnullable
Record<string, object[]>

Material to use per filament channel, keyed by the channel index from the part's materials[].index (0 for a single-material part). Each value is a list of material specs in order of preference, each one of { "variantId": ... } (an exact material and color), { "materialId": ... }, { "groupId": ... } or { "materialType": "PLA" }. Channels you leave out keep the part's own material assignments.

parametersoptional
Record<string, number | string | boolean>

Parameter overrides for parametric parts, as { "name": value } pairs. Names match the part's parameters[].name.

partIdrequired
string

ID of the part to print, from GET /v1/parts. The part must have finished file processing (processingStatus is null).

pattern: ^[a-z0-9]{24}$
plateLabelsoptional
Record<string, string>

3MF and GCODE 3MF parts only. Per-plate label overrides keyed by plate ID. A job for that plate is labeled <label> - <plateLabels[plateId]> instead of using the plate name from the file.

plateQuantitiesoptional
Record<string, number>

3MF and GCODE 3MF parts only. Copies to print per plate, keyed by plate ID (for example { "1": 2, "3": 1 }). Only the listed plates are printed, and quantity is ignored. Plate IDs are in the part's metadata.plates.

positionoptional
"front" | "back"

Where the new jobs go within their priority tier: "back" (default) or "front".

frontback
priorityoptional
100 | 1000

100 (normal, the default) or 1000 (low). Normal-priority jobs are printed before low-priority ones.

1001000
quantityoptional
number

Number of copies, 0 to 500, default 1. For a 3MF or GCODE 3MF part, every plate in the file is printed this many times. Ignored when plateQuantities is set.

min: 0max: 500
skipObjectsoptional
Record<string, string[]>

Bambu printers only. Objects to skip per plate, keyed by plate ID, as lists of identifyId strings from metadata.plates[].sliced.objects[]. The print starts normally and the listed objects are skipped once the printer reports it has started.

tagsoptional
object

Printer-matching tags added to the job's required printer tags. Jobs only go to printers whose tags satisfy them.

filament.typeoptional
string
printer.idoptional
string
printer.modelNameoptional
string
printer.nozzleDiameteroptional
string
printer.provideroptional
string
user.tagsoptional
string
skusoptional
object[]

SKUs (products) to print. Identify each one by skuId or by its SKU code in sku. Each entry can also set quantity (complete units, 1 to 500, default 1), options (variant selections as { "name": "Color", "value": "Red" } or { "id": "<optionId>", "value": "Red" }; the value can be a value name or a value ID), linkedPartConfigs (overrides keyed by linked part ID, accepting the same quantity, parameters, label, tags, plateQuantities, plateLabels, skipObjects and materials fields as a part entry), priority, position, consolidation and tags. Every linked part of the SKU gets its own part build.

Example Request

application/json 
{
  "parts": [
    {
      "partId": "string",
      "priority": 100,
      "position": "front",
      "consolidation": {
        "enabled": true,
        "partSpacingMm": 1,
        "plateMarginMm": 1,
        "bedSize": {
          "x": 1,
          "y": 1,
          "z": 1
        }
      },
      "quantity": 0,
      "parameters": {},
      "label": "string",
      "tags": {
        "printer.provider": "string",
        "printer.id": "string",
        "printer.nozzleDiameter": "string",
        "printer.modelName": "string",
        "filament.type": "string",
        "user.tags": "string"
      },
      "plateQuantities": {},
      "plateLabels": {},
      "materials": {},
      "skipObjects": {}
    }
  ],
  "skus": [
    {
      "skuId": "string",
      "quantity": 1,
      "linkedPartConfigs": {},
      "tags": {
        "printer.provider": "string",
        "printer.id": "string",
        "printer.nozzleDiameter": "string",
        "printer.modelName": "string",
        "filament.type": "string",
        "user.tags": "string"
      },
      "priority": 100,
      "position": "front",
      "consolidation": {
        "enabled": true,
        "partSpacingMm": 1,
        "plateMarginMm": 1,
        "bedSize": {
          "x": 1,
          "y": 1,
          "z": 1
        }
      },
      "skuInstanceStart": 1,
      "order": {
        "orderId": "string",
        "orderItemId": "string"
      },
      "options": [
        {
          "id": "string",
          "value": "string"
        }
      ]
    }
  ]
}

Examples

Print copies of a part

Queue three copies of an STL part. The response contains one part build; its three print jobs appear in the queue moments later.

Request 
{
  "parts": [
    {
      "partId": "p8f2k6m1q9w3e7r5t0y4u2i6",
      "quantity": 3
    }
  ]
}
Response 
{
  "partBuilds": [
    {
      "id": "b7v3c9x1z5n2m8k4j0h6g3f1",
      "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
      "partId": "p8f2k6m1q9w3e7r5t0y4u2i6",
      "partCopy": {
        "id": "p8f2k6m1q9w3e7r5t0y4u2i6",
        "name": "Benchy",
        "type": "stl"
      },
      "label": "Benchy",
      "quantity": 3,
      "status": "pending",
      "printStatus": "pending",
      "parameterOverrides": [],
      "materialAssignments": null,
      "priority": 100,
      "position": "back",
      "skuBuildId": null,
      "skuId": null,
      "skuName": null,
      "orderId": null,
      "orderItemId": null,
      "linkedPartId": null,
      "outputFiles": null,
      "dismissed": false,
      "createdAt": "2026-09-23T14:05:12.418Z",
      "updatedAt": "2026-09-23T14:05:12.418Z"
    }
  ],
  "skuBuilds": []
}

Print selected plates of a 3MF in a specific color

Print plate 1 twice and plate 3 once, force filament channel 0 to a specific material variant, and put the jobs at the front of the queue.

Request 
{
  "parts": [
    {
      "partId": "d4n7c2v8b1x5z9m3q6w0e4r8",
      "label": "Desk Organizer",
      "plateQuantities": {
        "1": 2,
        "3": 1
      },
      "materials": {
        "0": [
          {
            "variantId": "m6a0t4v8a2r5i9a3n7t1j2w4"
          }
        ]
      },
      "position": "front"
    }
  ]
}
Response 
{
  "partBuilds": [
    {
      "id": "b2x6c0v4b8n1m5k9j3h7g2f6",
      "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
      "partId": "d4n7c2v8b1x5z9m3q6w0e4r8",
      "label": "Desk Organizer",
      "quantity": 1,
      "status": "pending",
      "printStatus": "pending",
      "extensions": {
        "3mf": {
          "plateQuantities": {
            "1": 2,
            "3": 1
          }
        }
      },
      "materialAssignments": {
        "0": [
          {
            "variantId": "m6a0t4v8a2r5i9a3n7t1j2w4"
          }
        ]
      },
      "priority": 100,
      "position": "front",
      "createdAt": "2026-09-23T14:07:40.102Z",
      "updatedAt": "2026-09-23T14:07:40.102Z"
    }
  ],
  "skuBuilds": []
}

Print a SKU by code with a variant selection

Build two units of the SKU BENCHY in red. Each SKU build is returned with the part builds created for its linked parts.

Request 
{
  "skus": [
    {
      "sku": "BENCHY",
      "quantity": 2,
      "options": [
        {
          "name": "Color",
          "value": "Red"
        }
      ]
    }
  ]
}
Response 
{
  "partBuilds": [],
  "skuBuilds": [
    {
      "id": "u6y2t8r4e0w5q1a7s3d9f2g4",
      "storeId": "k3m9x2p7q8r4t6v1w5y0z3a2",
      "skuId": "s5h1j7k3l9a2s6d0f4g8h2j5",
      "skuCopy": {
        "id": "s5h1j7k3l9a2s6d0f4g8h2j5",
        "sku": "BENCHY",
        "title": "Benchy"
      },
      "status": "pending",
      "priority": 100,
      "selectedOptions": {
        "v2a6r0i4a8n1t5c9o3l7o2r6": "Red"
      },
      "orderId": null,
      "orderItemId": null,
      "createdAt": "2026-09-23T14:09:03.551Z",
      "updatedAt": "2026-09-23T14:09:03.551Z",
      "partBuilds": [
        {
          "id": "b5n9m3k7j1h4g8f2d6s0a5q9",
          "partId": "p8f2k6m1q9w3e7r5t0y4u2i6",
          "skuBuildId": "u6y2t8r4e0w5q1a7s3d9f2g4",
          "skuId": "s5h1j7k3l9a2s6d0f4g8h2j5",
          "skuName": "BENCHY",
          "label": "Benchy",
          "quantity": 2,
          "numPartsPerSku": 1,
          "status": "pending",
          "materialAssignments": {
            "0": [
              {
                "variantId": "m6a0t4v8a2r5i9a3n7t1j2w4"
              }
            ]
          },
          "priority": 100,
          "position": "back"
        }
      ]
    }
  ]
}

Override one linked part inside a SKU

Print one unit of a SKU but make three copies of one of its linked parts, with a parameter override. The key in linkedPartConfigs is the linked part ID from the SKU's linkedParts.

Request 
{
  "skus": [
    {
      "skuId": "s5h1j7k3l9a2s6d0f4g8h2j5",
      "linkedPartConfigs": {
        "l2k8j4h0g6f1d7s3a9p5o1i7": {
          "quantity": 3,
          "parameters": {
            "name_text": "Ada"
          }
        }
      }
    }
  ]
}
Response 
{
  "partBuilds": [],
  "skuBuilds": [
    {
      "id": "u1i5o9p3a7s2d6f0g4h8j3k7",
      "skuId": "s5h1j7k3l9a2s6d0f4g8h2j5",
      "status": "pending",
      "priority": 100,
      "partBuilds": [
        {
          "id": "b8m2n6b0v4c7x1z5a9s3d7f1",
          "partId": "p8f2k6m1q9w3e7r5t0y4u2i6",
          "skuBuildId": "u1i5o9p3a7s2d6f0g4h8j3k7",
          "label": "Benchy",
          "quantity": 3,
          "numPartsPerSku": 3,
          "parameterOverrides": [
            {
              "name": "name_text",
              "value": "Ada",
              "type": "string"
            }
          ],
          "status": "pending"
        }
      ]
    }
  ]
}

Response Schema

BuildResultV2
partBuildsrequired
object[]

Part builds created for the entries in parts. Part builds created for SKUs are nested under each SKU build instead.

assignmentCompletedAtrequirednullable
string
format: date-time
assignmentStartedAtrequirednullable
string
format: date-time
createdAtrequired
string
format: date-time
customMetadataoptional
Record<string, any>
Construct a type with a set of properties K of type T
dismissedrequired
boolean
extensionsoptionalnullable
object
3mfoptional
object
plateLabelsoptional
Record<string, string>
plateQuantitiesoptional
Record<string, number>
skipObjectsoptional
Record<string, string[]>
Construct a type with a set of properties K of type T
boundingBoxoptionalnullable
object
{x,y,z} mm footprint of this build's generated geometry, stashed after a parametric (OpenSCAD/CadQuery) render so per-job boundingBox denormalization can read it without re-parsing the output STL.
xrequired
number
yrequired
number
zrequired
number
consolidationoptional
object
Build-time plate consolidation (issue #437): when printing quantity N of a part, pack the copies onto as few plates as possible and emit one merged plate per full plate instead of N separate jobs. Reuses the merge core, so a consolidated plate is an ordinary merged parent (unmergeable back into its copies). All layout fields default to the store's PlateMergingSettings / the account's smallest bed when omitted.
bedSizeoptional
object
{x,y,z} mm build volume of the target plate.
enabledrequired
boolean
Off by default. When true, this build's copies are consolidated.
partSpacingMmoptional
number
Per-build override of the store's part spacing (mm).
plateMarginMmoptional
number
Per-build override of the store's plate edge margin (mm).
createdByoptional
object
The person or API key that asked for a build, kept on the build itself.
actorEmailoptional
string
Actor's email for readability in logs
actorIdrequired
string
Firebase UID or system identifier
actorTyperequired
"user" | "api_key" | "webhook" | "system" | "scheduler" | "fuse"
Type of actor performing the operation
userapi_keywebhooksystemschedulerfuse
apiKeyIdoptional
string
API key ID if action was via API key
customizeroptional
object
unresolvedChannelsoptional
object[]
Palette channels whose customer hex could not be mapped to a material.
mergedPlateoptional
object
Marker + payload stored on a merged parent job's synthetic PartBuild.
bedSizerequired
object
{x,y,z} mm build volume of the target plate.
childJobIdsrequired
string[]
The child (merged-in) print job ids, in layout order.
childProcessSettingsoptional
Record<string, Record<string, string>>
Construct a type with a set of properties K of type T
excludeAreasoptional
object[]
Bed keep-out rects the layout respected (from the machine profile).
failureoptional
object
Set when async authoring failed and the merge was unwound.
filamentColoursoptional
string[]
Per-filament colours, indexed by slot (gaps null). Written into the merged 3MF, and mirrored onto the parent JOB's copy of this extension — the queue reports the plate's per-slot material requirements from the durable job row, since the synthetic build is archived out of client caches once authoring succeeds.
filamentCountoptional
number
Filaments the merged plate declares. Absent/1 = a single-color plate, whose objects are clamped to filament 1 at authoring time. >1 marks N copies of one multi-color plate, whose extruder ids carry through.
layoutrequired
object[]
Committed, authoritative placements the merged 3MF is authored from.
machineNameoptional
string
Target machine profile name, written into the merged file's config.
moderequired
"manual" | "auto" | "consolidation"
How this plate was created.
manualautoconsolidation
objectManifestoptional
Record<string, number[]>
Construct a type with a set of properties K of type T
policyoptional
"same-order" | "any"
Automatic-mode scope policy the merge was selected under (auto only).
same-orderany
processOverridesoptional
Record<string, string>
Construct a type with a set of properties K of type T
slicerVersionIdoptional
string
SlicerVersion.id the plate optimizer chose for this plate under the store's slicer-compatibility policy. Mirrored onto the parent job's mergedPlate extension and honored at dispatch. Absent = store slicer.
orderInfooptional
object
linkedPartIdrequired
string
pattern: ^[a-z0-9]{24}$
linkedPartQuantityrequired
number
sequenceFanoutoptional
object
Fan-out bookkeeping stamped on each per-unit sibling build when a sequence binding splits a quantity-N build into N quantity-1 builds. The siblings share one queue group and one queueOrder so the run prints in serial order, and their jobs carry contiguous quantityIndex values across the set.
buildIdsrequired
string[]
All sibling build ids in unit order (index 0 first).
groupIdrequired
string
Shared print-queue groupId for the whole sibling set.
queueOrderrequired
number
Pre-allocated queueOrder shared by every sibling's job.
unitCountrequired
number
Total number of sibling builds in the set.
unitIndexrequired
number
0-based index of this unit within the sibling set.
serialsoptional
object[]
Serials consumed by this build, stamped at allocation time.
parameterNamerequired
string
sequenceIdrequired
string
pattern: ^[a-z0-9]{24}$
sequenceNamerequired
string
serialrequired
string
targetoptional
object
The physical item a serial was allocated for, recorded so queue and history views can explain which item received which number. A plate-aware share-mode stamp carries only the plate (the value applies to every matching occurrence there); an increment-mode stamp pins the exact object instance in the 3MF's stable `(object_id, instance_id)` identity.
valuerequired
number
idrequired
string
pattern: ^[a-z0-9]{24}$
labelrequirednullable
string
linkedPartIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
materialAssignmentsrequirednullable
Record<string, object[]>
numPartsPerSkuoptionalnullable
number
orderIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
orderItemIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
outputFilesrequirednullable
string[]
parameterOverridesrequired
object[]
namerequired
string
typerequired
"number" | "string" | "boolean" | "file"
numberstringbooleanfile
valueoptional
number | string | boolean
partCopyrequired
object
arrangeableoptional
boolean
createdAtrequired
string
customMetadataoptional
Record<string, any>
descriptionrequired
string
fileHashesrequired
string[]
fileUrisrequired
string[]
folderIdoptionalnullable
string
pattern: ^[a-z0-9]{24}$
gcodePlateUrisoptionalnullable
Record<string, string>
idrequired
string
pattern: ^[a-z0-9]{24}$
materialsrequirednullable
object[]
colorrequirednullable
string
pattern: ^#{0,1}[0-9A-F]{6}|[0-9A-F]{8}$
identifieroptionalnullable
string
indexrequired
number
min: 0
nameoptionalnullable
string
skipoptional
boolean
typerequirednullable
string
meshErroroptionalnullable
string
Why tessellating this source failed. Set with `meshUri` cleared, so a file that cannot be meshed is stated once instead of re-converting on every print forever. Replacing the source moves `fileHashes[0]` off this hash, which retires the error without anything having to clear it.
meshSourceHashoptionalnullable
string
`fileHashes[0]` of the source the mesh state describes — the file `meshUri` was tessellated from, or the one `meshError` failed on.
meshUrioptionalnullable
string
Tessellated mesh derived from a boundary-representation source (STEP). The slicer CLI only reads meshes, so this — not `fileUris[0]` — is what the print and estimation paths feed it.
metadataoptionalnullable
object
filamentColorsrequired
string[]
filamentDensitiesoptional
number[]
filamentDiametersoptional
number[]
filamentIdsoptional
string[]
filamentTyperequired
string[]
nozzleDiameterrequired
string
plateRenderSourceHashoptional
string
`fileHashes[0]` of the source that produced the plates' `thumbnailRenderedUri`. Re-extraction carries the renders forward only while this still matches the part's current source; a replaced file leaves them behind rather than showing the previous model's geometry.
platesoptional
object[]
printerModelrequired
string
profileCompatrequired
object
slicerVersionoptionalnullable
object
textSlotsoptional
object[]
PrintagoParam text slots with their per-plate occurrence identities, re-detected whenever the file is (re)processed. The saved reuse mode lives on the slot's parameter, which survives a file replacement; this is the geometry-derived half that must always track the current file.
namerequired
string
overriddenProcessProfileIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
parametersrequired
object[]
acceptedContentTypesoptional
string[]
File-parameter-only fields (populated when `type === PartParameterVariableType.File`). Kept optional on the shared interface so scalar-parameter call sites do not need union-narrowing. See `FilePartParameter` for the strict shape. `acceptedContentTypes` is intentionally an OPEN `string[]` (not a narrow union). The customizer emits SVG, but Etsy attachments and direct API order ingestion can carry ANY mime type (PNG / JPG / PDF / AI / etc). Builders enforce kind constraints; the shared type stays open.
defaultoptional
number | string | boolean
defaultUrioptional
string
Optional fallback file URI (e.g. a known SVG in storage).
descriptionoptional
string
labeloptional
string
What the parameter is shown under wherever a customer or an operator fills it in; `name` stays the key everything binds by (SKU options, order inputs, build overrides, and — for a 3MF text slot — the text volume the substitution travels to). A parameter without one is shown under its name. This interface is the one the API's request validators are generated from, and it is a second declaration of the shape in `../part/parameter`. A field added to only one of them is accepted by the code and then pruned off the wire.
maxoptional
number
minoptional
number
multipleoptional
boolean
Whether the slot accepts >1 file. Reserved for forward compat — the Phase 5 resolver assumes single-file per slot for v1.
namerequired
string
optionsoptional
object[]
serialReuseoptional
"share" | "increment"
For a 3MF text-slot parameter bound to a sequence: whether occurrences repeated on one plate share a serial or each consume the next one. Absent means {@link TextSlotSerialReuse.Share }, today's duplicate-name meaning.
shareincrement
sizingoptional
"stretch" | "fit" | "unconstrained"
3MF text placeholders only: how a substituted value is sized against the bounds of the text volume it replaces. Absent means "fit within bounds", which is what every part declared before the setting existed carries. Declared on this shape as well as on `../part/parameter` for the reason `label` is — the API's request validators are generated from this one, and a field on only the other is pruned off the wire.
stretchfitunconstrained
stepoptional
number
typerequired
"number" | "string" | "boolean" | "file"
numberstringbooleanfile
valueoptional
number | string | boolean
printTagsrequired
object
filament.typeoptional
string
printer.idoptional
string
printer.modelNameoptional
string
printer.nozzleDiameteroptional
string
printer.provideroptional
string
user.tagsoptional
string
processingoptionalnullable
object
Per-stage ingest progress and, on failure, which stage stopped and why.
attemptrequired
number
How many ingests this part has had before this one — a monotonic per-part counter, not a per-file retry count, so no two runs can ever share a workflow key. See {@link nextPartIngestAttempt }.
erroroptional
string
failedStageoptional
"fetch" | "read-metadata" | "thumbnails" | "split-plates" | "estimate"
fetchread-metadatathumbnailssplit-platesestimate
fileHashrequired
string
`fileHashes[0]` this ingest describes; replacing the file retires it.
finishedAtoptional
string
stagesrequired
object[]
startedAtrequired
string
workflowKeyrequired
string
The workflow run that owns this state. A retry or a file replacement writes a new key first, so a superseded run's writes no longer match and are dropped instead of clobbering the newer run's progress.
processingStatusoptionalnullable
"processing" | "failed"
Where the file's ingest (metadata extraction, thumbnails, plate split, estimation) stands. `null` means ready — parts that predate the ingest workflow are healthy without backfill. System-set, not user-editable.
processingfailed
slicerOverrideoptionalnullable
string
slicingEstimateoptionalnullable
object
estimatedPrintTimeSecondsrequired
number
materialsrequired
object[]
platesoptional
object[]
profilesoptional
object
slicedAtrequired
string
slicerVersionrequired
string
totalWeightGramsrequired
number
sourceoptionalnullable
"google-drive" | "onedrive"
Which integration created this part. Set only by the cloud-storage providers today; null on every other creation path (upload, API, OpenSCAD, …) rather than carrying a synthetic "manual" value, so existing parts need no backfill. Not user-editable — it records what happened, not a preference.
google-driveonedrive
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
thumbnailUrirequirednullable
string
typerequired
enum
scadcadquerybuild123dstlstep3mfgcode3mfgcode
updatedAtrequired
string
uploadedAtoptionalnullable
string
use3MFProcessProfileoptional
boolean
Slice this part with the process profile embedded in its 3MF rather than the matched printer's. Omit it when creating a 3MF part and it is turned on for you, unless you also send an `overriddenProcessProfileId`; send `false` to slice with the printer's profile instead. Ignored for every other part type.
userTagsoptional
string[]
partIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
positionrequired
"front" | "back"
frontback
printingCompletedAtrequirednullable
string
format: date-time
printingStartedAtrequirednullable
string
format: date-time
printStatusrequired
"pending" | "printing" | "success" | "error" | "cancelled"
pendingprintingsuccesserrorcancelled
priorityrequired
100 | 1000
1001000
quantityrequired
number
min: 0max: 500
requiredPrinterTagsrequired
object
filament.typeoptional
string
printer.idoptional
string
printer.modelNameoptional
string
printer.nozzleDiameteroptional
string
printer.provideroptional
string
user.tagsoptional
string
skuBuildIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
skuIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
skuInstanceStartoptionalnullable
number
skuNamerequirednullable
string
statusrequired
enum
pendingbuildingqueuedfulfillingpreparingsending-to-printerprintingsuccesserrorcancelled
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
thumbnailUrirequirednullable
string
updatedAtrequired
string
format: date-time
skuBuildsrequired
object[]

One SKU build per resolved entry in skus, each with the part builds created for its linked parts in partBuilds.

createdAtrequired
string
format: date-time
idrequired
string
pattern: ^[a-z0-9]{24}$
orderIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
orderItemIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
priorityrequired
100 | 1000
1001000
selectedOptionsoptionalnullable
Record<string, string>
Construct a type with a set of properties K of type T
skuCopyrequired
object
createdAtrequired
string
customMetadataoptional
Record<string, any>
descriptionrequired
string
externalIdrequirednullable
string
externalProviderrequirednullable
"etsy" | "shopify"
etsyshopify
folderIdoptionalnullable
string
pattern: ^[a-z0-9]{24}$
idrequired
string
pattern: ^[a-z0-9]{24}$
skurequired
string
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
titlerequired
string
totalCogsrequired
number
updatedAtrequired
string
skuIdrequirednullable
string
pattern: ^[a-z0-9]{24}$
skuInstanceStartoptionalnullable
number
statusrequired
"pending" | "running" | "success" | "error" | "cancelled"
pendingrunningsuccesserrorcancelled
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
updatedAtrequired
string
format: date-time

Example Response

201 OK — application/json 
{
  "partBuilds": [
    {
      "partId": "string",
      "skuBuildId": "string",
      "skuId": "string",
      "skuName": "string",
      "label": "string",
      "partCopy": {
        "name": "string",
        "type": "scad",
        "description": "string",
        "fileUris": [
          "string"
        ],
        "fileHashes": [
          "string"
        ],
        "thumbnailUri": "string",
        "parameters": [
          {
            "default": 1,
            "options": [
              {
                "value": "string",
                "label": "string"
              }
            ],
            "description": "string",
            "min": 1,
            "max": 1,
            "step": 1,
            "acceptedContentTypes": [
              "string"
            ],
            "multiple": true,
            "defaultUri": "string",
            "label": "string",
            "serialReuse": "share",
            "sizing": "stretch",
            "name": "string",
            "type": "number",
            "value": 1
          }
        ],
        "printTags": {
          "printer.provider": "string",
          "printer.id": "string",
          "printer.nozzleDiameter": "string",
          "printer.modelName": "string",
          "filament.type": "string",
          "user.tags": "string"
        },
        "overriddenProcessProfileId": "string",
        "folderId": "string",
        "materials": [
          {
            "index": 0,
            "color": "string",
            "type": "string",
            "skip": true,
            "name": "string",
            "identifier": "string"
          }
        ],
        "slicerOverride": "string",
        "metadata": {
          "printerModel": "string",
          "filamentType": [
            "string"
          ],
          "filamentColors": [
            "string"
          ],
          "filamentDensities": [
            1
          ],
          "filamentDiameters": [
            1
          ],
          "nozzleDiameter": "string",
          "profileCompat": {
            "sliced": "string",
            "compatible": [
              "string"
            ],
            "safe": [
              "string"
            ]
          },
          "slicerVersion": {
            "engine": "orcaslicer",
            "version": "string"
          },
          "plates": [
            {
              "id": 1,
              "name": "string",
              "locked": true,
              "filamentMapMode": "string",
              "filamentMaps": [
                1
              ],
              "gcodeFile": "string",
              "thumbnailFile": "string",
              "thumbnailUploadedUri": "string",
              "thumbnailRenderedUri": "string",
              "thumbnailNoLightFile": "string",
              "thumbnailData": "string",
              "topFile": "string",
              "pickFile": "string",
              "topData": "string",
              "pickData": "string",
              "topUploadedUri": "string",
              "pickUploadedUri": "string",
              "patternBboxFile": "string",
              "sliced": {
                "index": 1,
                "extruderType": "string",
                "nozzleVolumeType": "string",
                "printerModelId": "string",
                "nozzleDiameters": "string",
                "timelapseType": "string",
                "prediction": 1,
                "weight": 1,
                "outside": true,
                "supportUsed": true,
                "labelObjectEnabled": true,
                "filamentMaps": "string",
                "objects": [
                  {}
                ],
                "filaments": [
                  {}
                ],
                "warnings": [
                  {}
                ],
                "layerFilamentLists": [
                  {}
                ]
              },
              "filamentIds": [
                "string"
              ]
            }
          ],
          "filamentIds": [
            "string"
          ],
          "textSlots": [
            {
              "key": "string",
              "label": "string",
              "text": "string",
              "volumeCount": 1,
              "fontName": "string",
              "fontVersion": "string",
              "surfaceType": 1,
              "occurrences": [
                {
                  "plateId": 1,
                  "objectId": "string",
                  "instanceId": 1,
                  "identifyId": "string"
                }
              ]
            }
          ],
          "plateRenderSourceHash": "string"
        },
        "slicingEstimate": {
          "estimatedPrintTimeSeconds": 1,
          "materials": [
            {
              "index": 1,
              "usedGrams": 1,
              "usedMeters": 1,
              "materialType": "string",
              "color": "string"
            }
          ],
          "totalWeightGrams": 1,
          "profiles": {
            "machineProfileId": "string",
            "machineProfileName": "string",
            "processProfileId": "string",
            "processProfileName": "string",
            "filamentProfileIds": [
              "string"
            ],
            "filamentProfileNames": [
              "string"
            ]
          },
          "slicedAt": "string",
          "slicerVersion": "string",
          "plates": [
            {
              "plateId": 1,
              "estimatedPrintTimeSeconds": 1,
              "materials": [
                {
                  "index": 1,
                  "usedGrams": 1,
                  "usedMeters": 1,
                  "materialType": "string",
                  "color": "string"
                }
              ],
              "totalWeightGrams": 1
            }
          ]
        },
        "use3MFProcessProfile": true,
        "arrangeable": true,
        "userTags": [
          "string"
        ],
        "gcodePlateUris": {},
        "meshUri": "string",
        "meshSourceHash": "string",
        "meshError": "string",
        "uploadedAt": "string",
        "customMetadata": {},
        "source": "google-drive",
        "processingStatus": "processing",
        "processing": {
          "workflowKey": "string",
          "fileHash": "string",
          "attempt": 1,
          "startedAt": "string",
          "finishedAt": "string",
          "failedStage": "fetch",
          "error": "string",
          "stages": [
            {
              "key": "fetch",
              "status": "running",
              "attempts": 1,
              "error": "string"
            }
          ]
        },
        "id": "string",
        "storeId": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "requiredPrinterTags": {
        "printer.provider": "string",
        "printer.id": "string",
        "printer.nozzleDiameter": "string",
        "printer.modelName": "string",
        "filament.type": "string",
        "user.tags": "string"
      },
      "quantity": 0,
      "numPartsPerSku": 1,
      "skuInstanceStart": 1,
      "parameterOverrides": [
        {
          "name": "string",
          "type": "number",
          "value": 1
        }
      ],
      "status": "pending",
      "outputFiles": [
        "string"
      ],
      "thumbnailUri": "string",
      "assignmentStartedAt": "2025-01-15T12:00:00.000Z",
      "assignmentCompletedAt": "2025-01-15T12:00:00.000Z",
      "printingStartedAt": "2025-01-15T12:00:00.000Z",
      "printingCompletedAt": "2025-01-15T12:00:00.000Z",
      "printStatus": "pending",
      "extensions": {
        "3mf": {
          "plateQuantities": {},
          "skipObjects": {},
          "plateLabels": {}
        },
        "createdBy": {
          "actorId": "string",
          "actorType": "user",
          "actorEmail": "string",
          "apiKeyId": "string"
        },
        "orderInfo": {
          "linkedPartId": "string",
          "linkedPartQuantity": 1
        },
        "boundingBox": {
          "x": 1,
          "y": 1,
          "z": 1
        },
        "mergedPlate": {
          "childJobIds": [
            "string"
          ],
          "layout": [
            {
              "jobId": "string",
              "x": 1,
              "y": 1,
              "rotationDeg": 0
            }
          ],
          "bedSize": {
            "x": 1,
            "y": 1,
            "z": 1
          },
          "mode": "manual",
          "policy": "same-order",
          "objectManifest": {},
          "machineName": "string",
          "excludeAreas": [
            {
              "x": 1,
              "y": 1,
              "width": 1,
              "height": 1
            }
          ],
          "filamentCount": 1,
          "filamentColours": [
            "string"
          ],
          "processOverrides": {},
          "childProcessSettings": {},
          "slicerVersionId": "string",
          "failure": {
            "message": "string"
          }
        },
        "consolidation": {
          "enabled": true,
          "partSpacingMm": 1,
          "plateMarginMm": 1,
          "bedSize": {
            "x": 1,
            "y": 1,
            "z": 1
          }
        },
        "customizer": {
          "unresolvedChannels": [
            {
              "index": 1,
              "hex": "string"
            }
          ]
        },
        "serials": [
          {
            "sequenceId": "string",
            "sequenceName": "string",
            "parameterName": "string",
            "value": 1,
            "serial": "string",
            "target": {
              "plateId": 1,
              "objectId": "string",
              "instanceId": 1,
              "identifyId": "string"
            }
          }
        ],
        "sequenceFanout": {
          "groupId": "string",
          "unitIndex": 1,
          "unitCount": 1,
          "buildIds": [
            "string"
          ],
          "queueOrder": 1
        }
      },
      "materialAssignments": {},
      "priority": 100,
      "position": "front",
      "orderId": "string",
      "orderItemId": "string",
      "linkedPartId": "string",
      "dismissed": true,
      "customMetadata": {},
      "id": "string",
      "storeId": "string",
      "createdAt": "2025-01-15T12:00:00.000Z",
      "updatedAt": "2025-01-15T12:00:00.000Z"
    }
  ],
  "skuBuilds": [
    {
      "skuId": "string",
      "skuCopy": {
        "sku": "string",
        "title": "string",
        "description": "string",
        "externalId": "string",
        "externalProvider": "etsy",
        "folderId": "string",
        "totalCogs": 1,
        "customMetadata": {},
        "id": "string",
        "storeId": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "status": "pending",
      "skuInstanceStart": 1,
      "orderId": "string",
      "orderItemId": "string",
      "priority": 100,
      "selectedOptions": {},
      "id": "string",
      "storeId": "string",
      "createdAt": "2025-01-15T12:00:00.000Z",
      "updatedAt": "2025-01-15T12:00:00.000Z"
    }
  ]
}