The Model object
A reusable design: readiness status, inspection results, measurements and Model repair.
Fields
file_revision integer · optional
Current customer file revision. Size and name changes do not create file revisions.
Minimum: 1
file_repair integer | null · optional
Current model repair of file_revision (1 and 1 is revision 1.1), or null.
Minimum: 1
id string · required
Immutable design identifier. File replacements append a customer file revision while preserving this ID and previous sources.
Min length: 11 · Max length: 11
source object · required
Reference to an uploaded geometry file and its supporting assets. One file can back multiple models in the same account. Set print size explicitly using longest_dimension_mm.
source fields
file_id string · required
Unique, server-generated file ID. Treat it as an opaque reference.
Min length: 37 · Max length: 37
name string · optional
Optional customer-supplied label. Unicode category C characters, including control and format characters, are rejected.
external_id string · optional
Optional identifier from your system. Not unique and does not deduplicate requests; filter by external_id when listing models.
created_at string (date-time) · required
When registration occurred; immutable. UTC RFC 3339 timestamp with six fractional-second digits (microseconds).
updated_at string (date-time) · required
Last persisted model update, including processing, readiness, preview and price changes. Use with updated_since to sync. Reading the model does not change this timestamp. Models have no time-based expiry. UTC RFC 3339 timestamp with six fractional-second digits (microseconds).
status string · required
Public readiness. ready: CalculatePrices, quotes and orders accept the model at its saved size, including any required Model repair price. processing: inspection, measurements or the repair estimate are still running. action_required: processing finished but the model cannot be priced; status_reasons says why and how to recover. failed: processing failed; replace the file. Poll until status is not processing, or subscribe to model.ready.
Allowed values: processing, ready, action_required, failed
status_reasons array · required
Why the model is not ready, in check order. Empty when ready.
status_reasons item fields
code string · required
Why the model is not ready. A failed model reports its processing error code.
Allowed values: inspection_pending, measurements_pending, repair_estimate_pending, measurements_unavailable, volume_unavailable, invalid_model_package, unreadable_model, missing_required_assets, unsupported_format, unsupported_model_features, invalid_geometry, processing_limit_exceeded, processing_timeout, inspection_unavailable, processing_failed, storage_unavailable
message string · required
Human-readable explanation; not a stable identifier.
preview object | null · required
Independent preview progress and seven image URLs when ready. Null for older models without a preview job or when temporary signing failure prevents safe delivery; other model fields remain available. Inspection does not wait for previews; repair cost estimation consumes all seven images or its documented fallback.
preview fields
At least one of these conditions applies:
pending / processing / ready / failed
status string · required
pending waits for normalization or rendering; processing renders images; ready makes all seven available; failed has an error. Poll GetModel with backoff until ready or failed.
Allowed values: pending, processing, ready, failed
default_view string · optional
Recommended image for cards and thumbnails. Present only when ready.
Always: "angled"
expires_at string (date-time) · optional
Earliest expiry of all preview URLs, at most 15 minutes after retrieval. Retrieve the model for fresh URLs. Issued URLs can remain usable until expiry after permission removal or model deletion.
images object · optional
Original transparent PNGs. Present only when ready. All seven source views are published together.
images fields
angled string (uri) · required
Camera at [1, 0.8, 1], looking toward the model center, with +Y up. Default view.
front string (uri) · required
Camera on +Z, +Y up.
back string (uri) · required
Camera on -Z, +Y up.
left string (uri) · required
Camera on -X, +Y up.
right string (uri) · required
Camera on +X, +Y up.
top string (uri) · required
Camera on +Y, -Z up.
bottom string (uri) · required
Camera on -Y, +Z up.
thumbnails object · optional
Transparent 384 by 384 pixel WebP images for compact views. Present only when ready. Each missing variant uses its source PNG URL.
thumbnails fields
angled string (uri) · required
Camera at [1, 0.8, 1], looking toward the model center, with +Y up. Default view.
front string (uri) · required
Camera on +Z, +Y up.
back string (uri) · required
Camera on -Z, +Y up.
left string (uri) · required
Camera on -X, +Y up.
right string (uri) · required
Camera on +X, +Y up.
top string (uri) · required
Camera on +Y, -Z up.
bottom string (uri) · required
Camera on -Y, +Z up.
display object · optional
Transparent 1024 by 1024 pixel WebP images for larger views. Present only when ready. Each missing variant uses its source PNG URL.
display fields
angled string (uri) · required
Camera at [1, 0.8, 1], looking toward the model center, with +Y up. Default view.
front string (uri) · required
Camera on +Z, +Y up.
back string (uri) · required
Camera on -Z, +Y up.
left string (uri) · required
Camera on -X, +Y up.
right string (uri) · required
Camera on +X, +Y up.
top string (uri) · required
Camera on +Y, -Z up.
bottom string (uri) · required
Camera on -Y, +Z up.
null
null
metadata object · optional
Optional customer key/value strings. Up to 50 keys, each 1–40 characters; values up to 500 characters. Unicode category C characters (including control and format characters) are rejected in keys and values. No secrets. Not interpreted for pricing, permissions or deduplication.
longest_dimension_mm number · required
Default print size and inspection reference size, in millimeters. Pricing items can select another size without changing this model or existing cart/order items.
Minimum: 30 · Maximum: 200
mesh_check object · required
Execution status, independent of the result. Successful checks may find defects or incomplete categories. The input geometry is not automatically repaired.
mesh_check fields
status string · required
Allowed values: pending, processing, completed, failed
warnings array · optional
Non-blocking appearance warnings. Missing materials use neutral gray; missing or unreadable textures use the material base color. Original uploads remain unchanged.
warnings item fields
code string · required
Allowed values: appearance_fallback
message string · required
result object · conditional
result fields
passed boolean | null · required
False: a supported check found a defect. True: all three supported primary checks completed and found none. Null: no defect established, but one or more primary checks are incomplete. This is not printability or manufacturing approval.
incomplete_checks array · required
Supported checks that did not finish completely. A known positive count can coexist with incomplete checks.
incomplete_checks item fields
string
Allowed values: inverted_normals, bad_edges, planar_holes
inverted_normals integer | null · required
Inverted triangle count. Null means unavailable, never zero.
Minimum: 0
bad_edges integer | null · required
Unpaired directed edge incidences; one geometric edge can contribute more than one. Null means unavailable, never zero.
Minimum: 0
planar_holes integer | null · required
Detected planar hole contours. Null means unavailable, never zero.
Minimum: 0
shells integer | null · required
Number of shared-edge connected components. Faces joined by an edge belong to the same component, even at non-manifold or reversed edges. Vertex-only contact does not join components. Multiple components are allowed. Null means unavailable.
Minimum: 0
near_bad_edges integer | null · required
Measured Magics count, or null when unavailable.
Minimum: 0
noise_shells integer | null · required
Measured Magics count, or null when unavailable.
Minimum: 0
error object · conditional
Processing failure included in a successful model lookup (HTTP 200). Correct source problems by uploading a new file and replacing the existing model's source, or by creating a separate model. For persistent service failures, contact support with the model ID. A terminally failed model can retry with PATCH at the same print size and If-Match; this queues a new processing revision without uploading again. Completed evidence may remain visible, but manufacturing_estimate is unavailable and pricing/quotes return pricing_unavailable while failed. Late inspection results do not clear this model-level error or emit a completion event.
error fields
code string · required
Allowed values: invalid_model_package, unreadable_model, missing_required_assets, unsupported_format, unsupported_model_features, invalid_geometry, processing_limit_exceeded, processing_timeout, inspection_unavailable, processing_failed, storage_unavailable
message string · required
Recovery instructions. Do not branch on message text.
Exactly one of these conditions applies:
pending / processing
Absent fields: result, error.
status string · required
Allowed values: pending, processing
completed
Required fields: result.
Absent fields: error.
status string · required
Always: "completed"
failed
Required fields: error.
Absent fields: result.
status string · required
Always: "failed"
print_check object · required
Mesh integrity assessment at longest_dimension_mm. Printable means a completed inspection with zero inverted normals, bad edges and planar holes. Hard mesh defects or an inspection time budget failure require repair. Missing, incomplete or failed analysis is not a pass. This assessment does not authorize an order.
print_check fields
status string · required
Allowed values: pending, processing, completed, failed
longest_dimension_mm number · conditional
Minimum: 30 · Maximum: 200
waiting_for array · optional
waiting_for item fields
string
Allowed values: mesh_check
result object · conditional
result fields
passed boolean · required
Allowed values: true, false
decision string · required
Allowed values: printable, repair_required
blocking_mesh_checks array · required
blocking_mesh_checks item fields
string
Allowed values: inverted_normals, bad_edges, planar_holes
incomplete_mesh_checks array · required
incomplete_mesh_checks item fields
string
Allowed values: inverted_normals, bad_edges, planar_holes
risks array · required
risks item fields
severity string · required
Allowed values: warning, high
region_ids array · required
Stable IDs within this assessment. Empty for whole-model or hard mesh issues.
region_ids item fields
string
message string · required
Min length: 1 · Max length: 1000
Exactly one of these conditions applies:
object
passed boolean · required
Always: true
decision string · required
Always: "printable"
object
passed boolean · required
Always: false
decision string · required
Always: "repair_required"
error object · conditional
error fields
code string · required
Always: "printability_unavailable"
message string · required
Exactly one of these conditions applies:
pending / processing
Absent fields: result, error.
status string · required
Allowed values: pending, processing
completed
Required fields: longest_dimension_mm, result.
Absent fields: waiting_for, error.
status string · required
Always: "completed"
failed
Required fields: longest_dimension_mm, error.
Absent fields: waiting_for, result.
status string · required
Always: "failed"
repair object · required
Model repair decided by the server. It applies when mesh inspection fails, when the account requested repair for this file revision, or when a paid order already covers the revision. A model that passes inspection prints as uploaded.
progress object · optional
progress fields
stage string · required
Current inspection progress. inspection_completed and failed end polling for inspection; the overall model status can still be processing.
Allowed values: queued, preparing, inspecting, resizing, inspection_completed, failed
volume object | null · optional
Volume at the default print size in cubic millimeters, rounded to at most three decimal places. Null when unavailable.
volume fields
value_mm3 number · required
Cubic millimeters at the selected size, rounded to at most three decimal places. Holes and inconsistent geometry can affect estimate accuracy.
Minimum: 0
status string · required
estimated: approximate measurement; confirmed: validated measurement. Currently returns estimated.
Allowed values: estimated, confirmed
estimated_weight_g number | null · optional
Estimated model material weight at the default print size, in grams, rounded to at most three decimal places. Excludes support material. Null when unavailable.
Minimum: 0
orders object · optional
Current order history for this model in its owning account. Includes all order statuses and revisions; count is distinct orders, not printed models or line items. Latest uses creation time then ID. Historical idempotent registration replays may omit this field.
orders fields
count integer · required
Minimum: 0
latest_order_id string | null · required
manufacturing_estimate object · optional
Independent manufacturing component at the default print size; excludes repair, shipping and tax. Provisional, never checkout approval. Uses settled account rates when available; final pricing settles discounts. Poll models while pending even after inspection completes. Terminally failed models return unavailable even if measurement evidence was already completed. Retry the failed model with PATCH at the same size, or correct and replace its source.
manufacturing_estimate fields
status string · required
Allowed values: pending, unavailable, provisional
currency string · conditional
Always: "usd"
unit_price integer · conditional
Cents per printed copy; repair excluded.
Minimum: 0
longest_dimension_mm number · conditional
Minimum: 30 · Maximum: 200
pricing_version string · conditional
repair_cost_included boolean · conditional
Always: false
Exactly one of these conditions applies:
pending / unavailable
Absent fields: currency, unit_price, longest_dimension_mm, pricing_version, repair_cost_included.
status string · required
Allowed values: pending, unavailable
provisional
Required fields: currency, unit_price, longest_dimension_mm, pricing_version, repair_cost_included.
status string · required
Always: "provisional"
error object · optional
Terminal preparation failure. Completed inspection and pricing evidence remain available, but this model cannot be quoted until preparation succeeds.
error fields
code string · required
Allowed values: invalid_model_package, unreadable_model, missing_required_assets, unsupported_format, unsupported_model_features, invalid_geometry, processing_limit_exceeded, processing_timeout, inspection_unavailable, processing_failed, storage_unavailable
message string · required
Recovery instructions. Do not branch on message text.
Returned by
Example
JSON
{
"id": "MD-739YQ549",
"source": {
"file_id": "file_6c82bd3e319b4bb099310d54a761879e"
},
"name": "Wedding figurine",
"external_id": "design-123",
"created_at": "2026-09-18T18:00:00.000000Z",
"updated_at": "2026-09-18T18:00:00.000000Z",
"status": "processing",
"status_reasons": [
{
"code": "inspection_pending",
"message": "Mesh inspection is running."
}
],
"preview": {
"status": "pending"
},
"longest_dimension_mm": 100,
"mesh_check": {
"status": "pending"
},
"print_check": {
"status": "pending"
},
"repair": {
"required": false,
"applied": false,
"reason": null,
"status": "not_applied",
"fee": 0,
"covered_by_order_id": null
},
"progress": {
"stage": "queued"
},
"volume": null,
"estimated_weight_g": null
}API v1 preview