Get all parts

GET /v1/parts

List all parts in your store

Requires: part.view

Query Parameters

name optional

string

Filter on name. A bare value is an exact match (name=value); use name.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

type optional

string

Filter on type. A bare value is an exact match (type=value); use type.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

description optional

string

Filter on description. A bare value is an exact match (description=value); use description.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

fileUris optional

string

Filter on fileUris. A bare value is an exact match (fileUris=value); use fileUris.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

fileHashes optional

string

Filter on fileHashes. A bare value is an exact match (fileHashes=value); use fileHashes.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

thumbnailUri optional

string

Filter on thumbnailUri. A bare value is an exact match (thumbnailUri=value); use thumbnailUri.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

parameters optional

string

Filter on parameters. A bare value is an exact match (parameters=value); use parameters.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

printTags optional

string

Filter on printTags. A bare value is an exact match (printTags=value); use printTags.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

overriddenProcessProfileId optional

string

Filter on overriddenProcessProfileId. A bare value is an exact match (overriddenProcessProfileId=value); use overriddenProcessProfileId.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

folderId optional

string

Filter on folderId. A bare value is an exact match (folderId=value); use folderId.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

materials optional

string

Filter on materials. A bare value is an exact match (materials=value); use materials.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

slicerOverride optional

string

Filter on slicerOverride. A bare value is an exact match (slicerOverride=value); use slicerOverride.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

metadata optional

string

Filter on metadata. A bare value is an exact match (metadata=value); use metadata.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

slicingEstimate optional

string

Filter on slicingEstimate. A bare value is an exact match (slicingEstimate=value); use slicingEstimate.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

use3MFProcessProfile optional

string

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.

arrangeable optional

string

Filter on arrangeable. A bare value is an exact match (arrangeable=value); use arrangeable.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

userTags optional

string

Filter on userTags. A bare value is an exact match (userTags=value); use userTags.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

gcodePlateUris optional

string

Filter on gcodePlateUris. A bare value is an exact match (gcodePlateUris=value); use gcodePlateUris.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

meshUri optional

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.

meshSourceHash optional

string

`fileHashes[0]` of the source the mesh state describes — the file `meshUri` was tessellated from, or the one `meshError` failed on.

meshError optional

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.

uploadedAt optional

string

Filter on uploadedAt. A bare value is an exact match (uploadedAt=value); use uploadedAt.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

customMetadata optional

string

Filter on customMetadata. A bare value is an exact match (customMetadata=value); use customMetadata.<operator>=value for the other operators (ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull; which ones a field accepts depends on its type). See Querying Data.

source optional

string

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.

processingStatus optional

string

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.

processing optional

string

Per-stage ingest progress and, on failure, which stage stopped and why.

id optional

string

Filter by record ID. A bare value is an exact match; use id.in=a,b,c for several (up to 100). See Querying Data.

storeId optional

string

Filter by store ID. Results are always limited to the store your API key belongs to, so this is rarely useful. See Querying Data.

createdAt optional

string

Filter by creation time. Pass an ISO 8601 timestamp with a comparison operator, e.g. createdAt.gte=2025-01-01T00:00:00Z. See Querying Data.

updatedAt optional

string

Filter by last-modified time. Pass an ISO 8601 timestamp with a comparison operator, e.g. updatedAt.gt=2025-01-01T00:00:00Z to fetch what changed since a checkpoint. See Querying Data.

sort optional

string

Comma-separated field:direction pairs, applied in order, e.g. createdAt:desc,name:asc. Direction is asc (the default) or desc. At most 5 clauses; JSON and array fields cannot be sorted on. See Querying Data.

limit optional

number

Maximum number of records to return, 1–1000. Defaults to 1000; larger values are capped at 1000. See Querying Data.

offset optional

number

Number of matching records to skip before returning results. Combine with limit to page through a list, and with meta=true to learn the total. See Querying Data.

fields optional

string

Comma-separated list of fields to return, e.g. id,name,updatedAt. Other fields are left out of each record. At most 50 fields. See Querying Data.

include optional

string

Comma-separated related records to embed in each result, e.g. linkedParts,linkedParts.part. At most 4 includes, each at most 2 levels deep; only the relations this endpoint supports are accepted, anything else is a 400. See Querying Data.

meta optional

boolean

Set to true to wrap the response as { data, meta }, where meta carries total, count, offset, limit, hasMore and executionTime. Without it the response is a bare array. See Querying Data.

hints optional

boolean

Set to true to add a hints array of suggested follow-up API calls to the response (aimed at AI agents). A list response is wrapped as { data, meta, hints }. See Querying Data.

Response Schema

Part[] | SearchResponse

Variant 1Part[]

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

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[]

colorrequired

string

idrequired

string

trayInfoIdxrequired

string

typerequired

string

usedGrequired

number

usedMrequired

number

indexoptional

number

labelObjectEnabledoptional

boolean

layerFilamentListsoptional

object[]

filamentListrequired

number

layerRangesrequired

string

nozzleDiametersoptional

string

nozzleVolumeTypeoptional

string

objectsoptional

object[]

identifyIdrequired

string

namerequired

string

skippedrequired

boolean

outsideoptional

boolean

predictionoptional

number

printerModelIdoptional

string

supportUsedoptional

boolean

timelapseTypeoptional

string

warningsoptional

object[]

errorCoderequired

string

levelrequired

number

msgrequired

string

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"

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"

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

userTagsoptional

string[]

max items: 10

Variant 2SearchResponseStandardized search response with data, metadata, and query information

datarequired

Record<string, any>[]

Array of matching entities

metarequired

object

Pagination and result metadata

countrequired

number

Number of records returned in this response

executionTimerequired

number

Query execution time in milliseconds

hasMorerequired

boolean

Whether there are more records available

limitrequired

number

Maximum number of records requested

offsetrequired

number

Number of records skipped

totalrequired

number

Total number of matching records (before pagination)

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"
  }
]