Printago API
PATCH /v1/parts

Bulk update parts

Update the same fields on multiple parts at once

Requires: part.edit

Request Body

Part IDs and shared update data

UpdateManyRequestPartUpdateWithMaterials
idsrequired
string[]
updaterequired
object
Make all properties in T optional
arrangeableoptional
boolean
assignedMaterialsoptional
Record<string, object[]>
customMetadataoptional
Record<string, any>
Construct a type with a set of properties K of type T
descriptionoptional
string
fileUrisoptional
string[]
min items: 1
folderIdoptionalnullable
string
pattern: ^[a-z0-9]{24}$
nameoptional
string
overriddenProcessProfileIdoptionalnullable
string
pattern: ^[a-z0-9]{24}$
parametersoptional
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[]
labeloptional
string
valuerequired
string | number
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
printTagsoptional
object
filament.typeoptional
string
printer.idoptional
string
printer.modelNameoptional
string
printer.nozzleDiameteroptional
string
printer.provideroptional
string
user.tagsoptional
string
slicerOverrideoptionalnullable
string
typeoptional
enum
scadcadquerybuild123dstlstep3mfgcode3mfgcode
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[]
max items: 10

Example Request

application/json 
{
  "ids": [
    "string"
  ],
  "update": {
    "name": "string",
    "type": "scad",
    "description": "string",
    "fileUris": [
      "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"
    },
    "customMetadata": {},
    "overriddenProcessProfileId": "string",
    "folderId": "string",
    "slicerOverride": "string",
    "use3MFProcessProfile": true,
    "arrangeable": true,
    "userTags": [
      "string"
    ],
    "assignedMaterials": {}
  }
}

Response Schema

Part[]
Array of Part, each with:
arrangeableoptional
boolean
createdAtrequired
string
format: date-time
customMetadataoptional
Record<string, any>
Construct a type with a set of properties K of type T
descriptionrequired
string
fileHashesrequired
string[]
min items: 1
fileUrisrequired
string[]
min items: 1
folderIdoptionalnullable
string
pattern: ^[a-z0-9]{24}$
gcodePlateUrisoptionalnullable
Record<string, string>
Construct a type with a set of properties K of type T
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[]
filamentIdsoptional
string[]
filamentMapModeoptional
string
filamentMapsoptional
number[]
gcodeFileoptional
string
idrequired
number
lockedoptional
boolean
nameoptional
string
patternBboxFileoptional
string
pickDataoptional
string
pickFileoptional
string
pickUploadedUrioptional
string
slicedoptional
object
extruderTypeoptional
string
filamentMapsoptional
string
filamentsoptional
object[]
indexoptional
number
labelObjectEnabledoptional
boolean
layerFilamentListsoptional
object[]
nozzleDiametersoptional
string
nozzleVolumeTypeoptional
string
objectsoptional
object[]
outsideoptional
boolean
predictionoptional
number
printerModelIdoptional
string
supportUsedoptional
boolean
timelapseTypeoptional
string
warningsoptional
object[]
weightoptional
number
thumbnailDataoptional
string
thumbnailFileoptional
string
thumbnailNoLightFileoptional
string
thumbnailRenderedUrioptional
string
The plate re-rendered by the three.js builder. Written by a different flow, and to a different storage path, than the archive copy above — a later metadata reprocess re-copies the archive image and must not be able to overwrite this. Prefer it over `thumbnailUploadedUri` (see `plateThumbnailUri`).
thumbnailUploadedUrioptional
string
The archive's own plate preview, copied out at metadata-extraction time.
topDataoptional
string
Base64 PNG data for the top/pick images, staged before upload then cleared.
topFileoptional
string
topUploadedUrioptional
string
Uploaded URIs for the plate's top-down image and color-coded object pick mask. Used by the visual skip-objects picker.
printerModelrequired
string
profileCompatrequired
object
compatiblerequired
string[]
saferequired
string[]
slicedrequired
string
slicerVersionoptionalnullable
object
enginerequired
"orcaslicer" | "bambu-studio" | "prusaslicer" | "superslicer"
orcaslicerbambu-studioprusaslicersuperslicer
versionrequired
string
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.
fontNameoptional
string
`font_name` of the first volume seen with this key.
fontVersionoptional
string
`font_version` of the first volume seen with this key.
keyrequired
string
The matching volume/object name — the substitution key.
labelrequired
string
The label this slot's parameter is shown under.
occurrencesoptional
object[]
Every printable object instance carrying this slot, across all plates. Absent when the file predates occurrence detection or has no plate metadata to resolve instances against.
identifyIdoptional
string
Bambu's per-instance id, when present (matches gcode object labels).
instanceIdrequired
number
0-based instance index among the object's build items.
objectIdrequired
string
`model_settings.config` object id (matches the root model's build items).
plateIdrequired
number
surfaceTypeoptional
number
`surface_type` of the first volume seen with this key (0=flat).
textrequired
string
The text authored into the volume. It prints as-is when the slot goes unfilled, which makes it the parameter's default.
volumeCountrequired
number
How many text volumes in the file carry this slot name.
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[]
labeloptional
string
valuerequired
string | number
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[]
attemptsoptional
number
Times the stage has been started, so the UI can say "retrying · attempt N".
erroroptional
string
keyrequired
"fetch" | "read-metadata" | "thumbnails" | "split-plates" | "estimate"
fetchread-metadatathumbnailssplit-platesestimate
statusrequired
"running" | "done" | "pending" | "failed" | "skipped"
runningdonependingfailedskipped
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[]
coloroptional
string
indexrequired
number
materialTyperequired
string
usedGramsrequired
number
usedMetersrequired
number
platesoptional
object[]
estimatedPrintTimeSecondsrequired
number
materialsrequired
object[]
coloroptional
string
indexrequired
number
materialTyperequired
string
usedGramsrequired
number
usedMetersrequired
number
plateIdrequired
number
totalWeightGramsrequired
number
profilesoptional
object
filamentProfileIdsrequired
string[]
filamentProfileNamesrequired
string[]
machineProfileIdrequired
string
machineProfileNamerequired
string
processProfileIdrequired
string
processProfileNamerequired
string
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
format: date-time
uploadedAtoptionalnullable
string
format: date-time
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[]
max items: 10

Example Response

200 OK — application/json 
[
  {
    "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": [
              {
                "identifyId": "string",
                "name": "string",
                "skipped": true
              }
            ],
            "filaments": [
              {
                "id": "string",
                "trayInfoIdx": "string",
                "type": "string",
                "color": "string",
                "usedM": 1,
                "usedG": 1
              }
            ],
            "warnings": [
              {
                "msg": "string",
                "level": 1,
                "errorCode": "string"
              }
            ],
            "layerFilamentLists": [
              {
                "filamentList": 1,
                "layerRanges": "string"
              }
            ]
          },
          "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": "2025-01-15T12:00:00.000Z",
    "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": "2025-01-15T12:00:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  }
]