Printago API
POST /v2/builds

Create and queue prints

Create prints containing parts and/or SKUs. You can issue prints by specifying individual parts and/or complete SKUs (products). Each part or SKU can be customized with specific quantities, parameters, materials, and other configuration options.

Request Body

- Build configuration specifying parts and SKUs to include

BuildConfigV2
partsoptional
object[]
Individual parts to print
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.
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
Custom label for this part in the build.
materialsoptional
Record<string, object[]>
Material assignments per extruder/channel (channel index -> material specifications)
parametersoptional
Record<string, number | string | boolean>
Key-value pairs of parameter names to their values for customizing parts
partIdrequired
string
ID of the part to print
pattern: ^[a-z0-9]{24}$
plateLabelsoptional
Record<string, string>
Per-plate label overrides keyed by plate ID. Only applies to 3MF and GCODE 3MF files. When set, the print job label for that plate becomes `${label} - ${plateLabels[plateId]}` instead of the plate's name embedded in the file.
plateQuantitiesoptional
Record<string, number>
Quantity distribution across plates. Only applies to 3MF and GCODE 3MF files
positionoptional
any
Position in the queue: 'front' places jobs at front of priority tier, 'back' at end
priorityoptional
any
Priority level for print job queue processing
quantityoptional
number
Number of copies to print.
min: 0max: 500
skipObjectsoptional
Record<string, string[]>
Construct a type with a set of properties K of type T
tagsoptional
object
Tags to categorize or filter this part
filament.typeoptional
string
printer.idoptional
string
printer.modelNameoptional
string
printer.nozzleDiameteroptional
string
printer.provideroptional
string
user.tagsoptional
string
skusoptional
object[]
SKUs (product bundles) to print

Example Request

application/json 
{
  "parts": [
    {
      "partId": "string",
      "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": {},
      "skipObjects": {}
    }
  ],
  "skus": []
}

Response Schema

BuildResultV2
partBuildsrequired
object[]
Created part build records
assignmentCompletedAtrequired
string
assignmentStartedAtrequired
string
createdAtrequired
string
format: date-time
dismissedrequired
boolean
extensionsoptional
object
idrequired
string
pattern: ^[a-z0-9]{24}$
labelrequired
string
linkedPartIdrequired
string
materialAssignmentsrequired
Record<string, object[]>
numPartsPerSkuoptional
number
orderIdrequired
string
orderItemIdrequired
string
outputFilesrequired
string[]
parameterOverridesrequired
object[]
namerequired
string
typerequired
any
valueoptional
number | string | boolean
partCopyrequired
object
arrangeableoptional
boolean
createdAtrequired
string
descriptionrequired
string
fileHashesrequired
string[]
fileUrisrequired
string[]
folderIdoptional
string
gcodePlateUrisoptional
Record<string, string>
idrequired
string
pattern: ^[a-z0-9]{24}$
materialsrequired
object[]
meshErroroptional
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.
meshSourceHashoptional
string
`fileHashes[0]` of the source the mesh state describes — the file `meshUri` was tessellated from, or the one `meshError` failed on.
meshUrioptional
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.
metadataoptional
object
namerequired
string
overriddenProcessProfileIdrequired
string
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
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[]
stepoptional
number
typerequired
any
valueoptional
number | string | boolean
printTagsrequired
object
filament.typeoptional
string
printer.idoptional
string
printer.modelNameoptional
string
printer.nozzleDiameteroptional
string
printer.provideroptional
string
user.tagsoptional
string
slicerOverrideoptional
string
slicingEstimateoptional
object
sourceoptional
any
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.
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
thumbnailUrirequired
string
typerequired
any
updatedAtrequired
string
uploadedAtoptional
string
use3MFProcessProfileoptional
boolean
userTagsoptional
string[]
partIdrequired
string
positionrequired
any
printingCompletedAtrequired
string
printingStartedAtrequired
string
printStatusrequired
any
priorityrequired
any
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
skuBuildIdrequired
string
skuIdrequired
string
skuInstanceStartoptional
number
skuNamerequired
string
statusrequired
any
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
thumbnailUrirequired
string
updatedAtrequired
string
format: date-time
skuBuildsrequired
object[]
Created SKU build records
createdAtrequired
string
format: date-time
idrequired
string
pattern: ^[a-z0-9]{24}$
orderIdrequired
string
orderItemIdrequired
string
priorityrequired
any
selectedOptionsoptional
Record<string, string>
skuCopyrequired
object
createdAtrequired
string
descriptionrequired
string
externalIdrequired
string
externalProviderrequired
any
folderIdoptional
string
idrequired
string
pattern: ^[a-z0-9]{24}$
skurequired
string
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
titlerequired
string
totalCogsrequired
number
updatedAtrequired
string
skuIdrequired
string
skuInstanceStartoptional
number
statusrequired
any
storeIdrequired
string
pattern: ^[a-z0-9]{24}$
updatedAtrequired
string
format: date-time

Example Response

201 OK — application/json 
{
  "partBuilds": [
    {
      "partCopy": {
        "name": "string",
        "description": "string",
        "fileUris": [
          "string"
        ],
        "fileHashes": [
          "string"
        ],
        "parameters": [
          {
            "options": [
              {
                "label": "string"
              }
            ],
            "description": "string",
            "min": 1,
            "max": 1,
            "step": 1,
            "acceptedContentTypes": [
              "string"
            ],
            "multiple": true,
            "defaultUri": "string",
            "name": "string"
          }
        ],
        "printTags": {
          "printer.provider": "string",
          "printer.id": "string",
          "printer.nozzleDiameter": "string",
          "printer.modelName": "string",
          "filament.type": "string",
          "user.tags": "string"
        },
        "use3MFProcessProfile": true,
        "arrangeable": true,
        "userTags": [
          "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,
      "parameterOverrides": [
        {
          "name": "string"
        }
      ],
      "dismissed": true,
      "id": "string",
      "storeId": "string",
      "createdAt": "2026-08-24T03:58:56.001Z",
      "updatedAt": "2026-08-24T03:58:56.001Z"
    }
  ],
  "skuBuilds": [
    {
      "skuCopy": {
        "sku": "string",
        "title": "string",
        "description": "string",
        "totalCogs": 1,
        "id": "string",
        "storeId": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "id": "string",
      "storeId": "string",
      "createdAt": "2026-08-24T03:58:56.001Z",
      "updatedAt": "2026-08-24T03:58:56.001Z"
    }
  ]
}