Preview part builds and jobs (dry run)

POST /v2/builds/preview

Preview part builds and jobs (dry run)

Preview builds and jobs that would be created without queueing anything.

Request Body

- Build configuration specifying parts and SKUs to preview

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

BuildPreviewV2

partBuildsrequired

object[]

Previewed part builds grouped with their corresponding jobs

jobsrequired

object[]

Print jobs that would be created for this part build

labelrequired

string

Label that the print job will use in queue

plateIdoptional

string | number

Optional plate ID for 3MF/GCODE 3MF jobs

plateNameoptional

string

Optional plate name for 3MF/GCODE 3MF jobs

quantityIndexrequired

number

1-based index of this job within the part build

quantityTotalrequired

number

Total jobs that would be created for this part build

thumbnailUrioptional

string

Optional thumbnail URI for this job

labelrequired

string

Label that the part build will use

materialsoptional

Record<string, object[]>

Material assignments that will be used for this part build

partIdrequired

string

Part ID for this previewed part build

pattern: ^[a-z0-9]{24}$

partNamerequired

string

Part name

partThumbnailUrioptional

string

Optional part-level thumbnail URI

plateQuantitiesoptional

Record<string, number>

3MF plate quantities, if applicable

quantityrequired

number

Part build quantity

skuoptional

object

SKU metadata when source is "sku"

sourcerequired

any

Indicates whether this part build comes from direct part config or a SKU config

summaryrequired

object

Summary counts for quick display

jobCountrequired

number

partBuildCountrequired

number

skuBuildCountrequired

number

Example Response

201 OK — application/json

{
  "partBuilds": [
    {
      "partId": "string",
      "partName": "string",
      "label": "string",
      "quantity": 1,
      "jobs": [
        {
          "label": "string",
          "quantityIndex": 1,
          "quantityTotal": 1
        }
      ]
    }
  ],
  "summary": {
    "partBuildCount": 1,
    "skuBuildCount": 1,
    "jobCount": 1
  }
}