{ "openapi": "3.1.1", "info": { "title": "OTTO MFG API", "version": "2026-10-08", "description": "OTTO MFG API v1 preview.", "contact": { "name": "OTTO MFG support", "email": "help@ottomfg.com" } }, "servers": [ { "url": "https://api.ottomfg.com/api/v1", "description": "Production" } ], "tags": [ { "name": "Files", "description": "Register files and upload their bytes directly to storage." }, { "name": "Models", "description": "Create models from uploaded files and track inspection, revisions and repair." }, { "name": "Pricing", "description": "Calculate manufacturing prices for inspected models." }, { "name": "Quotes", "description": "Create and retrieve saved shipping quotes." }, { "name": "Orders", "description": "Create, pay, track and cancel orders." }, { "name": "Payments", "description": "List saved payment methods for order payments." } ], "paths": { "/files": { "post": { "operationId": "CreateFile", "tags": [ "Files" ], "summary": "Create a file", "description": "Create a file record and receive temporary upload instructions. Upload the bytes to the returned URL using the supplied form fields. Registration does not upload or validate the model. Idempotency-Key is optional; successful retries return the original snapshot for 24 hours.", "requestBody": { "required": true, "description": "Required upload metadata for pre-upload validation. Send file bytes separately using the signed instructions returned after these checks pass.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileInput" }, "examples": { "upload": { "summary": "ZIP upload metadata", "value": { "filename": "figurine.zip", "size_bytes": 10485760 } }, "glb": { "summary": "Self-contained GLB upload metadata", "value": { "filename": "figurine.glb", "size_bytes": 2097152 } } } } } }, "responses": { "200": { "description": "File registered; upload the bytes using the returned instructions. ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRegistration" }, "examples": { "upload": { "summary": "File reference and signed upload instructions", "value": { "upload": { "method": "POST", "url": "https://example-upload-bucket.s3.amazonaws.com/", "fields": { "key": "files/2a08c3d391244972a31a0f87d3821fa9/source", "policy": "GENERATED_POLICY", "x-amz-algorithm": "AWS4-HMAC-SHA256", "x-amz-credential": "GENERATED_CREDENTIAL_SCOPE", "x-amz-date": "20260921T180000Z", "x-amz-signature": "GENERATED_SIGNATURE", "x-amz-security-token": "GENERATED_SESSION_TOKEN", "success_action_status": "204" }, "expires_at": "2026-09-21T19:00:00Z" }, "id": "file_6c82bd3e319b4bb099310d54a761879e" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid JSON or metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "missingFilename": { "summary": "filename is required.", "value": { "code": "filename_required", "message": "filename is required." } }, "missingSize": { "summary": "size_bytes is required.", "value": { "code": "size_bytes_required", "message": "size_bytes is required." } }, "unsupportedExtension": { "summary": "Filename extension is not supported.", "value": { "code": "unsupported_file_extension", "message": "Use a .glb, .obj or .zip file." } }, "invalidSize": { "summary": "size_bytes must be a positive integer.", "value": { "code": "invalid_file_size", "message": "size_bytes must be a positive integer." } }, "tooLarge": { "summary": "Declared file size exceeds the upload limit.", "value": { "code": "file_too_large", "message": "Files cannot exceed 400000000 bytes (400 MB)." } }, "invalidArgument": { "value": { "code": "invalid_argument", "message": "Use filename and size_bytes only." } }, "invalidIdempotencyKey": { "summary": "Invalid retry key", "value": { "code": "invalid_argument", "message": "Idempotency-Key must be 1–255 visible ASCII characters." } } } } } }, "401": { "description": "API key is missing, invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer", "description": "Bearer authentication challenge." } } }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Verified caller lacks upload permission for the account, or uses an unsupported personal API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "summary": "permission_denied", "value": { "code": "permission_denied", "message": "This key requires the files:write scope." } } } } } }, "409": { "$ref": "#/components/responses/Response409" }, "413": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Metadata request exceeds 8192 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "tooLarge": { "value": { "code": "request_too_large", "message": "Metadata requests cannot exceed 8192 bytes." } } } } } }, "415": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Send application/json metadata; file bytes go directly to storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "value": { "code": "unsupported_media_type", "message": "Unsupported media type \"text/plain\" in request." } } } } } }, "429": { "description": "Account registration or unlinked storage limit reached. Retry-After is 60 seconds, but storage limits remain until reservations expire.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "summary": "resource_exhausted", "value": { "code": "resource_exhausted", "message": "File registration limit reached. Try again later." } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Delay in seconds before retrying. File registration currently returns 60." } } }, "500": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "summary": "internal", "value": { "code": "internal", "message": "File request failed." } } } } } }, "503": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "Required service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "summary": "unavailable", "value": { "code": "unavailable", "message": "File storage is temporarily unavailable." } } } } } } }, "security": [ { "ApiKeyAuth": [ "files:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "x-required-permission": "files:write" } }, "/prices": { "post": { "operationId": "CalculatePrices", "summary": "Calculate prices", "tags": [ "Pricing" ], "description": "Price inspected models at chosen sizes and quantities. Returns item prices and any repair fee in USD cents, without shipping or tax. Nothing is saved or charged. Business accounts get a fixed rate per cycle (3rd to 2nd, UTC); paid volume counts by calendar month after a two-day buffer. A failed or action_required model returns pricing_unavailable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceInput" }, "examples": { "configuration": { "summary": "Price configured models", "value": { "items": [ { "model_id": "MD-739YQ549", "quantity": 2, "longest_dimension_mm": 100 } ] } } } } } }, "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "description": "Ephemeral manufacturing prices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceCalculation" }, "examples": { "calculated": { "summary": "Two 12 g prints: $49.20; no repair fee", "value": { "currency": "usd", "pricing_version": "pv_support_v1_ebcc9b8b64eb5043", "items": [ { "model_id": "MD-739YQ549", "longest_dimension_mm": 100, "quantity": 2, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12, "mesh_check_passed": true, "unit_price": 2460, "subtotal": 4920, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "file_revision": 1, "support_volume": { "value_mm3": 0, "status": "estimated" }, "minimum_total_volume": { "value_mm3": 10000, "status": "estimated" }, "support_build_direction": "+y" } ], "subtotal": 4920, "estimated_production_business_days": null, "service_fees": { "mesh_repair": 0, "model_repair": 350 } } }, "repair_required": { "summary": "Two printed models with a repair fee", "value": { "currency": "usd", "pricing_version": "pv_support_v1_ebcc9b8b64eb5043", "items": [ { "model_id": "MD-739YQ549", "longest_dimension_mm": 100, "quantity": 2, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12, "mesh_check_passed": false, "unit_price": 2460, "subtotal": 4920, "repair": { "required": true, "applied": true, "reason": "inspection_failed", "status": "estimating", "fee": null, "covered_by_order_id": null }, "file_revision": 1, "support_volume": { "value_mm3": 0, "status": "estimated" }, "minimum_total_volume": { "value_mm3": 10000, "status": "estimated" }, "support_build_direction": "+y" } ], "subtotal": 4920, "estimated_production_business_days": null, "service_fees": { "mesh_repair": 0, "model_repair": 350 } } }, "inconclusive": { "summary": "Inconclusive inspection with usable volume; mesh repair required", "value": { "currency": "usd", "pricing_version": "pv_support_v1_ebcc9b8b64eb5043", "items": [ { "model_id": "MD-739YQ549", "longest_dimension_mm": 100, "quantity": 2, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12, "mesh_check_passed": null, "unit_price": 2460, "subtotal": 4920, "repair": { "required": true, "applied": true, "reason": "inspection_failed", "status": "estimating", "fee": null, "covered_by_order_id": null }, "file_revision": 1, "support_volume": { "value_mm3": 0, "status": "estimated" }, "minimum_total_volume": { "value_mm3": 10000, "status": "estimated" }, "support_build_direction": "+y" } ], "subtotal": 4920, "estimated_production_business_days": null, "service_fees": { "mesh_repair": 0, "model_repair": 350 } } }, "covered_revision": { "summary": "Repeat order: revision repair already paid", "value": { "currency": "usd", "pricing_version": "pv_support_v1_ebcc9b8b64eb5043", "service_fees": { "mesh_repair": 0, "model_repair": 350 }, "items": [ { "model_id": "MD-739YQ549", "file_revision": 1, "longest_dimension_mm": 100, "quantity": 2, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12, "mesh_check_passed": false, "unit_price": 2460, "subtotal": 4920, "repair": { "required": true, "applied": true, "reason": "covered", "status": "covered", "fee": 0, "covered_by_order_id": "OM-1EY18R95" }, "support_volume": { "value_mm3": 0, "status": "estimated" }, "minimum_total_volume": { "value_mm3": 10000, "status": "estimated" }, "support_build_direction": "+y" } ], "subtotal": 4920, "estimated_production_business_days": null } }, "multiple_sizes": { "summary": "Same model at 100 and 150 mm: one repair fee total", "value": { "currency": "usd", "pricing_version": "pv_support_v1_ebcc9b8b64eb5043", "items": [ { "model_id": "MD-739YQ549", "longest_dimension_mm": 100, "quantity": 2, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12, "mesh_check_passed": false, "unit_price": 2460, "subtotal": 4920, "repair": { "required": true, "applied": true, "reason": "inspection_failed", "status": "estimating", "fee": null, "covered_by_order_id": null }, "file_revision": 1, "support_volume": { "value_mm3": 0, "status": "estimated" }, "minimum_total_volume": { "value_mm3": 10000, "status": "estimated" }, "support_build_direction": "+y" }, { "model_id": "MD-739YQ549", "longest_dimension_mm": 150, "quantity": 1, "volume": { "value_mm3": 33750, "status": "estimated" }, "estimated_weight_g": 40.5, "mesh_check_passed": false, "unit_price": 4740, "subtotal": 4740, "repair": { "required": true, "applied": true, "reason": "inspection_failed", "status": "estimating", "fee": null, "covered_by_order_id": null }, "file_revision": 1, "support_volume": { "value_mm3": 0, "status": "estimated" }, "minimum_total_volume": { "value_mm3": 33750, "status": "estimated" }, "support_build_direction": "+y" } ], "subtotal": 9660, "estimated_production_business_days": null, "service_fees": { "mesh_repair": 0, "model_repair": 350 } } }, "support_heavy": { "summary": "Support-heavy model; manufacturing includes support", "value": { "currency": "usd", "pricing_version": "pv_support_v1_ebcc9b8b64eb5043", "items": [ { "model_id": "MD-739YQ549", "longest_dimension_mm": 100, "quantity": 2, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12, "mesh_check_passed": true, "unit_price": 3900, "subtotal": 7800, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "file_revision": 1, "support_volume": { "value_mm3": 40000, "status": "estimated" }, "minimum_total_volume": { "value_mm3": 50000, "status": "estimated" }, "support_build_direction": "+y" } ], "subtotal": 7800, "estimated_production_business_days": null, "service_fees": { "mesh_repair": 0, "model_repair": 350 } } } } } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Correct the input or inspect the referenced model. No partial basket is returned. pricing_unavailable is not a transient service outage; retrying unchanged inputs does not recompute inspection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_argument": { "summary": "Supply an integer quantity from 1 to 500.", "value": { "code": "invalid_argument", "message": "Supply an integer quantity from 1 to 500.", "details": [ { "field": "items[0].quantity", "message": "Supply an integer quantity from 1 to 500." } ] } }, "model_not_found": { "$ref": "#/components/examples/ModelNotFound" }, "pricing_unavailable": { "$ref": "#/components/examples/PricingUnavailable" } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "$ref": "#/components/examples/Unauthenticated" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer" } } }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "API key requires models:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "permission_denied": { "$ref": "#/components/examples/PermissionDenied" } } } } }, "409": { "description": "Retry-key conflict, or a referenced model is still processing (model_not_ready, model_repair_estimate_pending). Wait for the model to be ready, then retry.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/IdempotencyKeyReused" }, "idempotency_request_in_progress": { "$ref": "#/components/examples/IdempotencyRequestInProgress" }, "model_not_ready": { "$ref": "#/components/examples/ModelNotReady" }, "model_measurements_pending": { "$ref": "#/components/examples/ModelMeasurementsPending" } } } } }, "413": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "JSON request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "request_too_large": { "summary": "Pricing requests cannot exceed 65536 bytes.", "value": { "code": "request_too_large", "message": "Pricing requests cannot exceed 65536 bytes." } } } } } }, "415": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Send application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported_media_type": { "$ref": "#/components/examples/UnsupportedMediaType" } } } } }, "429": { "description": "600 pricing requests per minute per account, shared across all callers for that account. Retry after Retry-After seconds.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter_2" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "resource_exhausted": { "$ref": "#/components/examples/ResourceExhausted" } } } } }, "500": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Unexpected server failure; retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal": { "summary": "Pricing request failed.", "value": { "code": "internal", "message": "Pricing request failed." } } } } } }, "503": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "Temporary dependency failure; retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unavailable": { "summary": "Pricing storage is temporarily unavailable.", "value": { "code": "unavailable", "message": "Pricing storage is temporarily unavailable." } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "x-required-permission": "models:read", "security": [ { "ApiKeyAuth": [ "models:read" ] } ] } }, "/quotes": { "post": { "operationId": "CreateQuote", "tags": [ "Quotes" ], "summary": "Create a quote", "description": "Create a quote for inspected models, sizes, quantities and a US address. Returns manufacturing prices and USPS/UPS shipping options, without tax, valid for 30 minutes. No order, payment or repair job is created. Unordered quotes are kept for 30 days after expiry. A retry with the same Idempotency-Key returns the original quote for 24 hours.", "responses": { "200": { "description": "Saved quote with manufacturing and shipping totals in USD cents. Tax excluded; no charge is made. Shipping prices in this example are illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" }, "examples": { "example": { "$ref": "#/components/examples/Example" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid fields, unavailable model inputs or unsupported shipping. Correct the indicated field; pricing_unavailable is not a transient carrier error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_argument": { "summary": "Supply items, shipping_address and optional buyer only.", "value": { "code": "invalid_argument", "message": "Supply items, shipping_address and optional buyer only.", "details": [ { "field": "body", "message": "Supply items, shipping_address and optional buyer only." } ] } }, "model_not_found": { "$ref": "#/components/examples/ModelNotFound" }, "pricing_unavailable": { "$ref": "#/components/examples/PricingUnavailable" }, "shipping_unavailable": { "summary": "No supported shipping service is available for these items and destination.", "value": { "code": "shipping_unavailable", "message": "No supported shipping service is available for these items and destination.", "details": [ { "field": "shipping_address", "message": "No supported shipping service is available for these items and destination." } ] } }, "address_unverified": { "summary": "Shipping address could not be verified. Check the address and retry.", "value": { "code": "shipping_unavailable", "message": "Shipping address could not be verified. Check the address and retry.", "details": [ { "field": "shipping_address", "message": "Shipping address could not be verified. Check the address and retry." } ] } }, "parcel_limit": { "summary": "These items exceed the single-parcel limit of 150 lb including packing.", "value": { "code": "shipping_unavailable", "message": "These items exceed the single-parcel limit of 150 lb including packing.", "details": [ { "field": "shipping_address", "message": "These items exceed the single-parcel limit of 150 lb including packing." } ] } }, "invalid_key": { "summary": "Idempotency-Key must be 1–255 visible ASCII characters.", "value": { "code": "invalid_argument", "message": "Idempotency-Key must be 1–255 visible ASCII characters." } }, "invalid_zip": { "summary": "ZIP+4 or another invalid ZIP", "value": { "code": "invalid_argument", "message": "Supply a five-digit ZIP code.", "details": [ { "field": "shipping_address.postal_code", "message": "Supply a five-digit ZIP code." } ] } } } } } }, "401": { "$ref": "#/components/responses/Response401" }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Key lacks quotes:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "scope": { "summary": "This key requires the quotes:write scope.", "value": { "code": "permission_denied", "message": "This key requires the quotes:write scope." } } } } } }, "409": { "description": "Retry-key conflict, or a referenced model is still processing (model_not_ready, model_repair_estimate_pending). Wait for the model to be ready, then retry.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/IdempotencyKeyReused" }, "idempotency_request_in_progress": { "$ref": "#/components/examples/IdempotencyRequestInProgress" }, "model_not_ready": { "$ref": "#/components/examples/ModelNotReady" }, "model_measurements_pending": { "$ref": "#/components/examples/ModelMeasurementsPending" }, "model_repair_estimate_pending": { "$ref": "#/components/examples/ModelRepairEstimatePending" } } } } }, "413": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "JSON body exceeds 65,536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "too_large": { "summary": "Quote requests cannot exceed 65536 bytes.", "value": { "code": "request_too_large", "message": "Quote requests cannot exceed 65536 bytes." } } } } } }, "415": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Send application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unsupported": { "$ref": "#/components/examples/UnsupportedMediaType" } } } } }, "429": { "description": "10 admitted quote attempts per minute per account. shipping_rates_unavailable outcomes release their slot; other failures still count. Successful replays bypass this limit. In-flight attempts reserve slots until completion. Wait at least 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "rate_limit": { "summary": "Quote creation limit reached. Retry after 60 seconds.", "value": { "code": "resource_exhausted", "message": "Quote creation limit reached. Retry after 60 seconds." } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "description": "Minimum wait before retrying, in seconds.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "$ref": "#/components/responses/Response500" }, "503": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "Dependency temporarily unavailable. Retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "storage": { "$ref": "#/components/examples/Storage" }, "shipping": { "summary": "Shipping rates are temporarily unavailable; retry later.", "value": { "code": "shipping_rates_unavailable", "message": "Shipping rates are temporarily unavailable; retry later." } }, "in_progress": { "summary": "Quote creation is in progress. Retry with the same Idempotency-Key.", "value": { "code": "unavailable", "message": "Quote creation is in progress. Retry with the same Idempotency-Key." } }, "model_changed": { "summary": "Model inputs changed while quoting. Retry with the same Idempotency-Key.", "value": { "code": "unavailable", "message": "Model inputs changed while quoting. Retry with the same Idempotency-Key." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteInput" }, "examples": { "example": { "summary": "Quote two printed models for a US destination.", "value": { "items": [ { "model_id": "MD-739YQ549", "longest_dimension_mm": 100, "quantity": 2 } ], "shipping_address": { "name": "Test Recipient", "line1": "123 Example St", "city": "Seattle", "state": "WA", "postal_code": "98101", "country": "US" } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "x-required-permission": "quotes:write", "security": [ { "ApiKeyAuth": [ "quotes:write" ] } ] } }, "/quotes/{quote_id}": { "get": { "operationId": "GetQuote", "tags": [ "Quotes" ], "summary": "Get a quote", "description": "Retrieve the saved quote and original commercial terms with a current open/expired status. Prices and the 30-minute expiry never change. Unordered quotes become unavailable 30 days after expiry; order-linked quotes are retained. Only the owning account can retrieve a quote.", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/QuoteId" }, "description": "Public quote ID returned in id; pass unchanged.", "example": "quote_6c82bd3e319b4bb099310d54a761879e" } ], "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Saved quote with manufacturing and shipping totals in USD cents. Tax excluded; no charge is made. Shipping prices in this example are illustrative.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" }, "examples": { "example": { "$ref": "#/components/examples/Example" }, "expired": { "summary": "Expired quote, still within retention", "value": { "id": "quote_6c82bd3e319b4bb099310d54a761879e", "created_at": "2026-09-17T18:00:00.000000Z", "expires_at": "2026-09-17T18:30:00.000000Z", "currency": "usd", "items": [ { "model_id": "MD-739YQ549", "longest_dimension_mm": 100, "quantity": 2, "dimensions_mm": { "x": 100, "y": 50, "z": 20 }, "unit_price": 2460, "subtotal": 4920, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null } } ], "shipping_address": { "name": "Test Recipient", "line1": "123 EXAMPLE ST", "city": "SEATTLE", "state": "WA", "postal_code": "98101", "country": "US" }, "buyer": { "company": "Example Store", "email": "orders@example.com" }, "estimated_production_business_days": null, "shipping_options": [ { "id": "shipopt_6c82bd3e319b4bb099310d54a761879e", "name": "UPS Ground", "totals": { "subtotal": 4920, "shipping": 1000, "total": 5920 }, "estimated_transit_business_days": { "min": 3, "max": 3 }, "estimated_delivery": null, "carrier": "UPS" }, { "id": "shipopt_8c1f25d94e3142f8b9a70635d42c81e0", "name": "USPS Priority Mail Express", "totals": { "subtotal": 4920, "shipping": 2000, "total": 6920 }, "estimated_transit_business_days": { "min": 1, "max": 1 }, "estimated_delivery": null, "carrier": "USPS" } ], "pricing_version": "pv_20261001_model_repair_01", "status": "expired" } } } } } }, "401": { "$ref": "#/components/responses/Response401" }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Key lacks quotes:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "scope": { "summary": "This key requires the quotes:read scope.", "value": { "code": "permission_denied", "message": "This key requires the quotes:read scope." } } } } } }, "404": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Unknown, other-account or past-retention quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "not_found": { "value": { "code": "quote_not_found", "message": "Quote was not found." } } } } } }, "429": { "$ref": "#/components/responses/Response429" }, "500": { "$ref": "#/components/responses/Response500" }, "503": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "Dependency temporarily unavailable. Retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "storage": { "$ref": "#/components/examples/Storage" } } } } } }, "x-required-permission": "quotes:read", "security": [ { "ApiKeyAuth": [ "quotes:read" ] } ] } }, "/models": { "post": { "operationId": "CreateModel", "tags": [ "Models" ], "summary": "Create a model", "description": "Create a model from an uploaded file and its default longest dimension. Returns a permanent model ID immediately while inspection runs asynchronously. Retrieve the model for progress and results.", "requestBody": { "required": true, "description": "Required source.file_id and longest_dimension_mm; optional name/external_id/metadata. JSON body maximum 65536 bytes. Upload completion and ownership are checked atomically before registration. Use an optional Idempotency-Key to safely retry creation for 24 hours; unkeyed requests may create separate models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelInput" }, "examples": { "fromFile": { "summary": "Create from an uploaded, available File", "value": { "source": { "file_id": "file_6c82bd3e319b4bb099310d54a761879e" }, "name": "Wedding figurine", "external_id": "design-123", "longest_dimension_mm": 100 } }, "fractionalMillimeters": { "summary": "Fractional millimeters (caller converts units)", "value": { "source": { "file_id": "file_6c82bd3e319b4bb099310d54a761879e" }, "longest_dimension_mm": 101.6 } } } } } }, "responses": { "200": { "description": "Model with current progress and inspection results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisteredModel" }, "examples": { "accepted": { "$ref": "#/components/examples/Accepted" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid input. No model is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "summary": "invalid_argument", "value": { "code": "invalid_argument", "message": "Use source, longest_dimension_mm, name, external_id and metadata only.", "details": [ { "field": "body", "message": "Use source, longest_dimension_mm, name, external_id and metadata only." } ] } }, "fileNotReady": { "summary": "File not available yet; no Model registered", "value": { "code": "file_not_ready", "message": "Upload the file before creating a model.", "details": [ { "field": "source.file_id", "message": "Upload the file before creating a model." } ] } }, "file_not_found": { "summary": "Missing body-referenced File", "value": { "code": "file_not_found", "message": "File was not found.", "details": [ { "field": "source.file_id", "message": "File was not found." } ] } }, "missing_longest_dimension_mm": { "$ref": "#/components/examples/MissingLongestDimensionMm" }, "invalid_longest_dimension_mm": { "$ref": "#/components/examples/MissingLongestDimensionMm" }, "invalid_idempotency_key": { "summary": "Invalid idempotency key", "value": { "code": "invalid_argument", "message": "Idempotency-Key must be 1–255 visible ASCII characters." } } } } } }, "401": { "$ref": "#/components/responses/Response401_2" }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Account lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error_2" } } } } }, "409": { "$ref": "#/components/responses/Response409" }, "413": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Model requests cannot exceed 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error_3" } } } } }, "415": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Unsupported media type \"text/plain\" in request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/UnsupportedMediaType" } } } } }, "429": { "description": "Shared model creation, replacement and resize processing limit reached. Retry after 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error_4" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter_3" } } }, "500": { "$ref": "#/components/responses/Response500_2" }, "503": { "$ref": "#/components/responses/Response503" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "x-required-permission": "models:write", "security": [ { "ApiKeyAuth": [ "models:write" ] } ] }, "get": { "operationId": "ListModels", "summary": "List models", "tags": [ "Models" ], "description": "List the account's models, oldest update first, for synchronization. Filter by status, customer reference or update time; use sort=-created_at for newest first. Pages return data, has_more and next_cursor. Deleted models are omitted, even from updated_since results; use Get Model to confirm a missing ID. Listing does not start inspection or repair.", "parameters": [ { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "updated_at", "-created_at" ], "default": "updated_at" }, "description": "updated_at sorts oldest update first, with ascending id ties. -created_at sorts newest creation first, with descending id ties. Repeat the same sort on every cursor request; cursors cannot be reused across sort orders." }, { "name": "status", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/ModelStatus" } }, "description": "Comma-separated model statuses (OR): processing, ready, action_required, failed. Filters combine with AND. Omit status for full synchronization." }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "description": "", "format": "date-time" }, "description": "Inclusive lower bound on updated_at. Use an RFC 3339 timestamp with a timezone and at most six fractional digits. Repeat the same filters on subsequent pages." }, { "name": "external_id", "in": "query", "schema": { "type": "string", "description": "", "maxLength": 255 }, "description": "Exact, case-sensitive customer reference match. May return multiple models. An empty string matches an explicitly empty external_id, not an omitted field. Unicode category C characters are not accepted." }, { "$ref": "#/components/parameters/Limit" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "", "maxLength": 2048 }, "description": "Opaque next_cursor from a previous response for the same account. Has no time-based expiry; repeat the original filters and limit. Pages are live, not a frozen snapshot. Concurrent updates may reappear; deduplicate by id and updated_at." } ], "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "A live page of account models. An empty library returns data: [], has_more: false and next_cursor: null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisteredModelList" }, "examples": { "page": { "summary": "One registered model; no further page", "value": { "data": [ { "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": null, "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 } } ], "has_more": false, "next_cursor": null } }, "empty": { "summary": "No matching models", "value": { "data": [], "has_more": false, "next_cursor": null } } } } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid query parameter. Unknown or repeated parameters are rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_limit": { "summary": "Page size outside 1–100", "value": { "code": "invalid_argument", "message": "Supply an integer from 1 to 100.", "details": [ { "field": "limit", "message": "Supply an integer from 1 to 100." } ] } }, "invalid_cursor": { "summary": "Invalid cursor or cursor from another account", "value": { "code": "invalid_argument", "message": "Supply a valid next_cursor returned for this account.", "details": [ { "field": "cursor", "message": "Supply a valid next_cursor returned for this account." } ] } }, "invalid_status": { "summary": "Invalid status filter", "value": { "code": "invalid_argument", "message": "Supply unique comma-separated statuses: processing, ready, action_required, failed.", "details": [ { "field": "status", "message": "Supply unique comma-separated statuses: processing, ready, action_required, failed." } ] } } } } } }, "401": { "$ref": "#/components/responses/Response401_2" }, "403": { "$ref": "#/components/responses/Response403" }, "429": { "$ref": "#/components/responses/Response429" }, "500": { "$ref": "#/components/responses/Response500_2" }, "503": { "$ref": "#/components/responses/Response503" } }, "x-required-permission": "models:read", "security": [ { "ApiKeyAuth": [ "models:read" ] } ] } }, "/models/{model_id}": { "get": { "operationId": "GetModel", "tags": [ "Models" ], "summary": "Get a model", "description": "Retrieve current inspection progress, findings and estimated measurements. A completed inspection can report defects. Processing failures return HTTP 200 with mesh_check.error; use the response body to determine the outcome. Previews run independently: when preview.status is ready, preview.images contains all seven signed PNG URLs. Refresh this resource when the URLs expire.", "parameters": [ { "$ref": "#/components/parameters/ModelId" } ], "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "description": "Model with current progress and inspection results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisteredModel" }, "examples": { "queued": { "$ref": "#/components/examples/Accepted" }, "preparing": { "summary": "Preparing", "value": { "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": "preparing" }, "volume": null, "estimated_weight_g": null } }, "inspecting": { "summary": "Inspecting", "value": { "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": "processing" }, "longest_dimension_mm": 100, "mesh_check": { "status": "processing" }, "print_check": { "status": "pending" }, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "progress": { "stage": "inspecting" }, "volume": null, "estimated_weight_g": null } }, "inspection_complete": { "summary": "Inspection complete", "value": { "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": "measurements_pending", "message": "Model measurements are running." } ], "preview": { "status": "processing" }, "longest_dimension_mm": 100, "mesh_check": { "status": "completed", "result": { "passed": true, "inverted_normals": 0, "bad_edges": 0, "planar_holes": 0, "shells": 1, "near_bad_edges": null, "noise_shells": null, "incomplete_checks": [] } }, "print_check": { "status": "pending" }, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "progress": { "stage": "inspection_completed" }, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12 } }, "inspection_defects": { "summary": "Inspection defects", "value": { "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": "measurements_pending", "message": "Model measurements are running." } ], "preview": { "status": "processing" }, "longest_dimension_mm": 100, "mesh_check": { "status": "completed", "result": { "passed": false, "inverted_normals": 0, "bad_edges": 12, "planar_holes": 1, "shells": 1, "near_bad_edges": null, "noise_shells": null, "incomplete_checks": [] } }, "print_check": { "status": "pending" }, "repair": { "required": true, "applied": true, "reason": "inspection_failed", "status": "estimating", "fee": null, "covered_by_order_id": null }, "progress": { "stage": "inspection_completed" }, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12 } }, "inspection_incomplete": { "summary": "Inspection incomplete", "value": { "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": "measurements_pending", "message": "Model measurements are running." } ], "preview": { "status": "processing" }, "longest_dimension_mm": 100, "mesh_check": { "status": "completed", "result": { "passed": null, "inverted_normals": null, "bad_edges": 0, "planar_holes": 0, "shells": 1, "near_bad_edges": null, "noise_shells": null, "incomplete_checks": [ "inverted_normals" ] } }, "print_check": { "status": "pending" }, "repair": { "required": true, "applied": true, "reason": "inspection_failed", "status": "estimating", "fee": null, "covered_by_order_id": null }, "progress": { "stage": "inspection_completed" }, "volume": null, "estimated_weight_g": null } }, "intake_failed": { "summary": "Intake failed", "value": { "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": "failed", "status_reasons": [ { "code": "unreadable_model", "message": "The model could not be read. Export a new OBJ package or self-contained GLB." } ], "preview": { "status": "failed", "error": { "code": "preview_unavailable", "message": "A preview could not be prepared from this model." } }, "longest_dimension_mm": 100, "mesh_check": { "status": "failed", "error": { "code": "unreadable_model", "message": "The model could not be read. Export a new OBJ package or self-contained GLB." } }, "print_check": { "status": "pending" }, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "progress": { "stage": "failed" }, "volume": null, "estimated_weight_g": null } }, "preview_ready": { "summary": "Preview ready", "value": { "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": "measurements_pending", "message": "Model measurements are running." } ], "preview": { "status": "ready", "default_view": "angled", "expires_at": "2026-09-23T18:15:00Z", "images": { "angled": "https://assets.example.com/models/model_example/previews/angled.png?signature=example", "front": "https://assets.example.com/models/model_example/previews/front.png?signature=example", "back": "https://assets.example.com/models/model_example/previews/back.png?signature=example", "left": "https://assets.example.com/models/model_example/previews/left.png?signature=example", "right": "https://assets.example.com/models/model_example/previews/right.png?signature=example", "top": "https://assets.example.com/models/model_example/previews/top.png?signature=example", "bottom": "https://assets.example.com/models/model_example/previews/bottom.png?signature=example" }, "thumbnails": { "angled": "https://assets.example.com/models/model_example/previews/angled-384.webp?signature=example", "front": "https://assets.example.com/models/model_example/previews/front-384.webp?signature=example", "back": "https://assets.example.com/models/model_example/previews/back-384.webp?signature=example", "left": "https://assets.example.com/models/model_example/previews/left-384.webp?signature=example", "right": "https://assets.example.com/models/model_example/previews/right-384.webp?signature=example", "top": "https://assets.example.com/models/model_example/previews/top-384.webp?signature=example", "bottom": "https://assets.example.com/models/model_example/previews/bottom-384.webp?signature=example" }, "display": { "angled": "https://assets.example.com/models/model_example/previews/angled-1024.webp?signature=example", "front": "https://assets.example.com/models/model_example/previews/front-1024.webp?signature=example", "back": "https://assets.example.com/models/model_example/previews/back-1024.webp?signature=example", "left": "https://assets.example.com/models/model_example/previews/left-1024.webp?signature=example", "right": "https://assets.example.com/models/model_example/previews/right-1024.webp?signature=example", "top": "https://assets.example.com/models/model_example/previews/top-1024.webp?signature=example", "bottom": "https://assets.example.com/models/model_example/previews/bottom-1024.webp?signature=example" } }, "longest_dimension_mm": 100, "mesh_check": { "status": "completed", "result": { "passed": true, "inverted_normals": 0, "bad_edges": 0, "planar_holes": 0, "shells": 1, "near_bad_edges": null, "noise_shells": null, "incomplete_checks": [] } }, "print_check": { "status": "pending" }, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "progress": { "stage": "inspection_completed" }, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12 } }, "preview_failed": { "summary": "Preview failed", "value": { "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": "measurements_pending", "message": "Model measurements are running." } ], "preview": { "status": "failed", "error": { "code": "preview_unavailable", "message": "Preview images could not be generated. Inspection and pricing are unaffected. Contact support with the model ID." } }, "longest_dimension_mm": 100, "mesh_check": { "status": "completed", "result": { "passed": true, "inverted_normals": 0, "bad_edges": 0, "planar_holes": 0, "shells": 1, "near_bad_edges": null, "noise_shells": null, "incomplete_checks": [] } }, "print_check": { "status": "pending" }, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "progress": { "stage": "inspection_completed" }, "volume": { "value_mm3": 10000, "status": "estimated" }, "estimated_weight_g": 12 } } } } } }, "401": { "$ref": "#/components/responses/Response401_3" }, "403": { "$ref": "#/components/responses/Response403" }, "404": { "$ref": "#/components/responses/Response404" }, "429": { "$ref": "#/components/responses/Response429" }, "500": { "$ref": "#/components/responses/Response500_2" }, "503": { "$ref": "#/components/responses/Response503" } }, "x-required-permission": "models:read", "security": [ { "ApiKeyAuth": [ "models:read" ] } ] }, "patch": { "operationId": "UpdateModel", "tags": [ "Models" ], "summary": "Update a model", "description": "Rename or resize a model. Send the ETag from Get Model in If-Match; a stale value returns 412 precondition_failed, and without If-Match the last write wins. A size change clears checks and prices and inspects the model again. A failed model can retry without a new upload. Existing orders are unchanged. PATCH has no idempotent replay.", "security": [ { "ApiKeyAuth": [ "models:write" ] } ], "x-required-permission": "models:write", "parameters": [ { "$ref": "#/components/parameters/ModelId_2" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "ETag from GetModel. The edit applies only while that version is current; otherwise 412 precondition_failed. Omit for last-write-wins." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelUpdate" }, "examples": { "rename": { "summary": "Rename using the current timestamp", "value": { "name": "Wedding figurine" } }, "resize": { "summary": "Change the saved longest dimension", "value": { "longest_dimension_mm": 120 } } } } } }, "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "description": "Updated model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisteredModel" }, "examples": { "renamed": { "summary": "Renamed model with its existing processing state", "value": { "id": "MD-739YQ549", "file_revision": 1, "source": { "file_id": "file_6c82bd3e319b4bb099310d54a761879e" }, "name": "Wedding figurine", "created_at": "2026-09-18T18:00:00.000000Z", "updated_at": "2026-09-30T00:01: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 } } } } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid fields, name or size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "body": { "summary": "Supply name and/or longest_dimension_mm.", "value": { "code": "invalid_argument", "message": "Supply name and/or longest_dimension_mm.", "details": [ { "field": "body", "message": "Supply name and/or longest_dimension_mm." } ] } }, "name": { "summary": "Enter a model name.", "value": { "code": "invalid_argument", "message": "Enter a model name.", "details": [ { "field": "name", "message": "Enter a model name." } ] } } } } } }, "401": { "$ref": "#/components/responses/Response401_4" }, "403": { "$ref": "#/components/responses/Response403_2" }, "404": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Model absent, deleted or owned by another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "not_found": { "$ref": "#/components/examples/NotFound" } } } } }, "409": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Request conflict or model not ready for the requested change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "model_not_ready": { "summary": "Inspection must complete before resizing", "value": { "code": "model_not_ready", "message": "Wait for model processing before changing size." } } } } } }, "412": { "$ref": "#/components/responses/Response412" }, "413": { "$ref": "#/components/responses/Response413" }, "415": { "$ref": "#/components/responses/Response415" }, "429": { "description": "Shared per-account creation, replacement and resize processing limit reached, including same-size retries of failed models. Renames and no-op saves do not consume the limit. Retry-After: 60 seconds.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "rate_limit": { "value": { "code": "resource_exhausted", "message": "Model processing limit reached. Retry after 60 seconds." } } } } } }, "500": { "$ref": "#/components/responses/Response500_2" }, "503": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error_5" } } } } } } }, "delete": { "operationId": "DeleteModel", "summary": "Delete a model", "tags": [ "Models" ], "description": "Soft-delete a model owned by your account. Returns its ID and deleted: true; subsequent lookup and repeated deletion return 404, and lists exclude it. The linked file remains protected. A model referenced by any order, including a cancelled order, cannot be deleted.", "parameters": [ { "$ref": "#/components/parameters/ModelId" } ], "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Model deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedModel" }, "examples": { "deleted": { "summary": "Soft deletion acknowledged", "value": { "id": "MD-739YQ549", "deleted": true } } } } } }, "401": { "$ref": "#/components/responses/Response401_3" }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "API key lacks models:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "missing_scope": { "summary": "Write scope required", "value": { "code": "permission_denied", "message": "This key requires the models:write scope." } } } } } }, "404": { "$ref": "#/components/responses/Response404" }, "409": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Action conflicts with current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "model_in_use": { "summary": "An order references this model; it cannot be deleted.", "value": { "code": "model_in_use", "message": "An order references this model; it cannot be deleted." } } } } } }, "500": { "$ref": "#/components/responses/Response500_2" }, "503": { "$ref": "#/components/responses/Response503" } }, "x-required-permission": "models:write", "security": [ { "ApiKeyAuth": [ "models:write" ] } ] } }, "/models/{model_id}/revisions": { "get": { "operationId": "ListModelRevisions", "tags": [ "Models" ], "summary": "List model file revisions", "description": "Owner-only immutable source history, newest revision first. Use limit (1–100, default 20) and cursor. Returns data, has_more and next_cursor. Names and sizes remain current model settings. Missing or deleted models return 404 model_not_found.", "security": [ { "ApiKeyAuth": [ "models:read" ] } ], "x-required-permission": "models:read", "parameters": [ { "$ref": "#/components/parameters/ModelId_2" }, { "$ref": "#/components/parameters/Limit_2" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Revision page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelFileRevisionPage" }, "examples": { "history": { "summary": "Uploads, with a model repair of revision 2 as the current file", "value": { "data": [ { "number": 2, "label": "2", "source": { "file_id": "file_7c82bd3e319b4bb099310d54a761879e" }, "filename": "figurine-v2.zip", "created_at": "2026-09-30T00:01:00.000000Z", "current": false, "repairs": [ { "repair": 1, "label": "2.1", "source": { "file_id": "file_8c82bd3e319b4bb099310d54a761879e" }, "filename": "figurine-v2-repaired.zip", "created_at": "2026-10-03T09:00:00.000000Z", "current": true } ] }, { "number": 1, "label": "1", "source": { "file_id": "file_6c82bd3e319b4bb099310d54a761879e" }, "filename": "figurine.zip", "created_at": "2026-09-18T18:00:00.000000Z", "current": false, "repairs": [] } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid limit or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "cursor": { "summary": "Supply a valid revision cursor.", "value": { "code": "invalid_argument", "message": "Supply a valid revision cursor.", "details": [ { "field": "cursor", "message": "Supply a valid revision cursor." } ] } } } } } }, "401": { "$ref": "#/components/responses/Response401_4" }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "models:read permission required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/PermissionDenied" } } } } }, "404": { "$ref": "#/components/responses/Response404_2" }, "429": { "description": "Read limit reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "value": { "code": "resource_exhausted", "message": "Read limit reached." } } } } } }, "500": { "$ref": "#/components/responses/Response500_2" }, "503": { "description": "Dependency temporarily unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "value": { "code": "unavailable", "message": "Dependency temporarily unavailable." } } } } } } } }, "post": { "operationId": "ReplaceModelFile", "tags": [ "Models" ], "summary": "Replace a model file", "description": "Append an immutable source-file revision to an owned model and restart processing. Send If-Match from GetModel to guard against concurrent edits; omit for last-write-wins. Idempotency-Key is optional, retained for 24 hours, and replays the original response snapshot. The model ID stays the same. Repair coverage remains attached to the original file revision.", "security": [ { "ApiKeyAuth": [ "models:write" ] } ], "x-required-permission": "models:write", "parameters": [ { "$ref": "#/components/parameters/ModelId_2" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "ETag from GetModel. The edit applies only while that version is current; otherwise 412 precondition_failed. Omit for last-write-wins. A replay with the same Idempotency-Key returns the original response even if the model has since changed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelReplacement" }, "examples": { "replacement": { "summary": "Replace an uploaded source using the current timestamp", "value": { "source": { "file_id": "file_7c82bd3e319b4bb099310d54a761879e" } } } } } } }, "responses": { "200": { "description": "Current model after replacement.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisteredModel" }, "examples": { "queued": { "summary": "New file revision queued for inspection", "value": { "id": "MD-739YQ549", "file_revision": 2, "source": { "file_id": "file_7c82bd3e319b4bb099310d54a761879e" }, "name": "Wedding figurine", "created_at": "2026-09-18T18:00:00.000000Z", "updated_at": "2026-09-30T00:01: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 } } } } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid input or unusable uploaded file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "file_not_found": { "value": { "code": "file_not_found", "message": "File was not found.", "details": [ { "field": "source.file_id", "message": "File was not found." } ] } } } } } }, "401": { "$ref": "#/components/responses/Response401_4" }, "403": { "$ref": "#/components/responses/Response403_2" }, "404": { "$ref": "#/components/responses/Response404_2" }, "409": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "Request conflict or model not ready for the requested change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/IdempotencyKeyReused" }, "idempotency_request_in_progress": { "$ref": "#/components/examples/IdempotencyRequestInProgress" } } } } }, "412": { "$ref": "#/components/responses/Response412" }, "413": { "$ref": "#/components/responses/Response413" }, "415": { "$ref": "#/components/responses/Response415" }, "429": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter_3" } }, "description": "Shared per-account creation, replacement and resize processing limit reached. Retry-After: 60 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error_4" } } } } }, "500": { "$ref": "#/components/responses/Response500_2" }, "503": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "File storage temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error_5" } } } } } } } }, "/orders": { "post": { "operationId": "CreateOrder", "tags": [ "Orders" ], "summary": "Create an order", "description": "Accept an open quote and one shipping option to create an order with fixed terms, status awaiting_payment and expires_at 24 hours after creation. Payment starts separately. An Idempotency-Key is required; replays return the original order.", "responses": { "200": { "description": "Order with complete inline event history and one optional shipment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "pending": { "$ref": "#/components/examples/Pending" }, "repair_pending": { "summary": "Order accepted after inspection; repair running and payment unpaid", "value": { "id": "OM-XMF1NT2E", "created_at": "2026-09-18T18:00:00.000000Z", "quote_id": "quote_6c82bd3e319b4bb099310d54a761879e", "currency": "usd", "items": [ { "model_id": "MD-739YQ549", "quantity": 2, "unit_price": 3000, "subtotal": 6000, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "dimensions_mm": { "x": 50, "y": 100, "z": 40 }, "longest_dimension_mm": 100 } ], "shipping_address": { "name": "Alex Example", "company": "Example Retail", "line1": "123 Example Street", "city": "Seattle", "state": "WA", "postal_code": "98101", "country": "US" }, "buyer": { "company": "Example Store", "email": "orders@example.com" }, "shipping_option": { "id": "shipopt_6c82bd3e319b4bb099310d54a761879e", "name": "Standard", "totals": { "subtotal": 6000, "shipping": 1000, "total": 7000 }, "estimated_transit_business_days": { "min": 3, "max": 5 }, "estimated_delivery": null }, "external_id": "checkout-123", "purchase_order_number": "PO-2026-0042", "metadata": { "project": "launch" }, "updated_at": "2026-09-18T18:00:00.000000Z", "status": "awaiting_payment", "events": [ { "id": "evt_00000000000000000000000000000001", "sequence": 1, "type": "order.created", "at": "2026-09-18T18:00:00.000000Z", "reason": null, "data": { "status": "awaiting_payment" } } ], "estimated_ship_date": null, "estimated_delivery": null, "hold": null, "payment": { "status": "unpaid", "amount": 7000, "currency": "usd", "method": null, "paid_at": null, "receipt_url": null }, "shipment": null, "pricing_version": "pv_2026_09_a", "preparation": { "status": "processing", "items": [ { "model_id": "MD-739YQ549", "status": "processing", "longest_dimension_mm": 100 } ] }, "expires_at": "2026-09-19T18:00:00.000000Z" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_argument": { "$ref": "#/components/examples/InvalidArgument" }, "quote_not_found": { "summary": "quote not found", "value": { "code": "quote_not_found", "message": "Quote was not found.", "details": [ { "field": "quote_id", "message": "Quote was not found." } ] } } } } } }, "401": { "$ref": "#/components/responses/Response401_5" }, "403": { "$ref": "#/components/responses/Response403_3" }, "409": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "Coverage is revalidated at order creation. Pay or cancel a pending repair order before ordering that revision again. A changed body under the same Idempotency-Key returns idempotency_key_reused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "repair_payment_pending": { "summary": "Another order has an unpaid revision repair fee", "value": { "code": "repair_payment_pending", "message": "Pay or cancel the existing order's repair before ordering this revision again." } }, "repair_coverage_changed": { "summary": "Quoted repair coverage changed", "value": { "code": "quote_unavailable", "message": "Repair coverage changed. Create a new quote." } }, "quote_expired": { "summary": "quote expired", "value": { "code": "quote_expired", "message": "Quote has expired. Create a new quote." } }, "quote_unavailable": { "summary": "quote unavailable", "value": { "code": "quote_unavailable", "message": "A quoted model is no longer available." } }, "quote_accepted": { "summary": "Quote already has a non-cancelled order", "value": { "code": "quote_accepted", "message": "Quote already has an order. Use the existing order or create a new quote.", "details": [ { "field": "quote_id", "message": "Only cancelled orders allow reuse of an unexpired quote." } ] } }, "model_repair_estimate_pending": { "$ref": "#/components/examples/ModelRepairEstimatePending" }, "idempotency_key_reused": { "$ref": "#/components/examples/IdempotencyKeyReused" }, "idempotency_request_in_progress": { "$ref": "#/components/examples/IdempotencyRequestInProgress" } } } } }, "413": { "$ref": "#/components/responses/Response413_2" }, "415": { "$ref": "#/components/responses/Response415" }, "429": { "$ref": "#/components/responses/Response429_2" }, "500": { "$ref": "#/components/responses/Response500_3" }, "503": { "$ref": "#/components/responses/Response503_2" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInput" }, "examples": { "example": { "summary": "Accept Standard shipping from the quote", "value": { "quote_id": "quote_6c82bd3e319b4bb099310d54a761879e", "shipping_option_id": "shipopt_6c82bd3e319b4bb099310d54a761879e", "external_id": "checkout-123", "purchase_order_number": "PO-2026-0042", "metadata": { "project": "launch" } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey_2" } ], "x-required-permission": "orders:write", "security": [ { "ApiKeyAuth": [ "orders:write" ] } ] }, "get": { "operationId": "ListOrders", "tags": [ "Orders" ], "summary": "List orders", "description": "List orders owned by the authenticated account, ordered by updated_at then ID. Returns data, has_more and next_cursor. Keep filters unchanged while paging; payment changes also update updated_at.", "parameters": [ { "name": "status", "in": "query", "style": "form", "explode": false, "schema": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/OrderStatus" } }, "description": "Comma-separated statuses, e.g. awaiting_payment,confirmed. OR across values; AND with time filters. Omit for full reconciliation." }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower bound on domain updated_at; repeat on subsequent pages.", "example": "2026-09-18T00:00:00.000000Z" }, { "$ref": "#/components/parameters/Limit" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "" }, "description": "Stateless keyset token containing the last updated_at and id. Never expires; repeat original filters and limit. No frozen snapshot." }, { "name": "external_id", "in": "query", "required": false, "description": "Exact optional customer reference. Not unique.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "model_id", "in": "query", "description": "Only orders containing this model, including its historical revisions.", "schema": { "$ref": "#/components/schemas/ModelId" } }, { "name": "search", "in": "query", "description": "Case-insensitive substring search across order number, recipient name, external reference and purchase order number.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "sort", "in": "query", "description": "Ascending update time for synchronization (default), or newest orders first. Keep all filters and sort unchanged when using a cursor.", "schema": { "type": "string", "enum": [ "updated_at", "-created_at" ], "default": "updated_at" } } ], "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Live order page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" }, "examples": { "page": { "summary": "Live order page", "value": { "data": [ { "id": "OM-XMF1NT2E", "created_at": "2026-09-18T18:00:00.000000Z", "quote_id": "quote_6c82bd3e319b4bb099310d54a761879e", "currency": "usd", "items": [ { "model_id": "MD-739YQ549", "quantity": 2, "unit_price": 3000, "subtotal": 6000, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "longest_dimension_mm": 100, "dimensions_mm": { "x": 50, "y": 100, "z": 40 } } ], "shipping_address": { "name": "Alex Example", "company": "Example Retail", "line1": "123 Example Street", "city": "Seattle", "state": "WA", "postal_code": "98101", "country": "US" }, "buyer": { "company": "Example Store", "email": "orders@example.com" }, "shipping_option": { "id": "shipopt_6c82bd3e319b4bb099310d54a761879e", "name": "Standard", "totals": { "subtotal": 6000, "shipping": 1000, "total": 7000 }, "estimated_transit_business_days": { "min": 3, "max": 5 }, "estimated_delivery": null }, "external_id": "checkout-123", "purchase_order_number": "PO-2026-0042", "metadata": { "project": "launch" }, "updated_at": "2026-09-18T18:00:00.000000Z", "status": "awaiting_payment", "events": [ { "id": "evt_00000000000000000000000000000001", "sequence": 1, "type": "order.created", "at": "2026-09-18T18:00:00.000000Z", "reason": null, "data": { "status": "awaiting_payment" } } ], "estimated_ship_date": null, "estimated_delivery": null, "hold": null, "payment": { "status": "unpaid", "amount": 7000, "currency": "usd", "method": null, "paid_at": null, "receipt_url": null }, "shipment": null, "pricing_version": "pv_2026_09_a", "preparation": { "status": "completed", "items": [ { "model_id": "MD-739YQ549", "status": "completed", "longest_dimension_mm": 100 } ] }, "expires_at": "2026-09-19T18:00:00.000000Z" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/Response400" }, "401": { "$ref": "#/components/responses/Response401_5" }, "403": { "$ref": "#/components/responses/Response403_4" }, "429": { "$ref": "#/components/responses/Response429" }, "500": { "$ref": "#/components/responses/Response500_3" }, "503": { "$ref": "#/components/responses/Response503_2" } }, "x-required-permission": "orders:read", "security": [ { "ApiKeyAuth": [ "orders:read" ] } ] } }, "/orders/{order_id}": { "get": { "operationId": "GetOrder", "tags": [ "Orders" ], "summary": "Get an order", "description": "Retrieve an order’s accepted terms, current payment state and event history. Payment and refund status may update asynchronously. Returns 404 for unknown or other-account orders; payment continuation URLs and client secrets are excluded.", "parameters": [ { "$ref": "#/components/parameters/OrderId" } ], "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Order with complete inline event history and one optional shipment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "pending": { "$ref": "#/components/examples/Pending" }, "confirmed": { "summary": "Confirmed; can be cancelled", "value": { "id": "OM-XMF1NT2E", "created_at": "2026-09-18T18:00:00.000000Z", "quote_id": "quote_6c82bd3e319b4bb099310d54a761879e", "currency": "usd", "items": [ { "model_id": "MD-739YQ549", "quantity": 2, "unit_price": 3000, "subtotal": 6000, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "longest_dimension_mm": 100, "dimensions_mm": { "x": 50, "y": 100, "z": 40 } } ], "shipping_address": { "name": "Alex Example", "company": "Example Retail", "line1": "123 Example Street", "city": "Seattle", "state": "WA", "postal_code": "98101", "country": "US" }, "buyer": { "company": "Example Store", "email": "orders@example.com" }, "shipping_option": { "id": "shipopt_6c82bd3e319b4bb099310d54a761879e", "name": "Standard", "totals": { "subtotal": 6000, "shipping": 1000, "total": 7000 }, "estimated_transit_business_days": { "min": 3, "max": 5 }, "estimated_delivery": null }, "external_id": "checkout-123", "purchase_order_number": "PO-2026-0042", "metadata": { "project": "launch" }, "updated_at": "2026-09-18T18:01:00.000000Z", "status": "confirmed", "events": [ { "id": "evt_00000000000000000000000000000001", "sequence": 1, "type": "order.created", "at": "2026-09-18T18:00:00.000000Z", "reason": null, "data": { "status": "awaiting_payment" } }, { "id": "evt_00000000000000000000000000000002", "sequence": 2, "type": "order.confirmed", "at": "2026-09-18T18:01:00.000000Z", "reason": null, "data": { "previous_status": "awaiting_payment", "status": "confirmed" } } ], "estimated_ship_date": null, "estimated_delivery": null, "hold": null, "payment": { "status": "paid", "amount": 7000, "currency": "usd", "method": { "id": "pm_example", "brand": "visa", "last4": "4242" }, "paid_at": "2026-09-18T18:00:00.000000Z", "receipt_url": null }, "shipment": null, "pricing_version": "pv_2026_09_a", "preparation": { "status": "completed", "items": [ { "model_id": "MD-739YQ549", "status": "completed", "longest_dimension_mm": 100 } ] }, "expires_at": null } }, "cancelled": { "$ref": "#/components/examples/Cancelled" }, "paid_repair_pending": { "summary": "Paid while repair remains pending; manufacturing still blocked", "value": { "id": "OM-XMF1NT2E", "created_at": "2026-09-18T18:00:00.000000Z", "quote_id": "quote_6c82bd3e319b4bb099310d54a761879e", "currency": "usd", "items": [ { "model_id": "MD-739YQ549", "quantity": 2, "unit_price": 3000, "subtotal": 6000, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "dimensions_mm": { "x": 50, "y": 100, "z": 40 }, "longest_dimension_mm": 100 } ], "shipping_address": { "name": "Alex Example", "company": "Example Retail", "line1": "123 Example Street", "city": "Seattle", "state": "WA", "postal_code": "98101", "country": "US" }, "buyer": { "company": "Example Store", "email": "orders@example.com" }, "shipping_option": { "id": "shipopt_6c82bd3e319b4bb099310d54a761879e", "name": "Standard", "totals": { "subtotal": 6000, "shipping": 1000, "total": 7000 }, "estimated_transit_business_days": { "min": 3, "max": 5 }, "estimated_delivery": null }, "external_id": "checkout-123", "purchase_order_number": "PO-2026-0042", "metadata": { "project": "launch" }, "updated_at": "2026-09-18T18:00:00.000000Z", "status": "confirmed", "events": [ { "id": "evt_00000000000000000000000000000001", "sequence": 1, "type": "order.created", "at": "2026-09-18T18:00:00.000000Z", "reason": null, "data": { "status": "awaiting_payment" } }, { "id": "evt_00000000000000000000000000000002", "sequence": 2, "type": "order.confirmed", "at": "2026-09-18T18:01:00.000000Z", "reason": null, "data": { "previous_status": "awaiting_payment", "status": "confirmed" } } ], "estimated_ship_date": null, "estimated_delivery": null, "hold": null, "payment": { "status": "paid", "amount": 7000, "currency": "usd", "method": { "id": "pm_example", "brand": "visa", "last4": "4242" }, "paid_at": "2026-09-18T18:00:00.000000Z", "receipt_url": "https://payments.example.com/receipt/example" }, "shipment": null, "pricing_version": "pv_2026_09_a", "preparation": { "status": "processing", "items": [ { "model_id": "MD-739YQ549", "status": "processing", "longest_dimension_mm": 100 } ] }, "expires_at": null } } } } } }, "401": { "$ref": "#/components/responses/Response401_5" }, "403": { "$ref": "#/components/responses/Response403_4" }, "404": { "$ref": "#/components/responses/Response404_3" }, "429": { "$ref": "#/components/responses/Response429" }, "500": { "$ref": "#/components/responses/Response500_3" }, "503": { "$ref": "#/components/responses/Response503_2" } }, "x-required-permission": "orders:read", "security": [ { "ApiKeyAuth": [ "orders:read" ] } ] } }, "/orders/{order_id}/invoice": { "get": { "operationId": "GetOrderInvoice", "tags": [ "Orders" ], "summary": "Download an order invoice", "description": "Download the PDF invoice of a paid order. The invoice is issued once, when payment succeeds, and does not change. An unpaid order returns 409 invoice_unavailable. Errors are JSON.", "parameters": [ { "$ref": "#/components/parameters/OrderId" } ], "responses": { "200": { "description": "PDF invoice, named INV-.pdf.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Content-Disposition": { "description": "attachment; filename=\"INV-XMF1NT2E.pdf\"", "schema": { "type": "string" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Codes: unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "$ref": "#/components/examples/Error" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } } }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Codes: permission_denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "permission_denied": { "$ref": "#/components/examples/PermissionDenied_2" } } } } }, "404": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Codes: order_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "not_found": { "$ref": "#/components/examples/NotFound_2" } } } } }, "406": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "The Accept header excludes application/json and application/pdf.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "not_acceptable": { "summary": "Unsupported Accept header", "value": { "code": "not_acceptable", "message": "Could not satisfy the request Accept header." } } } } } }, "409": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "No paid invoice exists for this order yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invoice_unavailable": { "summary": "Order is not paid", "value": { "code": "invoice_unavailable", "message": "A paid invoice is not available for this order." } } } } } }, "429": { "description": "600 GET/HEAD requests per minute per API key, shared across read endpoints. Code: resource_exhausted. Retry after the number of seconds in Retry-After.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter_2" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "resource_exhausted": { "$ref": "#/components/examples/ResourceExhausted" } } } } }, "500": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Codes: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal": { "$ref": "#/components/examples/Internal" } } } } }, "503": { "description": "Codes: unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unavailable": { "$ref": "#/components/examples/Unavailable" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-required-permission": "orders:read", "security": [ { "ApiKeyAuth": [ "orders:read" ] } ] } }, "/orders/{order_id}/cancel": { "post": { "operationId": "CancelOrder", "tags": [ "Orders" ], "summary": "Cancel an order", "description": "Cancel an awaiting-payment or confirmed order. Production dispatch is not enabled. If other active orders use its paid mesh repair, cancel those dependent orders first; otherwise 409 cancellation_unavailable is returned. Successful cancellation of a paid order refunds the full amount, including shipping; refunds can complete asynchronously. Repeated cancellation returns 409. After a lost response, retrieve the existing order.", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderInput" }, "example": { "reason": "Customer no longer needs the parts." } } } }, "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "description": "Cancelled order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "cancelled": { "$ref": "#/components/examples/Cancelled" } } } } }, "400": { "$ref": "#/components/responses/Response400" }, "401": { "$ref": "#/components/responses/Response401_5" }, "403": { "$ref": "#/components/responses/Response403_3" }, "404": { "$ref": "#/components/responses/Response404_3" }, "409": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "Conflicts with the resource's current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "repair_dependents": { "summary": "Other orders depend on this paid repair", "value": { "code": "cancellation_unavailable", "message": "Other orders use this revision's paid repair. Cancel those orders first." } }, "cancellation_unavailable": { "summary": "cancellation unavailable", "value": { "code": "cancellation_unavailable", "message": "Only awaiting-payment or confirmed orders can be cancelled." } }, "idempotency_key_reused": { "$ref": "#/components/examples/IdempotencyKeyReused" }, "idempotency_request_in_progress": { "$ref": "#/components/examples/IdempotencyRequestInProgress" } } } } }, "413": { "$ref": "#/components/responses/Response413_2" }, "415": { "$ref": "#/components/responses/Response415" }, "429": { "$ref": "#/components/responses/Response429_2" }, "500": { "$ref": "#/components/responses/Response500_3" }, "503": { "$ref": "#/components/responses/Response503_2" } }, "x-required-permission": "orders:write", "security": [ { "ApiKeyAuth": [ "orders:write" ] } ] } }, "/orders/{order_id}/payments": { "post": { "operationId": "PayOrder", "tags": [ "Orders" ], "summary": "Pay an order", "description": "Pay an existing order’s accepted total through hosted Checkout or an approved saved card. Requires explicit API spending authorization and payments:write. Required Idempotency-Key protects retries for 24 hours; only one collection can be active per order. Declines and customer verification return payment state, not a new order.", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrderId" } }, { "$ref": "#/components/parameters/IdempotencyKey_2" } ], "x-required-permission": "payments:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentInput" }, "examples": { "checkout": { "value": { "type": "checkout" } }, "saved_card": { "value": { "type": "saved_method", "payment_method_id": "pm_example" } } } } } }, "responses": { "200": { "description": "Payment state and optional interaction required; success of this HTTP call does not imply paid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAction" }, "examples": { "checkout": { "value": { "order_id": "OM-XMF1NT2E", "payment": { "status": "requires_action", "amount": 7000, "currency": "usd", "method": null, "paid_at": null, "receipt_url": null }, "next_action": { "type": "redirect", "url": "https://payments.example.com/checkout/example", "expires_at": "2026-09-18T19:00:00.000000Z" } } }, "paid": { "value": { "order_id": "OM-XMF1NT2E", "payment": { "status": "paid", "amount": 7000, "currency": "usd", "method": { "id": "pm_example", "brand": "visa", "last4": "4242" }, "paid_at": "2026-09-18T18:00:00.000000Z", "receipt_url": "https://payments.example.com/receipt/example" }, "next_action": null } }, "declined": { "value": { "order_id": "OM-XMF1NT2E", "payment": { "status": "failed", "amount": 7000, "currency": "usd", "method": null, "paid_at": null, "receipt_url": null, "error": { "code": "card_declined", "message": "Choose another payment method on the same order." } }, "next_action": null } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } } }, "400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_argument": { "$ref": "#/components/examples/InvalidArgument" }, "payment_method_not_found": { "summary": "payment method not found", "value": { "code": "payment_method_not_found", "message": "An approved payment method was not found for this account.", "details": [ { "field": "payment_method_id", "message": "Use a card saved under the owning account." } ] } } } } } }, "401": { "$ref": "#/components/responses/Response401_5" }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "The API key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "permission_denied": { "summary": "permission denied", "value": { "code": "permission_denied", "message": "This key requires the payments:write scope." } } } } } }, "404": { "$ref": "#/components/responses/Response404_3" }, "409": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "description": "payment_method_unavailable: update the saved card in Billing. A changed body under the same Idempotency-Key returns idempotency_key_reused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "payment_unavailable": { "summary": "payment unavailable", "value": { "code": "payment_unavailable", "message": "This order is cancelled." } }, "payment_in_progress": { "summary": "payment in progress", "value": { "code": "payment_in_progress", "message": "Resolve the current payment before choosing a different payment method." } }, "payment_reconciliation_required": { "summary": "payment reconciliation required", "value": { "code": "payment_reconciliation_required", "message": "Payment outcome needs reconciliation. Contact support; do not create another order or payment." } }, "payment_method_unavailable": { "summary": "Saved card needs an address update", "value": { "code": "payment_method_unavailable", "message": "Update the saved card's billing address before paying." } }, "model_repair_estimate_pending": { "$ref": "#/components/examples/ModelRepairEstimatePending" }, "repair_payment_pending": { "summary": "texture payment pending", "value": { "code": "repair_payment_pending", "message": "Pay or cancel this revision's existing model repair order first." } }, "idempotency_key_reused": { "$ref": "#/components/examples/IdempotencyKeyReused" }, "idempotency_request_in_progress": { "$ref": "#/components/examples/IdempotencyRequestInProgress" }, "quote_unavailable": { "summary": "Saved Model repair evidence is unavailable.", "value": { "code": "quote_unavailable", "message": "Saved Model repair evidence is unavailable." } } } } } }, "413": { "$ref": "#/components/responses/Response413_2" }, "415": { "$ref": "#/components/responses/Response415" }, "429": { "description": "Rate or account limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "resource_exhausted": { "summary": "resource exhausted", "value": { "code": "resource_exhausted", "message": "Payment attempt limit reached. Retry after 60 seconds." } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter_4" } } }, "500": { "$ref": "#/components/responses/Response500_3" }, "503": { "$ref": "#/components/responses/Response503_2" } }, "security": [ { "ApiKeyAuth": [ "payments:write" ] } ] } }, "/payment-methods": { "get": { "operationId": "ListPaymentMethods", "tags": [ "Payments" ], "summary": "List payment methods", "description": "List cards saved and approved for the business. Requires payments:read (keys with payments:write also qualify); listing needs no spending consent and authorizes no charge. Manage cards on the account Billing page. No raw card data is returned. Pages use limit and cursor, ordered by card ID, and return data, has_more and next_cursor.", "parameters": [ { "$ref": "#/components/parameters/Limit_2" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Approved account-owned saved cards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedPaymentMethods" }, "examples": { "saved_cards": { "value": { "data": [ { "id": "pm_example", "brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2030 } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/Response400" }, "401": { "$ref": "#/components/responses/Response401_5" }, "403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "The API key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "permission_denied": { "value": { "code": "permission_denied", "message": "This key requires the payments:read scope." } } } } } }, "429": { "$ref": "#/components/responses/Response429" }, "500": { "$ref": "#/components/responses/Response500_3" }, "503": { "$ref": "#/components/responses/Response503_2" } }, "x-required-permission": "payments:read", "security": [ { "ApiKeyAuth": [ "payments:read" ] } ] } } }, "webhooks": { "order.created": { "post": { "summary": "Order created", "description": "Order accepted from a quote: awaiting_payment and unpaid.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "order.created": { "value": { "id": "evt_00000000000000000000000000000001", "type": "order.created", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 1, "status": "awaiting_payment", "payment": { "status": "unpaid" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "OrderCreatedWebhook" } }, "payment.requires_action": { "post": { "summary": "Payment requires action", "description": "The customer must authenticate. Resume the order's payment.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "payment.requires_action": { "value": { "id": "evt_00000000000000000000000000000002", "type": "payment.requires_action", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 2, "status": "awaiting_payment", "payment": { "status": "requires_action" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "PaymentRequiresActionWebhook" } }, "payment.processing": { "post": { "summary": "Payment processing", "description": "Payment submitted; the outcome is pending.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "payment.processing": { "value": { "id": "evt_00000000000000000000000000000003", "type": "payment.processing", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 2, "status": "awaiting_payment", "payment": { "status": "processing" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "PaymentProcessingWebhook" } }, "payment.paid": { "post": { "summary": "Payment paid", "description": "Payment captured. order.confirmed follows for awaiting_payment orders.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "payment.paid": { "value": { "id": "evt_00000000000000000000000000000004", "type": "payment.paid", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 3, "status": "awaiting_payment", "payment": { "status": "paid" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "PaymentPaidWebhook" } }, "payment.failed": { "post": { "summary": "Payment failed", "description": "Payment attempt failed. Check payment.error before starting a new attempt.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "payment.failed": { "value": { "id": "evt_00000000000000000000000000000005", "type": "payment.failed", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 3, "status": "awaiting_payment", "payment": { "status": "failed" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "PaymentFailedWebhook" } }, "order.confirmed": { "post": { "summary": "Order confirmed", "description": "Verified payment confirmed the order.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "order.confirmed": { "value": { "id": "evt_00000000000000000000000000000006", "type": "order.confirmed", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 4, "status": "confirmed", "payment": { "status": "paid" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "OrderConfirmedWebhook" } }, "order.in_production": { "post": { "summary": "Order in production", "description": "Staff or fulfillment started manufacturing. Customer cancellation is no longer available.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "order.in_production": { "value": { "id": "evt_00000000000000000000000000000007", "type": "order.in_production", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 5, "status": "in_production", "payment": { "status": "paid" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } }, "summary": "order.in_production example" } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "OrderInProductionWebhook" } }, "order.on_hold": { "post": { "summary": "Order on hold", "description": "Staff paused the order. The reason is the message shown to the customer; GET the order for hold.code.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "order.on_hold": { "value": { "id": "evt_00000000000000000000000000000008", "type": "order.on_hold", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 6, "status": "on_hold", "payment": { "status": "paid" }, "reason": "Model repair requires review.", "updated_at": "2026-09-29T18:01:00.000000Z" } }, "summary": "order.on_hold example" } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "OrderOnHoldWebhook" } }, "order.resumed": { "post": { "summary": "Order resumed", "description": "Staff released a hold; the status returns to its prior value.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "order.resumed": { "value": { "id": "evt_00000000000000000000000000000009", "type": "order.resumed", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 7, "status": "in_production", "payment": { "status": "paid" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } }, "summary": "order.resumed example" } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "OrderResumedWebhook" } }, "order.shipped": { "post": { "summary": "Order shipped", "description": "The whole order was handed to the carrier. GET the order for shipment tracking details.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "order.shipped": { "value": { "id": "evt_0000000000000000000000000000000a", "type": "order.shipped", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 8, "status": "shipped", "payment": { "status": "paid" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } }, "summary": "order.shipped example" } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "OrderShippedWebhook" } }, "order.delivered": { "post": { "summary": "Order delivered", "description": "Staff recorded delivery. GET the order for shipment.delivered_at.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "order.delivered": { "value": { "id": "evt_0000000000000000000000000000000b", "type": "order.delivered", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 9, "status": "delivered", "payment": { "status": "paid" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } }, "summary": "order.delivered example" } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "OrderDeliveredWebhook" } }, "order.cancelled": { "post": { "summary": "Order cancelled", "description": "Order cancelled. Payment events report any refund.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "order.cancelled": { "value": { "id": "evt_0000000000000000000000000000000c", "type": "order.cancelled", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 6, "status": "cancelled", "payment": { "status": "refund_pending" }, "reason": "Customer changed the design.", "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "OrderCancelledWebhook" } }, "payment.cancelled": { "post": { "summary": "Payment cancelled", "description": "Payment attempt cancelled or voided without a charge.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "payment.cancelled": { "value": { "id": "evt_0000000000000000000000000000000d", "type": "payment.cancelled", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 3, "status": "cancelled", "payment": { "status": "cancelled" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "PaymentCancelledWebhook" } }, "payment.refund_pending": { "post": { "summary": "Refund pending", "description": "Full refund requested after cancellation.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "payment.refund_pending": { "value": { "id": "evt_0000000000000000000000000000000e", "type": "payment.refund_pending", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 5, "status": "cancelled", "payment": { "status": "refund_pending" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "PaymentRefundPendingWebhook" } }, "payment.refunded": { "post": { "summary": "Payment refunded", "description": "The payment provider confirmed the full refund.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "payment.refunded": { "value": { "id": "evt_0000000000000000000000000000000f", "type": "payment.refunded", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 7, "status": "cancelled", "payment": { "status": "refunded" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "PaymentRefundedWebhook" } }, "payment.refund_failed": { "post": { "summary": "Refund failed", "description": "The refund failed. Support follows up; no new charge is needed.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "payment.refund_failed": { "value": { "id": "evt_00000000000000000000000000000010", "type": "payment.refund_failed", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 7, "status": "cancelled", "payment": { "status": "refund_failed" }, "reason": null, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "PaymentRefundFailedWebhook" } }, "model.ready": { "post": { "summary": "Model ready", "description": "The model became ready: CalculatePrices, quotes and orders accept it at its saved size, including any required Model repair price.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelWebhookEvent" }, "examples": { "model.ready": { "value": { "id": "evt_00000000000000000000000000000065", "type": "model.ready", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "model", "id": "MD-739YQ549", "external_id": "customer-123", "status": "ready", "status_reasons": [], "mesh_check": { "status": "completed" }, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "ModelReadyWebhook" } }, "model.action_required": { "post": { "summary": "Model needs action", "description": "Processing finished but the model cannot be priced. status_reasons explains how to recover, for example by resizing or replacing the file.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelWebhookEvent" }, "examples": { "model.action_required": { "value": { "id": "evt_00000000000000000000000000000066", "type": "model.action_required", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "model", "id": "MD-739YQ549", "external_id": "customer-123", "status": "action_required", "status_reasons": [ { "code": "volume_unavailable", "message": "The model has no printable volume at its saved size. Resize or replace the file." } ], "mesh_check": { "status": "completed" }, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "ModelActionRequiredWebhook" } }, "model.failed": { "post": { "summary": "Model failed", "description": "The model's status changed to failed: intake or inspection failed terminally. Upload a corrected file and replace the source under the same model ID, or create a separate model.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelWebhookEvent" }, "examples": { "model.failed": { "value": { "id": "evt_00000000000000000000000000000066", "type": "model.failed", "created_at": "2026-09-29T18:01:00.000000Z", "data": { "object": "model", "id": "MD-739YQ549", "external_id": "customer-123", "status": "failed", "status_reasons": [ { "code": "unreadable_model", "message": "The model could not be read. Export a new OBJ package or self-contained GLB." } ], "mesh_check": { "status": "failed", "error": { "code": "unreadable_model", "message": "The model could not be read. Export a new OBJ package or self-contained GLB." } }, "updated_at": "2026-09-29T18:01:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "ModelFailedWebhook" } }, "order.expired": { "post": { "summary": "Order expired", "description": "Unpaid order reached expires_at with no active payment attempt. Late payment success is refunded without confirming the order.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderWebhookEvent" }, "examples": { "order.expired": { "value": { "id": "evt_0000000000000000000000000000000d", "type": "order.expired", "created_at": "2026-09-30T18:00:00.000000Z", "data": { "object": "order", "id": "OM-3VFAH2ZH", "external_id": "PO-1042", "sequence": 2, "status": "expired", "payment": { "status": "unpaid" }, "reason": null, "updated_at": "2026-09-30T18:00:00.000000Z" } } } } } } }, "responses": { "200": { "description": "Return any 2xx status within 15 seconds to acknowledge. Other statuses, redirects and timeouts are retried." } }, "operationId": "OrderExpiredWebhook" } } }, "components": { "schemas": { "FileInput": { "type": "object", "additionalProperties": false, "required": [ "filename", "size_bytes" ], "properties": { "filename": { "type": "string", "minLength": 1, "pattern": "^(?!\\s)(?=[^/\\\\]*[^. /\\\\][^/\\\\]*\\.)(?!.*[\\x00-\\x1f\\x7f-\\x9f])[^/\\\\]+\\.(?:[gG][lL][bB]|[oO][bB][jJ]|[zZ][iI][pP])(?![\\s\\S])", "description": "Original filename, including .glb, .obj, or .zip. Maximum 255 characters; directory paths, leading/trailing whitespace, and control characters are not allowed.", "examples": [ "figurine.zip" ], "maxLength": 255 }, "size_bytes": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 400000000, "description": "Exact file size in bytes. For ZIPs, use the compressed size. Maximum 400000000 bytes (400 MB).", "examples": [ 10485760 ] } }, "description": "Required direct-upload metadata. Checked synchronously before registering a File and returning signed instructions. No source selector or geometry units. Actual model content is inspected after Model creation." }, "FileRegistration": { "type": "object", "additionalProperties": true, "required": [ "id", "upload" ], "properties": { "id": { "$ref": "#/components/schemas/FileId", "readOnly": true }, "upload": { "$ref": "#/components/schemas/SignedPostUpload", "readOnly": true } }, "description": "Registered file ID and temporary upload instructions. Registration does not mean bytes have arrived. Unlinked files expire 24 hours after registration; upload or access does not extend retention. upload.expires_at is the upload-permission deadline. Create a model using this file ID before the unlinked file expires." }, "FileId": { "type": "string", "minLength": 37, "maxLength": 37, "pattern": "^file_[0-9a-f]{32}$", "description": "Unique, server-generated file ID. Treat it as an opaque reference.", "examples": [ "file_6c82bd3e319b4bb099310d54a761879e" ] }, "SignedPostUpload": { "type": "object", "additionalProperties": true, "description": "Temporary upload instructions. Send all fields unchanged, then append the file as the last form field. Do not send your API key to storage.", "required": [ "method", "url", "fields", "expires_at" ], "properties": { "method": { "type": "string", "enum": [ "POST" ] }, "url": { "type": "string", "format": "uri", "description": "Destination for the file upload. Authorization is carried in the signed form fields." }, "fields": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "string" }, "description": "Complete generated form fields, including the object key, policy, signature, and AWS verification fields. Treat this map as opaque and forward every field unchanged. The actual file is supplied separately." }, "expires_at": { "type": "string", "format": "date-time", "description": "UTC expiration of these upload instructions, at most one hour after issuance. Retrying does not extend it. Completed uploads remain usable until the file’s unlinked retention deadline." } } }, "ApiError": { "type": "object", "additionalProperties": true, "required": [ "code", "message" ], "description": "Error code, message and optional field details. HTTP errors return this object directly; asynchronous processing errors appear on the resource. Branch on code, not message.", "properties": { "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "description": "Machine-readable error code. HTTP errors use a value from ErrorCode. Branch on this value; handle unknown codes by HTTP status." }, "message": { "type": "string", "description": "Human-readable explanation. Wording can vary; do not branch on it." }, "details": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "PriceInput": { "type": "object", "additionalProperties": false, "description": "Select model IDs, sizes and quantities. Matching model and size entries merge in first-appearance order; different sizes remain separate. Pricing does not modify models.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PriceItemInput" }, "description": "One to 50 model/print-size entries, up to 1,000 prints in total. Matching model_id and longest_dimension_mm values merge in first-appearance order. Combined quantity must not exceed 500 per model and size; different sizes remain separate.", "minItems": 1, "maxItems": 50 } } }, "PriceItemInput": { "type": "object", "additionalProperties": false, "description": "Select an owned model, print size and quantity. Size is a line-item choice; it does not modify the model. Requires completed mesh inspection and usable volume. The server decides Model repair; read the repair object on each returned line.", "required": [ "model_id", "longest_dimension_mm", "quantity" ], "properties": { "model_id": { "$ref": "#/components/schemas/ModelId" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Printed models at this size, from 1 to 500. The same limit applies after matching model/size entries are merged." }, "longest_dimension_mm": { "$ref": "#/components/schemas/LongestDimensionMm" } } }, "ModelId": { "type": "string", "minLength": 11, "maxLength": 11, "pattern": "^MD-[0-9A-HJKMNP-TV-Z]{8}$", "description": "Immutable model ID: MD- followed by eight uppercase Crockford Base32 characters. Use this same ID in the website, URLs and API; pass it unchanged.", "examples": [ "MD-739YQ549" ] }, "LongestDimensionMm": { "type": "number", "minimum": 30, "maximum": 200, "description": "Longest bounding-box dimension in millimeters, 30–200 inclusive. Fractional values are accepted. Uniformly scale all axes. At model creation this is the default and inspection reference size; each pricing/quote item explicitly selects its own size. Callers convert other units to millimeters." }, "PriceCalculation": { "type": "object", "additionalProperties": true, "description": "Manufacturing estimate using the current account rate. Does not create a quote, order, repair job, payment or quote price lock. Repeating a request has no billing side effects. A later calculation can change if measurements or pricing policy changes.", "required": [ "currency", "pricing_version", "items", "subtotal", "estimated_production_business_days" ], "properties": { "currency": { "type": "string", "const": "usd", "description": "Literal usd. All monetary amounts are integer USD cents." }, "pricing_version": { "$ref": "#/components/schemas/PricingVersion" }, "service_fees": { "$ref": "#/components/schemas/ServiceFees" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PriceLineItem" }, "description": "One line per model/size in first-appearance order. Matching entries merge. Each model’s repair fee is allocated to its first returned line only, regardless of sizes or quantities.", "minItems": 1 }, "subtotal": { "type": "integer", "minimum": 0, "description": "Sum of model line subtotals, excluding shipping and tax. Integer minor currency units." }, "estimated_production_business_days": { "anyOf": [ { "$ref": "#/components/schemas/BusinessDayRange" }, { "type": "null" } ], "description": "Reserved for a production estimate; currently null." } } }, "PricingVersion": { "type": "string", "description": "Opaque identifier for the pricing schedule used. Store it for reference; do not parse it or calculate prices from it. A calculation does not lock prices; review a quote before ordering. Business pricing versions change at calendar-month boundaries; unaccepted quotes then require refreshing." }, "PriceLineItem": { "type": "object", "additionalProperties": true, "description": "Model and print-configuration snapshot. subtotal is unit_price × quantity, plus repair.fee when this line carries the repair fee. A file revision's repair fee is charged once, on its first line, unless a paid order already covers it.", "required": [ "model_id", "quantity", "unit_price", "subtotal", "longest_dimension_mm", "volume", "estimated_weight_g", "mesh_check_passed", "repair" ], "properties": { "model_id": { "$ref": "#/components/schemas/ModelId" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Combined quantity of printed models for this model and print size, from 1 to 500." }, "unit_price": { "type": "integer", "minimum": 0, "description": "Manufacturing price per model in USD cents, excluding repair, shipping and tax." }, "subtotal": { "type": "integer", "minimum": 0, "description": "Manufacturing unit_price × quantity, plus repair.fee when the repair fee is charged on this line." }, "repair": { "$ref": "#/components/schemas/Repair" }, "longest_dimension_mm": { "$ref": "#/components/schemas/LongestDimensionMm" }, "volume": { "$ref": "#/components/schemas/ModelVolume" }, "estimated_weight_g": { "type": "number", "minimum": 0, "description": "Estimated model material weight per printed model at this size in grams, rounded to at most three decimal places. Informational; use unit_price for the charge." }, "mesh_check_passed": { "type": [ "boolean", "null" ], "description": "Inspection verdict. Failed or incomplete mesh integrity requires repair; paid coverage waives the fee, not the work. Not manufacturing approval." }, "file_revision": { "type": "integer", "minimum": 1, "description": "Customer-uploaded file revision, not the internal processing generation." }, "support_volume": { "$ref": "#/components/schemas/ModelVolume", "description": "Estimated support volume per model at this print size. Informational; use returned unit_price." }, "minimum_total_volume": { "$ref": "#/components/schemas/ModelVolume", "description": "Estimated manufacturing volume per model at this print size. Informational; use returned unit_price." }, "support_build_direction": { "type": "string", "enum": [ "+x", "-x", "+y", "-y", "+z", "-z" ], "description": "Selected estimated build direction." } } }, "Repair": { "type": "object", "required": [ "required", "applied", "reason", "status", "fee", "covered_by_order_id" ], "description": "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.", "properties": { "required": { "type": "boolean", "description": "Mesh inspection requires repair." }, "applied": { "type": "boolean", "description": "Staff repair this model before printing." }, "reason": { "type": [ "string", "null" ], "enum": [ "inspection_failed", "customer_request", "covered", null ], "description": "Why repair applies; null when it does not." }, "status": { "type": "string", "enum": [ "not_applied", "estimating", "priced", "covered" ], "description": "estimating: the fee is being estimated; quotes and orders wait. priced: fee is known. covered: a paid order already covers this file revision." }, "fee": { "type": [ "integer", "null" ], "minimum": 0, "description": "Repair fee in cents for this line or model revision; charged once per model revision per quote. Null while estimating." }, "covered_by_order_id": { "type": [ "string", "null" ], "description": "Paid order that covers this file revision; repaired file is printed at no charge." } } }, "ModelVolume": { "type": "object", "required": [ "value_mm3", "status" ], "description": "Volume at the enclosing model or price item’s longest_dimension_mm. A missing measurement is null; a measured zero is 0.", "properties": { "value_mm3": { "type": "number", "minimum": 0, "description": "Cubic millimeters at the selected size, rounded to at most three decimal places. Holes and inconsistent geometry can affect estimate accuracy." }, "status": { "type": "string", "enum": [ "estimated", "confirmed" ], "description": "estimated: approximate measurement; confirmed: validated measurement. Currently returns estimated." } } }, "BusinessDayRange": { "type": "object", "additionalProperties": true, "description": "Estimated transit business-day range. min does not exceed max. Not a delivery guarantee.", "required": [ "min", "max" ], "properties": { "min": { "type": "integer", "minimum": 0 }, "max": { "type": "integer", "minimum": 0 } } }, "Quote": { "type": "object", "additionalProperties": true, "description": "Saved manufacturing prices, destination and shipping options, valid for 30 minutes. Later model changes do not rewrite the quote. Only status changes at read time. Unordered quotes are retained for 30 days after expiry; order-linked quotes are retained. Totals exclude tax.", "required": [ "id", "created_at", "expires_at", "currency", "items", "shipping_address", "estimated_production_business_days", "shipping_options", "pricing_version", "status" ], "properties": { "id": { "$ref": "#/components/schemas/QuoteId", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time in UTC RFC 3339 with six fractional-second digits (microseconds)." }, "expires_at": { "type": "string", "format": "date-time", "description": "Last time this quote may be accepted: exactly 30 minutes after created_at. Covers manufacturing prices and all offered shipping charges. Reading the quote never extends this deadline. UTC RFC 3339 with six fractional-second digits (microseconds)." }, "currency": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Literal usd. All monetary fields are USD cents.", "const": "usd" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/QuoteLineItem" }, "description": "Priced items, merged by model and print size, in first-appearance order." }, "shipping_address": { "$ref": "#/components/schemas/ShippingAddress" }, "buyer": { "$ref": "#/components/schemas/Buyer" }, "estimated_production_business_days": { "description": "Currently null: no production estimate is available.", "anyOf": [ { "$ref": "#/components/schemas/BusinessDayRange" }, { "type": "null" } ] }, "shipping_options": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ShippingOption" }, "description": "At most one option per estimated transit day: keep the cheapest carrier service. For ranges, group by maximum transit business days. Omit slower options that cost as much or more than a faster option. Ties select a service deterministically. Options remain ordered by shipping price; transit estimates are not guaranteed." }, "pricing_version": { "$ref": "#/components/schemas/PricingVersion" }, "status": { "type": "string", "enum": [ "open", "expired" ], "readOnly": true, "description": "Derived at response time: open before expires_at, expired at or after it. Recomputed on GET; an idempotent replay returns the original status. Commercial snapshot fields never change. It describes expiry only, not order or payment status." } } }, "QuoteId": { "type": "string", "minLength": 38, "maxLength": 38, "pattern": "^quote_[0-9a-f]{32}$", "description": "Server-generated public quote ID: quote_ plus 32 lowercase hexadecimal digits representing an opaque random value. Immutable and opaque; not a storage path or content hash.", "examples": [ "quote_6c82bd3e319b4bb099310d54a761879e" ] }, "QuoteLineItem": { "type": "object", "additionalProperties": true, "description": "Model and print-configuration snapshot. subtotal is unit_price × quantity, plus repair.fee when this line carries the repair fee. A file revision's repair fee is charged once, on its first line, unless a paid order already covers it.", "required": [ "model_id", "quantity", "unit_price", "subtotal", "longest_dimension_mm", "dimensions_mm", "repair" ], "properties": { "model_repair": { "$ref": "#/components/schemas/OrderLineModelRepair" }, "model_id": { "$ref": "#/components/schemas/ModelId" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "unit_price": { "type": "integer", "minimum": 0, "description": "Manufacturing price per model in USD cents, excluding repair, shipping and tax." }, "subtotal": { "type": "integer", "minimum": 0, "description": "Manufacturing unit_price × quantity, plus repair.fee when the repair fee is charged on this line." }, "repair": { "$ref": "#/components/schemas/Repair" }, "longest_dimension_mm": { "$ref": "#/components/schemas/LongestDimensionMm" }, "dimensions_mm": { "$ref": "#/components/schemas/DimensionsMm" }, "file_revision": { "type": "integer", "minimum": 1, "description": "Customer-uploaded file revision, not the internal processing generation." }, "thumbnail": { "$ref": "#/components/schemas/LineItemThumbnail" }, "model_name": { "type": "string", "description": "Display name captured when quoting; saved names do not change after model renames. For older orders without a saved name, reads may supply the current model name or the filename of the matching uploaded file. The model_id remains the canonical reference." } } }, "DimensionsMm": { "type": "object", "additionalProperties": true, "description": "Dimensions at the selected print size in millimeters, rounded to at most three decimals. The longest axis matches longest_dimension_mm within rounding tolerance; small extents can round to zero.", "required": [ "x", "y", "z" ], "properties": { "x": { "type": "number", "description": "Extent along x in mm.", "minimum": 0 }, "y": { "type": "number", "description": "Extent along y in mm.", "minimum": 0 }, "z": { "type": "number", "description": "Extent along z in mm.", "minimum": 0 } } }, "ShippingAddress": { "type": "object", "description": "Saved US recipient address. New quotes return a five-digit ZIP code.", "required": [ "name", "line1", "city", "state", "postal_code", "country" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Delivery recipient; may differ from the buyer.", "maxLength": 255 }, "company": { "type": "string", "minLength": 1, "description": "Optional recipient company.", "maxLength": 255 }, "line1": { "type": "string", "minLength": 1, "description": "Street address.", "maxLength": 200 }, "line2": { "type": "string", "minLength": 1, "description": "Optional apartment, suite, or additional address line.", "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "description": "Destination city/locality.", "maxLength": 100 }, "state": { "type": "string", "minLength": 1, "description": "Supported two-letter US state or territory code, or AA/AE/AP military region.", "maxLength": 2 }, "postal_code": { "type": "string", "minLength": 1, "description": "Five-digit ZIP code on new quotes. Older saved snapshots may retain ZIP+4.", "maxLength": 10, "pattern": "^[0-9]{5}(-[0-9]{4})?$" }, "country": { "type": "string", "description": "Literal US.", "const": "US", "minLength": 1, "maxLength": 2 }, "phone": { "type": "string", "minLength": 1, "description": "Recipient contact; required where the selected carrier/service requires it.", "maxLength": 50 }, "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 } } }, "Buyer": { "type": "object", "additionalProperties": false, "description": "Optional buyer details, separate from the delivery recipient. The authenticated account owns the quote and order.", "required": [], "properties": { "name": { "type": "string", "minLength": 1, "description": "Buyer name.", "maxLength": 255 }, "company": { "type": "string", "minLength": 1, "description": "Buyer company.", "maxLength": 255 }, "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 } } }, "ShippingOption": { "type": "object", "additionalProperties": true, "description": "Selectable shipping service with a price and estimated transit time after dispatch. Returns at most one service per transit-day option, ordered by price. Null timing means unavailable; estimates are not guaranteed delivery dates.", "required": [ "id", "name", "totals", "estimated_transit_business_days", "estimated_delivery" ], "properties": { "id": { "$ref": "#/components/schemas/ShippingOptionId" }, "name": { "type": "string", "minLength": 1, "description": "Customer-facing shipping service label." }, "carrier": { "type": "string", "minLength": 1, "description": "Optional carrier name, when a carrier is committed for this option." }, "totals": { "$ref": "#/components/schemas/QuoteTotals" }, "estimated_transit_business_days": { "description": "Carrier transit days when supplied; otherwise the supported service estimate. Starts at handoff, excludes production, and is not guaranteed.", "anyOf": [ { "$ref": "#/components/schemas/BusinessDayRange" }, { "type": "null" } ] }, "estimated_delivery": { "description": "Currently null because production timing is not available. Carrier transit alone is not an arrival-date promise.", "anyOf": [ { "$ref": "#/components/schemas/DateRange" }, { "type": "null" } ] } } }, "ShippingOptionId": { "type": "string", "pattern": "^shipopt_[0-9a-f]{32}$", "description": "Opaque service-generated ID for an option within a particular quote. Not a carrier rate ID. Cannot be transferred to another quote." }, "QuoteTotals": { "type": "object", "additionalProperties": true, "description": "Manufacturing and shipping charges in integer minor currency units. Total excludes tax.", "required": [ "subtotal", "shipping", "total" ], "properties": { "subtotal": { "type": "integer", "minimum": 0, "description": "Sum of model line subtotals, excluding shipping and tax. Integer minor currency units." }, "shipping": { "type": "integer", "minimum": 0, "description": "Carrier rate for the estimated parcel, including its packing weight. No general free-shipping credit; an account-specific arrangement can price one service at 0. Integer minor currency units (for USD, cents)." }, "total": { "type": "integer", "minimum": 0, "description": "Amount to review before ordering: subtotal + shipping. Tax is excluded in V1. Integer minor currency units (for USD, cents)." } } }, "DateRange": { "type": "object", "additionalProperties": true, "description": "Estimated arrival-date window at destination, earliest no later than latest. Includes production, handling, and transit with relevant business calendars. Estimate only; never a delivery guarantee. Values are calendar dates without timezone offsets. Do not compare destination delivery dates directly to origin-local ship dates; they use different local calendars.", "required": [ "earliest", "latest" ], "properties": { "earliest": { "type": "string", "format": "date" }, "latest": { "type": "string", "format": "date" } } }, "QuoteInput": { "type": "object", "additionalProperties": false, "description": "Select inspected models and a US shipping address to receive manufacturing prices and shipping options. Use Calculate prices when no shipping address is available. Totals exclude tax.", "required": [ "items", "shipping_address" ], "properties": { "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/QuoteItemInput" }, "maxItems": 50, "description": "1–50 inspected model items, up to 1,000 prints in total. Matching model/size entries merge; combined quantity cannot exceed 500 per model and size." }, "shipping_address": { "$ref": "#/components/schemas/QuoteShippingAddressInput" }, "buyer": { "$ref": "#/components/schemas/Buyer" } } }, "QuoteItemInput": { "type": "object", "additionalProperties": false, "description": "Select an owned model, print size and quantity. Size is a line-item choice; it does not modify the model. Requires completed mesh inspection and usable volume. The server decides Model repair; read the repair object on each returned line.", "required": [ "model_id", "longest_dimension_mm", "quantity" ], "properties": { "model_id": { "$ref": "#/components/schemas/ModelId" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 500 }, "longest_dimension_mm": { "$ref": "#/components/schemas/LongestDimensionMm" } } }, "QuoteShippingAddressInput": { "type": "object", "additionalProperties": false, "description": "US recipient address. Supply a five-digit ZIP code as a string, preserving leading zeroes; ZIP+4 and other lengths are rejected. Text must be nonblank and contain no Unicode category C characters. Postal verification may standardize the address. No client parcel weight, dimensions or origin.", "required": [ "name", "line1", "city", "state", "postal_code", "country" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Delivery recipient; may differ from the buyer.", "maxLength": 255 }, "company": { "type": "string", "minLength": 1, "description": "Optional recipient company.", "maxLength": 255 }, "line1": { "type": "string", "minLength": 1, "description": "Street address.", "maxLength": 200 }, "line2": { "type": "string", "minLength": 1, "description": "Optional apartment, suite, or additional address line.", "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "description": "Destination city/locality.", "maxLength": 100 }, "state": { "type": "string", "minLength": 1, "description": "Supported two-letter US state or territory code, or AA/AE/AP military region.", "maxLength": 2 }, "postal_code": { "type": "string", "minLength": 5, "maxLength": 5, "pattern": "^[0-9]{5}$", "description": "Exactly five digits, for example 02108. ZIP+4 is not accepted." }, "country": { "type": "string", "description": "Literal US.", "const": "US", "minLength": 1, "maxLength": 2 }, "phone": { "type": "string", "minLength": 1, "description": "Recipient contact; required where the selected carrier/service requires it.", "maxLength": 50 }, "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 254 } } }, "ModelInput": { "type": "object", "additionalProperties": false, "description": "Create a model from an uploaded file ID and default longest dimension in millimeters.", "required": [ "source", "longest_dimension_mm" ], "properties": { "source": { "$ref": "#/components/schemas/ModelSource" }, "name": { "type": "string", "description": "Optional human-readable model name supplied by the customer. Not unique; id is the system-generated identifier. Unicode category C characters, including control and format characters, are rejected.", "maxLength": 255 }, "external_id": { "type": "string", "description": "Optional identifier from the customer’s system. Stored and returned unchanged. No uniqueness, lookup, or deduplication guarantee. Unicode category C characters, including control and format characters, are rejected.", "maxLength": 255 }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "longest_dimension_mm": { "$ref": "#/components/schemas/LongestDimensionMm" } } }, "ModelSource": { "type": "object", "additionalProperties": false, "required": [ "file_id" ], "properties": { "file_id": { "$ref": "#/components/schemas/FileId" } }, "description": "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." }, "Metadata": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "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.", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 } }, "RegisteredModel": { "type": "object", "required": [ "id", "created_at", "updated_at", "source", "status", "status_reasons", "preview", "longest_dimension_mm", "mesh_check", "print_check", "repair" ], "properties": { "file_revision": { "type": "integer", "minimum": 1, "readOnly": true, "description": "Current customer file revision. Size and name changes do not create file revisions." }, "file_repair": { "type": [ "integer", "null" ], "minimum": 1, "readOnly": true, "description": "Current model repair of file_revision (1 and 1 is revision 1.1), or null." }, "id": { "$ref": "#/components/schemas/ModelId", "readOnly": true, "description": "Immutable design identifier. File replacements append a customer file revision while preserving this ID and previous sources." }, "source": { "$ref": "#/components/schemas/ModelSource" }, "name": { "type": "string", "description": "Optional customer-supplied label. Unicode category C characters, including control and format characters, are rejected." }, "external_id": { "type": "string", "description": "Optional identifier from your system. Not unique and does not deduplicate requests; filter by external_id when listing models." }, "created_at": { "type": "string", "format": "date-time", "description": "When registration occurred; immutable. UTC RFC 3339 timestamp with six fractional-second digits (microseconds).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "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).", "readOnly": true }, "status": { "$ref": "#/components/schemas/ModelStatus" }, "status_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ModelStatusReason" }, "description": "Why the model is not ready, in check order. Empty when ready." }, "preview": { "anyOf": [ { "$ref": "#/components/schemas/Preview" }, { "type": "null" } ], "description": "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." }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "longest_dimension_mm": { "$ref": "#/components/schemas/LongestDimensionMm", "description": "Default print size and inspection reference size, in millimeters. Pricing items can select another size without changing this model or existing cart/order items." }, "mesh_check": { "$ref": "#/components/schemas/PrimaryMeshCheck" }, "print_check": { "$ref": "#/components/schemas/PrintabilityCheck" }, "repair": { "$ref": "#/components/schemas/Repair" }, "progress": { "$ref": "#/components/schemas/ModelProgress" }, "volume": { "$ref": "#/components/schemas/NullableModelVolume", "description": "Volume at the default print size in cubic millimeters, rounded to at most three decimal places. Null when unavailable." }, "estimated_weight_g": { "type": [ "number", "null" ], "minimum": 0, "description": "Estimated model material weight at the default print size, in grams, rounded to at most three decimal places. Excludes support material. Null when unavailable." }, "orders": { "$ref": "#/components/schemas/ModelOrderSummary" }, "manufacturing_estimate": { "$ref": "#/components/schemas/ManufacturingEstimate" }, "error": { "$ref": "#/components/schemas/ModelProcessingError", "description": "Terminal preparation failure. Completed inspection and pricing evidence remain available, but this model cannot be quoted until preparation succeeds." } }, "description": "A reusable design with an immutable ID. Inspection results and measurements use its default print size; pricing requests select a size per item." }, "ModelStatus": { "type": "string", "enum": [ "processing", "ready", "action_required", "failed" ], "description": "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." }, "ModelStatusReason": { "type": "object", "required": [ "code", "message" ], "description": "Why a model is not ready.", "properties": { "code": { "type": "string", "description": "Why the model is not ready. A failed model reports its processing error code.", "enum": [ "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" ], "x-enum-descriptions": [ "Mesh inspection is running. Wait for model.ready, or poll with backoff.", "Measurements are running. Wait for model.ready, or poll with backoff.", "The repair fee is being estimated. Wait for model.ready, or poll with backoff.", "Measurements failed. Replace the file, or contact support with the model ID.", "The model has no printable volume at its saved size. Resize it or replace the file.", "The ZIP is not a valid model package. Use a ZIP containing one OBJ and its referenced assets, preserving relative paths.", "The model could not be read. Export a new OBJ package or self-contained GLB.", "A referenced material or texture is missing or unreadable. Upload a complete package.", "The file format is not supported. Use OBJ geometry with PNG or JPEG textures, or a self-contained GLB.", "The model uses features we cannot process. Export a static, uncompressed GLB with embedded assets, or an OBJ package with baked textures.", "The model has no finite surface geometry or a zero longest dimension. Fix the geometry and upload a new file.", "The model exceeds a processing resource limit. Simplify it and upload a new file.", "Processing exceeded the time limit. Simplify the model and upload a new file.", "Inspection could not complete after retries. Replace the file, or contact support with the model ID.", "Processing could not finish after retries. Contact support with the model ID.", "Model storage could not be read after retries. Contact support with the model ID." ] }, "message": { "type": "string", "description": "Human-readable explanation; not a stable identifier." } } }, "Preview": { "type": "object", "description": "Seven transparent views, generated independently of inspection. Source PNGs remain in images. Use thumbnails for compact images and display for larger views. Coordinates refer to the normalized model; uploaded orientation is preserved. Direction names describe camera positions, not detected semantic front or upright. Refresh GetModel when URLs expire. Signing fresh URLs does not change updated_at. A preview failure does not prevent pricing or ordering.", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "processing", "ready", "failed" ], "description": "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." }, "default_view": { "type": "string", "const": "angled", "description": "Recommended image for cards and thumbnails. Present only when ready." }, "expires_at": { "type": "string", "format": "date-time", "description": "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": { "$ref": "#/components/schemas/PreviewViewURLs", "description": "Original transparent PNGs. Present only when ready. All seven source views are published together." }, "error": { "$ref": "#/components/schemas/ApiError", "description": "Preview generation failure; other model results remain usable." }, "thumbnails": { "$ref": "#/components/schemas/PreviewViewURLs", "description": "Transparent 384 by 384 pixel WebP images for compact views. Present only when ready. Each missing variant uses its source PNG URL." }, "display": { "$ref": "#/components/schemas/PreviewViewURLs", "description": "Transparent 1024 by 1024 pixel WebP images for larger views. Present only when ready. Each missing variant uses its source PNG URL." } } }, "PreviewViewURLs": { "type": "object", "required": [ "angled", "front", "back", "left", "right", "top", "bottom" ], "description": "Signed URLs for all seven camera views. Anyone with a URL can view that image until expiry. Keep URLs private. Image requests need no API key.", "properties": { "angled": { "type": "string", "format": "uri", "description": "Camera at [1, 0.8, 1], looking toward the model center, with +Y up. Default view." }, "front": { "type": "string", "format": "uri", "description": "Camera on +Z, +Y up." }, "back": { "type": "string", "format": "uri", "description": "Camera on -Z, +Y up." }, "left": { "type": "string", "format": "uri", "description": "Camera on -X, +Y up." }, "right": { "type": "string", "format": "uri", "description": "Camera on +X, +Y up." }, "top": { "type": "string", "format": "uri", "description": "Camera on +Y, -Z up." }, "bottom": { "type": "string", "format": "uri", "description": "Camera on -Y, +Z up." } } }, "PrimaryMeshCheck": { "description": "Execution status, independent of the result. Successful checks may find defects or incomplete categories. The input geometry is not automatically repaired.", "oneOf": [ { "$ref": "#/components/schemas/PrimaryMeshCheckRunning" }, { "$ref": "#/components/schemas/PrimaryMeshCheckCompleted" }, { "$ref": "#/components/schemas/PrimaryMeshCheckFailed" } ], "discriminator": { "propertyName": "status", "mapping": { "pending": "#/components/schemas/PrimaryMeshCheckRunning", "processing": "#/components/schemas/PrimaryMeshCheckRunning", "completed": "#/components/schemas/PrimaryMeshCheckCompleted", "failed": "#/components/schemas/PrimaryMeshCheckFailed" } } }, "PrimaryMeshResult": { "type": "object", "required": [ "passed", "inverted_normals", "bad_edges", "planar_holes", "shells", "near_bad_edges", "noise_shells", "incomplete_checks" ], "properties": { "passed": { "type": [ "boolean", "null" ], "description": "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": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "inverted_normals", "bad_edges", "planar_holes" ] }, "description": "Supported checks that did not finish completely. A known positive count can coexist with incomplete checks." }, "inverted_normals": { "type": [ "integer", "null" ], "minimum": 0, "description": "Inverted triangle count. Null means unavailable, never zero." }, "bad_edges": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unpaired directed edge incidences; one geometric edge can contribute more than one. Null means unavailable, never zero." }, "planar_holes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Detected planar hole contours. Null means unavailable, never zero." }, "shells": { "type": [ "integer", "null" ], "minimum": 0, "description": "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." }, "near_bad_edges": { "type": [ "integer", "null" ], "minimum": 0, "description": "Measured Magics count, or null when unavailable." }, "noise_shells": { "type": [ "integer", "null" ], "minimum": 0, "description": "Measured Magics count, or null when unavailable." } } }, "ModelProcessingError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "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" ], "x-enum-descriptions": [ "The ZIP is not a valid model package. Use a ZIP containing one OBJ and its referenced assets, preserving relative paths.", "The model could not be read. Export a new OBJ package or self-contained GLB.", "A referenced material or texture is missing or unreadable. Upload a complete package.", "The file format is not supported. Use OBJ geometry with PNG or JPEG textures, or a self-contained GLB.", "The model uses features we cannot process. Export a static, uncompressed GLB with embedded assets, or an OBJ package with baked textures.", "The model has no finite surface geometry or a zero longest dimension. Fix the geometry and upload a new file.", "The model exceeds a processing resource limit. Simplify it and upload a new file.", "Processing exceeded the time limit. Simplify the model and upload a new file.", "Inspection could not complete after retries. Replace the file, or contact support with the model ID.", "Processing could not finish after retries. Contact support with the model ID.", "Model storage could not be read after retries. Contact support with the model ID." ] }, "message": { "type": "string", "description": "Recovery instructions. Do not branch on message text." } }, "description": "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." }, "PrintabilityCheck": { "description": "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.", "oneOf": [ { "$ref": "#/components/schemas/PrintabilityCheckRunning" }, { "$ref": "#/components/schemas/PrintabilityCheckCompleted" }, { "$ref": "#/components/schemas/PrintabilityCheckFailed" } ], "discriminator": { "propertyName": "status", "mapping": { "pending": "#/components/schemas/PrintabilityCheckRunning", "processing": "#/components/schemas/PrintabilityCheckRunning", "completed": "#/components/schemas/PrintabilityCheckCompleted", "failed": "#/components/schemas/PrintabilityCheckFailed" } } }, "PrintabilityResult": { "oneOf": [ { "$ref": "#/components/schemas/PrintabilityResultPrintable" }, { "$ref": "#/components/schemas/PrintabilityResultRepairRequired" } ], "discriminator": { "propertyName": "decision", "mapping": { "printable": "#/components/schemas/PrintabilityResultPrintable", "repair_required": "#/components/schemas/PrintabilityResultRepairRequired" } } }, "PrintRisk": { "type": "object", "required": [ "severity", "region_ids", "message" ], "properties": { "severity": { "enum": [ "warning", "high" ], "type": "string" }, "region_ids": { "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^region-[1-9][0-9]{0,6}$" }, "description": "Stable IDs within this assessment. Empty for whole-model or hard mesh issues." }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 } } }, "ModelProgress": { "type": "object", "required": [ "stage" ], "properties": { "stage": { "type": "string", "enum": [ "queued", "preparing", "inspecting", "resizing", "inspection_completed", "failed" ], "description": "Current inspection progress. inspection_completed and failed end polling for inspection; the overall model status can still be processing." } } }, "NullableModelVolume": { "type": [ "object", "null" ], "required": [ "value_mm3", "status" ], "description": "Volume at the enclosing model or price item’s longest_dimension_mm. A missing measurement is null; a measured zero is 0.", "properties": { "value_mm3": { "type": "number", "minimum": 0, "description": "Cubic millimeters at the selected size, rounded to at most three decimal places. Holes and inconsistent geometry can affect estimate accuracy." }, "status": { "type": "string", "enum": [ "estimated", "confirmed" ], "description": "estimated: approximate measurement; confirmed: validated measurement. Currently returns estimated." } } }, "OrderId": { "type": "string", "minLength": 11, "maxLength": 11, "pattern": "^OM-[0-9A-HJKMNP-TV-Z]{8}$", "description": "Immutable order ID and customer reference: OM- followed by eight uppercase Crockford Base32 characters. Pass it unchanged; there is no separate order-number field.", "examples": [ "OM-XMF1NT2E" ] }, "ManufacturingEstimate": { "description": "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.", "oneOf": [ { "$ref": "#/components/schemas/ManufacturingEstimateUnavailable" }, { "$ref": "#/components/schemas/ManufacturingEstimateProvisional" } ], "discriminator": { "propertyName": "status", "mapping": { "pending": "#/components/schemas/ManufacturingEstimateUnavailable", "unavailable": "#/components/schemas/ManufacturingEstimateUnavailable", "provisional": "#/components/schemas/ManufacturingEstimateProvisional" } } }, "RegisteredModelList": { "type": "object", "additionalProperties": true, "description": "Page of models in the requested sort order (default: updated_at then id, oldest first; sort=-created_at: created_at then id, newest first). Follow next_cursor with the same sort, filters and limit. Results can change during pagination; deduplicate by id and updated_at.", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegisteredModel" }, "description": "Models in ascending updated_at and id order. Each item has the same fields as Get Model." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor on the next request. Null when no further page is currently available." }, "has_more": { "type": "boolean", "description": "Whether additional matching models were available when this page was read." } } }, "ModelUpdate": { "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "name" ] }, { "required": [ "longest_dimension_mm" ] } ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Nonblank model name. Trimmed; control and format characters rejected." }, "longest_dimension_mm": { "$ref": "#/components/schemas/LongestDimensionMm" } } }, "DeletedModel": { "type": "object", "description": "Deletion acknowledgment. Later lookup and repeated deletion return 404; list results exclude the model.", "required": [ "id", "deleted" ], "properties": { "id": { "$ref": "#/components/schemas/ModelId" }, "deleted": { "type": "boolean", "const": true, "description": "Always true." } } }, "ModelFileRevisionPage": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/ModelFileRevision" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque signed cursor; null on the last page." } } }, "ModelReplacement": { "type": "object", "additionalProperties": false, "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/ModelSource" } } }, "Order": { "type": "object", "additionalProperties": true, "description": "An accepted order with fixed model selections, sizes, quantities, prices and delivery details. Retrieve it for current payment and order status. Fulfillment is not enabled; shipment and hold remain null.", "required": [ "id", "created_at", "expires_at", "quote_id", "currency", "items", "shipping_address", "shipping_option", "status", "updated_at", "events", "estimated_ship_date", "estimated_delivery", "hold", "payment", "pricing_version", "shipment", "preparation" ], "properties": { "id": { "$ref": "#/components/schemas/OrderId", "readOnly": true }, "created_at": { "type": "string", "format": "date-time" }, "quote_id": { "$ref": "#/components/schemas/QuoteId" }, "currency": { "type": "string", "pattern": "^[a-z]{3}$", "description": "Lowercase ISO 4217 currency for all monetary fields on this order. Currently usd." }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/QuoteLineItem" } }, "shipping_address": { "$ref": "#/components/schemas/ShippingAddress" }, "buyer": { "$ref": "#/components/schemas/Buyer" }, "shipping_option": { "$ref": "#/components/schemas/ShippingOption" }, "external_id": { "type": "string", "description": "Optional customer reference, without uniqueness or deduplication guarantees.", "maxLength": 255 }, "purchase_order_number": { "type": "string", "description": "Optional buyer purchase-order reference; not payment authorization.", "maxLength": 255 }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/OrderEvent" }, "description": "Complete inline append-only history in ascending sequence. No truncation or separate event endpoint in v1. Lifecycle milestone times can be derived from events[].", "minItems": 1 }, "estimated_ship_date": { "type": [ "string", "null" ], "format": "date", "description": "Current estimate for final carrier handoff, in origin local date; null if unknown. Calendar date without timezone. Do not directly compare it to destination-local estimated_delivery dates." }, "estimated_delivery": { "anyOf": [ { "$ref": "#/components/schemas/DateRange" }, { "type": "null" } ], "description": "Current full-order completion window, destination local dates; null if unknown. Does not overwrite individual shipment delivery times." }, "hold": { "anyOf": [ { "$ref": "#/components/schemas/OrderHold" }, { "type": "null" } ], "description": "Set while the order is on_hold; otherwise null." }, "payment": { "$ref": "#/components/schemas/OrderPayment" }, "pricing_version": { "$ref": "#/components/schemas/PricingVersion" }, "shipment": { "anyOf": [ { "$ref": "#/components/schemas/Shipment" }, { "type": "null" } ], "description": "Set when the order ships; null before. delivered_at is set on delivery." }, "preparation": { "$ref": "#/components/schemas/OrderPreparation" }, "invoice": { "anyOf": [ { "$ref": "#/components/schemas/OrderInvoice" }, { "type": "null" } ], "description": "Paid invoice summary; download using GET /orders/{order_id}/invoice. Null for unpaid orders or historical orders without a captured billing profile." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Deadline to start a new payment: 24 hours after created_at. Null once the order leaves awaiting_payment. Existing attempts get at least one hour from attempt creation to finish; after both deadlines, unfinished collection is cancelled before the order expires. Verified success during reconciliation confirms the order; unresolved provider outcomes keep it awaiting_payment. Success discovered after the order has expired is refunded without confirming." } } }, "OrderStatus": { "type": "string", "description": "Order lifecycle: awaiting_payment, expired, confirmed, in_production, shipped, delivered, on_hold or cancelled. Staff set in_production, shipped, delivered and on_hold. Customer cancellation is allowed only in awaiting_payment or confirmed, subject to repair-coverage guards.", "enum": [ "awaiting_payment", "expired", "confirmed", "in_production", "shipped", "delivered", "on_hold", "cancelled" ] }, "OrderEvent": { "type": "object", "additionalProperties": true, "description": "Order event with a unique ID, increasing sequence, type and timestamp. Status changes include previous_status and status; order.created includes the initial status.", "required": [ "id", "sequence", "type", "at", "reason", "data" ], "properties": { "id": { "type": "string", "description": "", "pattern": "^evt_[0-9a-f]{32}$" }, "sequence": { "type": "integer", "minimum": 1 }, "type": { "$ref": "#/components/schemas/OrderEventType" }, "at": { "type": "string", "format": "date-time" }, "reason": { "type": [ "string", "null" ], "description": "" }, "data": { "type": "object", "additionalProperties": true } } }, "OrderEventType": { "type": "string", "description": "Stable event name; handle unknown additions.", "enum": [ "order.created", "order.expired", "order.confirmed", "order.in_production", "order.shipped", "order.delivered", "order.on_hold", "order.resumed", "order.cancelled", "payment.requires_action", "payment.processing", "payment.paid", "payment.failed", "payment.cancelled", "payment.refund_pending", "payment.refunded", "payment.refund_failed" ] }, "OrderHold": { "type": "object", "additionalProperties": true, "description": "Why an order is on hold. Customer cancellation is unavailable while on_hold.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "", "enum": [ "address_problem", "printability", "payment", "other" ] }, "message": { "type": "string", "description": "" } } }, "OrderPayment": { "type": "object", "additionalProperties": true, "properties": { "status": { "$ref": "#/components/schemas/PaymentStatus" }, "amount": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[a-z]{3}$" }, "method": { "anyOf": [ { "$ref": "#/components/schemas/PaymentMethodSummary" }, { "type": "null" } ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "receipt_url": { "type": [ "string", "null" ], "format": "uri", "description": "Receipt link after successful payment, when available; otherwise null. Retrieve the order for current payment details." }, "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "status", "amount", "currency", "method", "paid_at", "receipt_url" ], "description": "Order-bound payment state, independent of preparation/fulfillment. amount/currency come from accepted quote. A saved method or return redirect is not proof of payment. Receipt links may be absent; never expose client secrets here. Refund states describe full-order refunds in v1. Cancellation before production refunds the full accepted total, including shipping. Refund completion is asynchronous; refund_failed requires support." }, "PaymentStatus": { "type": "string", "enum": [ "unpaid", "requires_action", "processing", "paid", "failed", "cancelled", "refund_pending", "refunded", "refund_failed" ], "description": "Order payment state. Refund states describe full-order refunds." }, "PaymentMethodSummary": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string", "pattern": "^[0-9]{4}$" } }, "required": [ "id", "brand", "last4" ], "description": "Safe saved-card summary. ID references an approved method belonging to this order account; never raw card data." }, "Shipment": { "type": "object", "additionalProperties": true, "description": "Single whole-order shipment; null until handoff. No split quantities or partial shipping. Tracking may be unavailable.", "required": [ "carrier", "service", "tracking_number", "tracking_url", "shipped_at", "delivered_at" ], "properties": { "carrier": { "type": "string", "description": "" }, "service": { "type": "string", "description": "" }, "tracking_number": { "type": [ "string", "null" ], "description": "" }, "tracking_url": { "type": [ "string", "null" ], "description": "", "format": "uri" }, "shipped_at": { "type": "string", "description": "Carrier handoff of the whole order, not label purchase.", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "description": "Delivery time; set when the order is delivered.", "format": "date-time" } } }, "OrderPreparation": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/OrderPreparationItem" } } }, "required": [ "status", "items" ], "description": "Preparation of accepted model/size configurations. Status currently remains pending: production preparation and fulfillment execution are not enabled. Processing, completed and failed are reserved preparation states. Payment does not establish completed preparation." }, "OrderInvoice": { "type": "object", "required": [ "number", "issued_at" ], "properties": { "number": { "type": "string" }, "issued_at": { "type": "string", "format": "date-time" } } }, "OrderInput": { "type": "object", "additionalProperties": false, "description": "Accept an unexpired quote and one of its shipping options. Optional external_id, purchase_order_number and metadata belong to this order only; nothing is inherited from the quote. No item, address or price overrides. A quote may have only one non-cancelled order. A new key for an already accepted quote returns 409 quote_accepted. After cancellation, an unexpired quote can be accepted again with a new key; the original key still replays the original order.", "required": [ "quote_id", "shipping_option_id" ], "properties": { "quote_id": { "$ref": "#/components/schemas/QuoteId" }, "shipping_option_id": { "$ref": "#/components/schemas/ShippingOptionId" }, "external_id": { "type": "string", "description": "Optional customer reference, without uniqueness or deduplication guarantees.", "maxLength": 255 }, "purchase_order_number": { "type": "string", "description": "Optional buyer purchase-order reference; not payment authorization.", "maxLength": 255 }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "OrderList": { "type": "object", "additionalProperties": true, "description": "Page of orders ordered by updated_at then id, oldest first. Follow next_cursor with the same filters and limit. Results can change during pagination; deduplicate by id and updated_at.", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "description": "" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor on the next request. Null when has_more is false." }, "has_more": { "type": "boolean" } } }, "CancelOrderInput": { "type": "object", "additionalProperties": false, "description": "", "required": [], "properties": { "reason": { "type": "string", "description": "Optional customer explanation.", "maxLength": 1000 } } }, "PaymentInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "checkout", "type": "string" } }, "required": [ "type" ], "description": "Open/resume hosted payment UI. Server supplies allowlisted return destinations; no caller prices or arbitrary redirects.", "title": "Hosted checkout" }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "saved_method", "type": "string" }, "payment_method_id": { "type": "string", "minLength": 1, "maxLength": 243, "pattern": "^pm_[A-Za-z0-9]+$" } }, "required": [ "type", "payment_method_id" ], "description": "Attempt payment with an approved account-owned saved payment method. Requires spending permission and consent; API key alone is insufficient.", "title": "Saved payment method" } ], "discriminator": { "propertyName": "type" } }, "PaymentAction": { "type": "object", "additionalProperties": true, "properties": { "order_id": { "$ref": "#/components/schemas/OrderId" }, "payment": { "$ref": "#/components/schemas/OrderPayment" }, "next_action": { "anyOf": [ { "$ref": "#/components/schemas/PaymentNextAction" }, { "type": "null" } ] } }, "required": [ "order_id", "payment", "next_action" ], "description": "Current payment action result. next_action only when customer interaction is needed. Use GET order for durable state. Failed/expired action does not require a new Order." }, "PaymentNextAction": { "type": "object", "additionalProperties": true, "properties": { "type": { "const": "redirect", "type": "string" }, "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "type", "url", "expires_at" ], "description": "Short-lived continuation to trusted payment UI or first-party authenticated recovery. Never include in generic order lists/events/logs." }, "SavedPaymentMethods": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "description": "Account-owned cards approved through the account billing setup.", "items": { "$ref": "#/components/schemas/SavedPaymentMethod" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "OrderWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "id", "type", "created_at", "data" ], "description": "Order webhook body. Mirrors one order events[] entry and shares its ID. Delivery is at least once and unordered.", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Same as the matching order events[].id. Stable across retries; deduplicate on it." }, "type": { "$ref": "#/components/schemas/OrderEventType" }, "created_at": { "type": "string", "format": "date-time", "description": "Event time; matches events[].at." }, "data": { "$ref": "#/components/schemas/OrderWebhookData" } } }, "OrderWebhookData": { "type": "object", "additionalProperties": true, "required": [ "object", "id", "sequence", "status", "payment", "reason", "updated_at" ], "description": "Order status when the event occurred. Excludes recipient, buyer and metadata; retrieve the order for details.", "properties": { "object": { "type": "string", "const": "order" }, "id": { "type": "string", "pattern": "^OM-[0-9A-HJKMNP-TV-Z]{8}$", "minLength": 11, "maxLength": 11 }, "external_id": { "type": "string", "maxLength": 255, "description": "Present when supplied at order creation." }, "sequence": { "type": "integer", "minimum": 1, "description": "The event's events[].sequence. Ignore events at or below the last sequence processed for this order." }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "payment": { "$ref": "#/components/schemas/OrderWebhookPayment" }, "reason": { "type": [ "string", "null" ], "description": "The event's reason, when one applies." }, "updated_at": { "type": "string", "format": "date-time" } } }, "ModelWebhookEvent": { "type": "object", "additionalProperties": true, "required": [ "id", "type", "created_at", "data" ], "description": "Model webhook body. Delivery is at least once and unordered.", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Stable across retries. Deduplicate on this value." }, "type": { "$ref": "#/components/schemas/ModelEventType" }, "created_at": { "type": "string", "format": "date-time", "description": "Event time; matches data.updated_at." }, "data": { "$ref": "#/components/schemas/ModelWebhookData" } } }, "ModelEventType": { "type": "string", "enum": [ "model.ready", "model.action_required", "model.failed" ], "description": "Model readiness events, sent once per status change. Handle unknown additions." }, "ModelWebhookData": { "type": "object", "additionalProperties": true, "required": [ "object", "id", "status", "status_reasons", "mesh_check", "updated_at" ], "description": "Model readiness when the event occurred. Retrieve the model for results; compare updated_at to discard older events.", "properties": { "object": { "type": "string", "const": "model" }, "id": { "type": "string", "pattern": "^MD-[0-9A-HJKMNP-TV-Z]{8}$", "minLength": 11, "maxLength": 11 }, "external_id": { "type": "string", "description": "Present when supplied at model creation." }, "status": { "$ref": "#/components/schemas/ModelStatus" }, "status_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ModelStatusReason" } }, "mesh_check": { "$ref": "#/components/schemas/ModelWebhookMeshCheck" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ErrorCode": { "type": "string", "description": "Every code an HTTP error response can return in Error.code. Branch on code, not message. New codes can be added; handle unknown codes by HTTP status.", "enum": [ "invalid_argument", "filename_required", "size_bytes_required", "unsupported_file_extension", "invalid_file_size", "file_too_large", "file_not_found", "file_not_ready", "idempotency_key_reused", "idempotency_request_in_progress", "precondition_failed", "model_not_found", "model_not_ready", "pricing_unavailable", "shipping_unavailable", "model_repair_estimate_pending", "quote_not_found", "payment_method_not_found", "unauthenticated", "permission_denied", "order_not_found", "not_found", "method_not_allowed", "not_acceptable", "model_in_use", "quote_expired", "quote_accepted", "quote_unavailable", "repair_payment_pending", "invoice_unavailable", "cancellation_unavailable", "payment_unavailable", "payment_method_unavailable", "payment_in_progress", "payment_reconciliation_required", "request_too_large", "unsupported_media_type", "resource_exhausted", "internal", "unavailable", "shipping_rates_unavailable" ], "x-enum-descriptions": [ "A field, query parameter or header is invalid. Fix the field named in details, then send the request again.", "The file registration has no filename. Send the original filename with its extension.", "The file registration has no size_bytes. Send the file's exact byte count.", "The file type is not supported. Use a GLB, OBJ or ZIP file.", "size_bytes is not a positive whole number. Send the file's exact byte count.", "The file is over the upload limit. Reduce it before you register it.", "No file with this ID exists in the account, or it expired before a model used it. Register and upload the file again.", "The file bytes have not finished uploading, or their size differs from the registration. Finish the upload, then retry.", "This Idempotency-Key was already used with a different body. Retry the original body, or use a new key for a new operation.", "A request with this Idempotency-Key is still running. Wait Retry-After seconds, then retry the same key and body.", "The model changed since you read its ETag. Read it again, review the change, then retry with the new ETag in If-Match.", "No model with this ID exists in the account, or it was deleted. Check the ID.", "The model is still processing. Wait until its status is ready, then retry.", "The model cannot be priced, usually because processing failed. Read the model's status_reasons; repeating the request does not rerun inspection.", "No shipping service accepts this destination or basket. Check the address, or split an oversized basket.", "The repair fee is still being estimated. Wait until the model status is ready, then retry.", "No quote with this ID exists in the account, or it is past retention. Check the ID.", "No saved card with this ID is approved for the business. Choose a card from List payment methods.", "The API key is missing, invalid or revoked. Send a valid business API key in Authorization: Bearer.", "The key lacks the endpoint's scope, or payments lack spending consent. Check the scope listed on the endpoint.", "No order with this ID exists in the account. Check the ID.", "Any route (HTTP 404): no API route matches the path. Check the method, path and version prefix.", "Any route (HTTP 405): the route does not accept this HTTP method. Use a method listed in the reference.", "Any route (HTTP 406): the Accept header excludes application/json. Accept application/json.", "An order uses this model, so it cannot be deleted.", "The quote is older than 30 minutes. Create a new quote, then order it with a new Idempotency-Key.", "An order already uses this quote. Find it with List orders and quote_id; do not create another.", "A model, its price or its repair changed after quoting. Create and review a new quote.", "Another order has an unpaid repair fee for this file revision. Pay or cancel that order, then quote again.", "The order has no paid invoice yet. Pay the order, then download the invoice.", "The order can no longer be cancelled, or other orders rely on its paid repair. Retrieve it to see its status.", "The order cannot take a payment now. Retrieve it and check its status and expires_at.", "The saved card cannot be charged, for example because its billing address is invalid. Update it, then retry.", "A payment with a different method is still in progress. Wait for its result before you try another method.", "The payment outcome is unknown and needs review. Contact support with the order ID; do not pay again.", "The JSON body is over this endpoint's size limit. Send a smaller body.", "The body is not JSON. Send Content-Type: application/json.", "A rate or account limit was reached. Wait at least Retry-After seconds, then retry.", "The server failed unexpectedly. Retry with backoff; contact support with X-Request-ID if it persists.", "A required service is briefly unavailable. Retry with backoff, reusing the same Idempotency-Key.", "Shipping rates could not be fetched. Retry with backoff and the same Idempotency-Key." ] }, "ErrorDetail": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "Request body, query or header field path, e.g. items[0].model_id or Idempotency-Key." }, "message": { "type": "string" } } }, "ServiceFees": { "type": "object", "description": "Current Model repair starting rate in USD cents. Final price uses declared counts. mesh_repair is a deprecated compatibility field, always zero for new calculations.", "required": [ "mesh_repair" ], "properties": { "mesh_repair": { "deprecated": true, "type": "integer", "minimum": 0, "description": "Deprecated. Always zero; geometry repair is part of Model repair." }, "model_repair": { "type": "integer", "minimum": 0, "description": "Lowest count-priced service amount; currently 350 cents for one large item." } } }, "OrderLineModelRepair": { "type": "object", "readOnly": true, "description": "Orders only, on paid repair lines. Once repaired, the line prints file_revision.file_repair (1.1).", "required": [ "status", "file_revision" ], "properties": { "status": { "type": "string", "enum": [ "waiting", "repairing", "checking", "repaired" ] }, "file_revision": { "type": "integer", "minimum": 1 }, "file_repair": { "type": "integer", "minimum": 1 } } }, "LineItemThumbnail": { "type": "object", "description": "Optional private preview of the purchased file, freshly signed on order reads. Uses a 384 pixel WebP thumbnail, or the source PNG if conversion is incomplete. Missing when unavailable; refresh the order after expiry. Never uses a later uploaded revision.", "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } }, "ModelOrderSummary": { "type": "object", "additionalProperties": true, "description": "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.", "required": [ "count", "latest_order_id" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "latest_order_id": { "anyOf": [ { "$ref": "#/components/schemas/OrderId" }, { "type": "null" } ] } } }, "MeshCheckWarning": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "appearance_fallback" ] }, "message": { "type": "string" } } }, "PrintabilityError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "printability_unavailable", "type": "string" }, "message": { "type": "string" } } }, "ModelFileRevision": { "type": "object", "required": [ "number", "source", "filename", "created_at", "current", "label", "repairs" ], "properties": { "number": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/ModelSource" }, "filename": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "current": { "type": "boolean" }, "label": { "type": "string" }, "repairs": { "type": "array", "description": "Published model repairs of this upload, newest first (1.1 repairs 1).", "items": { "$ref": "#/components/schemas/ModelRepairRevision" } } } }, "ModelRepairRevision": { "type": "object", "required": [ "repair", "label", "source", "filename", "created_at", "current" ], "properties": { "repair": { "type": "integer", "minimum": 1 }, "label": { "type": "string" }, "source": { "$ref": "#/components/schemas/ModelSource" }, "filename": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "current": { "type": "boolean" } } }, "OrderPreparationItem": { "type": "object", "additionalProperties": true, "properties": { "model_id": { "$ref": "#/components/schemas/ModelId" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "error": { "$ref": "#/components/schemas/ApiError" }, "longest_dimension_mm": { "$ref": "#/components/schemas/LongestDimensionMm" }, "repair_required": { "type": "boolean", "description": "Paid repair and revalidation must complete before production." }, "file_revision": { "type": "integer", "minimum": 1, "description": "Pinned customer file revision. Renames and resizes do not create a new revision." }, "repair_order_id": { "type": "string", "pattern": "^OM-[0-9A-HJKMNP-TV-Z]{8}$", "description": "Originating paid mesh-repair order for this exact revision. Reuse its repair work; payment alone is not proof of completed preparation.", "minLength": 11, "maxLength": 11 } }, "required": [ "model_id", "longest_dimension_mm", "status" ], "description": "" }, "SavedPaymentMethod": { "type": "object", "required": [ "id", "brand", "last4", "exp_month", "exp_year" ], "properties": { "id": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string" }, "exp_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "exp_year": { "type": "integer" } } }, "OrderWebhookPayment": { "type": "object", "additionalProperties": true, "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/PaymentStatus" } } }, "ModelWebhookMeshCheck": { "type": "object", "additionalProperties": true, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "error": { "$ref": "#/components/schemas/ModelProcessingError" } } }, "PrimaryMeshCheckRunning": { "type": "object", "required": [ "status" ], "properties": { "status": { "enum": [ "pending", "processing" ], "type": "string" }, "warnings": { "type": "array", "description": "Non-blocking appearance warnings. Missing materials use neutral gray; missing or unreadable textures use the material base color. Original uploads remain unchanged.", "items": { "$ref": "#/components/schemas/MeshCheckWarning" } } } }, "PrimaryMeshCheckCompleted": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "const": "completed", "type": "string" }, "result": { "$ref": "#/components/schemas/PrimaryMeshResult" }, "warnings": { "type": "array", "description": "Non-blocking appearance warnings. Missing materials use neutral gray; missing or unreadable textures use the material base color. Original uploads remain unchanged.", "items": { "$ref": "#/components/schemas/MeshCheckWarning" } } } }, "PrimaryMeshCheckFailed": { "type": "object", "required": [ "status", "error" ], "properties": { "status": { "const": "failed", "type": "string" }, "warnings": { "type": "array", "description": "Non-blocking appearance warnings. Missing materials use neutral gray; missing or unreadable textures use the material base color. Original uploads remain unchanged.", "items": { "$ref": "#/components/schemas/MeshCheckWarning" } }, "error": { "$ref": "#/components/schemas/ModelProcessingError" } } }, "PrintabilityCheckRunning": { "type": "object", "required": [ "status" ], "properties": { "status": { "enum": [ "pending", "processing" ], "type": "string" }, "longest_dimension_mm": { "type": "number", "minimum": 30, "maximum": 200 }, "waiting_for": { "type": "array", "items": { "enum": [ "mesh_check" ], "type": "string" } } } }, "PrintabilityCheckCompleted": { "type": "object", "required": [ "status", "longest_dimension_mm", "result" ], "properties": { "status": { "const": "completed", "type": "string" }, "longest_dimension_mm": { "type": "number", "minimum": 30, "maximum": 200 }, "result": { "$ref": "#/components/schemas/PrintabilityResult" } } }, "PrintabilityCheckFailed": { "type": "object", "required": [ "status", "longest_dimension_mm", "error" ], "properties": { "status": { "const": "failed", "type": "string" }, "longest_dimension_mm": { "type": "number", "minimum": 30, "maximum": 200 }, "error": { "$ref": "#/components/schemas/PrintabilityError" } } }, "PrintabilityResultPrintable": { "type": "object", "required": [ "passed", "decision", "blocking_mesh_checks", "incomplete_mesh_checks", "risks" ], "properties": { "passed": { "const": true, "type": "boolean" }, "decision": { "const": "printable", "type": "string" }, "blocking_mesh_checks": { "type": "array", "items": { "enum": [ "inverted_normals", "bad_edges", "planar_holes" ], "type": "string" } }, "incomplete_mesh_checks": { "type": "array", "items": { "enum": [ "inverted_normals", "bad_edges", "planar_holes" ], "type": "string" } }, "risks": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PrintRisk" } } } }, "PrintabilityResultRepairRequired": { "type": "object", "required": [ "passed", "decision", "blocking_mesh_checks", "incomplete_mesh_checks", "risks" ], "properties": { "passed": { "const": false, "type": "boolean" }, "decision": { "const": "repair_required", "type": "string" }, "blocking_mesh_checks": { "type": "array", "items": { "enum": [ "inverted_normals", "bad_edges", "planar_holes" ], "type": "string" } }, "incomplete_mesh_checks": { "type": "array", "items": { "enum": [ "inverted_normals", "bad_edges", "planar_holes" ], "type": "string" } }, "risks": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PrintRisk" } } } }, "ManufacturingEstimateUnavailable": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "unavailable" ] } } }, "ManufacturingEstimateProvisional": { "type": "object", "required": [ "status", "currency", "unit_price", "longest_dimension_mm", "pricing_version", "repair_cost_included" ], "properties": { "status": { "const": "provisional", "type": "string" }, "currency": { "const": "usd", "type": "string" }, "unit_price": { "type": "integer", "minimum": 0, "description": "Cents per printed copy; repair excluded." }, "longest_dimension_mm": { "type": "number", "minimum": 30, "maximum": 200 }, "pricing_version": { "type": "string" }, "repair_cost_included": { "const": false, "type": "boolean" } } } }, "headers": { "RequestID": { "description": "Request identifier for support. Send X-Request-ID with 8–64 ASCII letters, digits or hyphens to reuse that value; otherwise the server generates a UUID4 hex value. Include the returned X-Request-ID in support requests. Do not put secrets or account IDs in this value.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{8,64}$" }, "example": "support-request-0001" }, "IdempotentReplayed": { "description": "Present when the original successful response is replayed.", "schema": { "type": "string", "enum": [ "true" ] } }, "RetryAfter": { "description": "Seconds to wait before retrying the same request.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "RetryAfter_2": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds until the per-key read quota resets (1–60)." }, "RetryAfter_3": { "description": "Wait 60 seconds. Registration limit: 10 models per minute per account.", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "description": "Opaque model edit version. Changes only when the file, name or print size changes; processing and previews do not invalidate it. Send the complete quoted value in If-Match.", "schema": { "type": "string" }, "example": "\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"" }, "WWWAuthenticate": { "schema": { "type": "string" }, "example": "Bearer", "description": "API-key bearer authentication challenge." }, "RetryAfter_4": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds to wait before retrying." } }, "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key starting with ak_", "description": "Server-side business API key with the scope required by each endpoint. Revocation and permission changes can take up to 30 seconds to affect reads. Writes and payment access check the current key on every request." } }, "responses": { "Response409": { "description": "Request conflict.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/IdempotencyKeyReused" }, "idempotency_request_in_progress": { "$ref": "#/components/examples/IdempotencyRequestInProgress" } } } } }, "Response401": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "missing": { "$ref": "#/components/examples/Unauthenticated" } } } } }, "Response500": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Unexpected request failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "summary": "Quote request failed.", "value": { "code": "internal", "message": "Quote request failed." } } } } } }, "Response429": { "description": "600 GET/HEAD requests per minute per API key, shared across read endpoints. Retry after the number of seconds in Retry-After.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter_2" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "resource_exhausted": { "$ref": "#/components/examples/ResourceExhausted" } } } } }, "Response401_2": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "summary": "Credential that is not an API key", "value": { "code": "unauthenticated", "message": "Invalid credential. Server integrations use a business API key (ak_…)." } }, "missing_credential": { "summary": "Missing bearer credential", "value": { "code": "unauthenticated", "message": "A bearer credential is required." } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } } }, "Response500_2": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "summary": "Model request failed.", "value": { "code": "internal", "message": "Model request failed." } } } } } }, "Response503": { "description": "Required service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error_5" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "Response403": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Account lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/PermissionDenied" } } } } }, "Response401_3": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Unauthenticated" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } } }, "Response404": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Model missing, deleted or inaccessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "not_found": { "$ref": "#/components/examples/NotFound" } } } } }, "Response401_4": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "missing_credential": { "$ref": "#/components/examples/Unauthenticated" }, "invalid_key": { "summary": "Invalid API key.", "value": { "code": "unauthenticated", "message": "Invalid API key." } } } } } }, "Response403_2": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "models:write permission required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error_2" } } } } }, "Response412": { "description": "The model edit version no longer matches If-Match.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "precondition_failed": { "value": { "code": "precondition_failed", "message": "Model changed. Retrieve it and review your changes before retrying." } } } } } }, "Response413": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Request body too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/Error_3" } } } } }, "Response415": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Unsupported request content type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "$ref": "#/components/examples/UnsupportedMediaType" } } } } }, "Response404_2": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Model not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "not_found": { "$ref": "#/components/examples/NotFound" } } } } }, "Response401_5": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthenticated": { "$ref": "#/components/examples/Error" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } } }, "Response403_3": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "The API key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "permission_denied": { "summary": "permission denied", "value": { "code": "permission_denied", "message": "This key requires the orders:write scope." } } } } } }, "Response413_2": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Request body too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "error": { "summary": "Order requests cannot exceed 65536 bytes.", "value": { "code": "request_too_large", "message": "Order requests cannot exceed 65536 bytes." } } } } } }, "Response429_2": { "description": "Rate or account limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "resource_exhausted": { "summary": "resource exhausted", "value": { "code": "resource_exhausted", "message": "Order creation limit reached. Retry after 60 seconds." } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter_4" } } }, "Response500_3": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "internal": { "$ref": "#/components/examples/Internal" } } } } }, "Response503_2": { "description": "Service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unavailable": { "$ref": "#/components/examples/Unavailable" } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } }, "Response400": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalid_argument": { "$ref": "#/components/examples/InvalidArgument" } } } } }, "Response403_4": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "The API key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "permission_denied": { "$ref": "#/components/examples/PermissionDenied_2" } } } } }, "Response404_3": { "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } }, "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "not_found": { "$ref": "#/components/examples/NotFound_2" } } } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[!-~]{1,255}$" }, "description": "Account, method and path scoped retry key, retained for 24 hours from first use. Same body replays the original successful status and body. A changed body returns 409 idempotency_key_reused; an in-flight request returns 409 idempotency_request_in_progress with Retry-After. Retry transient failures with the same key and body." }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Page size, default 20, maximum 100; repeat on subsequent pages." }, "ModelId": { "name": "model_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelId" }, "description": "Public model ID returned in id; pass unchanged.", "example": "MD-739YQ549" }, "ModelId_2": { "name": "model_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ModelId" } }, "Limit_2": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of results." }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 }, "description": "Opaque next_cursor from the previous page. Keep the same account, resource, filters and limit." }, "IdempotencyKey_2": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[!-~]{1,255}$" }, "description": "Account, method and path scoped retry key, retained for 24 hours from first use. Same body replays the original successful status and body. A changed body returns 409 idempotency_key_reused; an in-flight request returns 409 idempotency_request_in_progress with Retry-After. Retry transient failures with the same key and body." }, "OrderId": { "name": "order_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrderId" }, "description": "Public order ID returned in id; pass unchanged.", "example": "OM-XMF1NT2E" } }, "examples": { "Error": { "summary": "unauthenticated", "value": { "code": "unauthenticated", "message": "A bearer credential is required." } }, "ModelNotFound": { "summary": "Model was not found.", "value": { "code": "model_not_found", "message": "Model was not found.", "details": [ { "field": "items[0].model_id", "message": "Model was not found." } ] } }, "PricingUnavailable": { "summary": "Current model and support measurements are unavailable. Contact support to recompute this model.", "value": { "code": "pricing_unavailable", "message": "Current model and support measurements are unavailable. Contact support to recompute this model.", "details": [ { "field": "items[0].model_id", "message": "Current model and support measurements are unavailable. Contact support to recompute this model." } ] } }, "Unauthenticated": { "summary": "A bearer credential is required.", "value": { "code": "unauthenticated", "message": "A bearer credential is required." } }, "PermissionDenied": { "summary": "This key requires the models:read scope.", "value": { "code": "permission_denied", "message": "This key requires the models:read scope." } }, "IdempotencyKeyReused": { "value": { "code": "idempotency_key_reused", "message": "Idempotency-Key was already used with a different request body.", "details": [ { "field": "Idempotency-Key", "message": "Use the original body or a new key." } ] } }, "IdempotencyRequestInProgress": { "value": { "code": "idempotency_request_in_progress", "message": "A request with this Idempotency-Key is still running. Retry shortly." } }, "ModelNotReady": { "summary": "Model inspection has not completed.", "value": { "code": "model_not_ready", "message": "Model inspection has not completed.", "details": [ { "field": "items[0].model_id", "message": "Model inspection has not completed." } ] } }, "ModelMeasurementsPending": { "summary": "Model measurements have not completed.", "value": { "code": "model_not_ready", "message": "Model measurements have not completed.", "details": [ { "field": "items[0].model_id", "message": "Model measurements have not completed." } ] } }, "UnsupportedMediaType": { "summary": "Unsupported media type \"text/plain\" in request.", "value": { "code": "unsupported_media_type", "message": "Unsupported media type \"text/plain\" in request." } }, "ResourceExhausted": { "summary": "Read quota exceeded", "value": { "code": "resource_exhausted", "message": "Request was throttled. Expected available in 60 seconds." } }, "Example": { "summary": "Two printed models, with ground and express shipping choices.", "value": { "id": "quote_6c82bd3e319b4bb099310d54a761879e", "created_at": "2026-09-17T18:00:00.000000Z", "expires_at": "2026-09-17T18:30:00.000000Z", "currency": "usd", "items": [ { "model_id": "MD-739YQ549", "longest_dimension_mm": 100, "quantity": 2, "dimensions_mm": { "x": 100, "y": 50, "z": 20 }, "unit_price": 2460, "subtotal": 4920, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null } } ], "shipping_address": { "name": "Test Recipient", "line1": "123 EXAMPLE ST", "city": "SEATTLE", "state": "WA", "postal_code": "98101", "country": "US" }, "buyer": { "company": "Example Store", "email": "orders@example.com" }, "estimated_production_business_days": null, "shipping_options": [ { "id": "shipopt_6c82bd3e319b4bb099310d54a761879e", "name": "UPS Ground", "totals": { "subtotal": 4920, "shipping": 1000, "total": 5920 }, "estimated_transit_business_days": { "min": 3, "max": 3 }, "estimated_delivery": null, "carrier": "UPS" }, { "id": "shipopt_8c1f25d94e3142f8b9a70635d42c81e0", "name": "USPS Priority Mail Express", "totals": { "subtotal": 4920, "shipping": 2000, "total": 6920 }, "estimated_transit_business_days": { "min": 1, "max": 1 }, "estimated_delivery": null, "carrier": "USPS" } ], "pricing_version": "pv_20261001_model_repair_01", "status": "open" } }, "ModelRepairEstimatePending": { "summary": "model repair estimate pending", "value": { "code": "model_repair_estimate_pending", "message": "Wait for the Model repair price before checkout." } }, "Storage": { "summary": "Quote storage is temporarily unavailable.", "value": { "code": "unavailable", "message": "Quote storage is temporarily unavailable." } }, "Accepted": { "summary": "Model accepted; processing", "value": { "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 } }, "MissingLongestDimensionMm": { "summary": "Supply a finite number from 30 to 200 millimeters.", "value": { "code": "invalid_argument", "message": "Supply a finite number from 30 to 200 millimeters.", "details": [ { "field": "longest_dimension_mm", "message": "Supply a finite number from 30 to 200 millimeters." } ] } }, "Error_2": { "summary": "This key requires the models:write scope.", "value": { "code": "permission_denied", "message": "This key requires the models:write scope." } }, "Error_3": { "summary": "Model requests cannot exceed 65536 bytes.", "value": { "code": "request_too_large", "message": "Model requests cannot exceed 65536 bytes." } }, "Error_4": { "summary": "Model processing limit reached. Retry after 60 seconds.", "value": { "code": "resource_exhausted", "message": "Model processing limit reached. Retry after 60 seconds." } }, "NotFound": { "value": { "code": "model_not_found", "message": "Model was not found." } }, "Error_5": { "summary": "Model storage is temporarily unavailable.", "value": { "code": "unavailable", "message": "Model storage is temporarily unavailable." } }, "Pending": { "summary": "Awaiting acceptance", "value": { "id": "OM-XMF1NT2E", "created_at": "2026-09-18T18:00:00.000000Z", "quote_id": "quote_6c82bd3e319b4bb099310d54a761879e", "currency": "usd", "items": [ { "model_id": "MD-739YQ549", "quantity": 2, "unit_price": 3000, "subtotal": 6000, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "longest_dimension_mm": 100, "dimensions_mm": { "x": 50, "y": 100, "z": 40 } } ], "shipping_address": { "name": "Alex Example", "company": "Example Retail", "line1": "123 Example Street", "city": "Seattle", "state": "WA", "postal_code": "98101", "country": "US" }, "buyer": { "company": "Example Store", "email": "orders@example.com" }, "shipping_option": { "id": "shipopt_6c82bd3e319b4bb099310d54a761879e", "name": "Standard", "totals": { "subtotal": 6000, "shipping": 1000, "total": 7000 }, "estimated_transit_business_days": { "min": 3, "max": 5 }, "estimated_delivery": null }, "external_id": "checkout-123", "purchase_order_number": "PO-2026-0042", "metadata": { "project": "launch" }, "updated_at": "2026-09-18T18:00:00.000000Z", "status": "awaiting_payment", "events": [ { "id": "evt_00000000000000000000000000000001", "sequence": 1, "type": "order.created", "at": "2026-09-18T18:00:00.000000Z", "reason": null, "data": { "status": "awaiting_payment" } } ], "estimated_ship_date": null, "estimated_delivery": null, "hold": null, "payment": { "status": "unpaid", "amount": 7000, "currency": "usd", "method": null, "paid_at": null, "receipt_url": null }, "shipment": null, "pricing_version": "pv_2026_09_a", "preparation": { "status": "completed", "items": [ { "model_id": "MD-739YQ549", "status": "completed", "longest_dimension_mm": 100 } ] }, "expires_at": "2026-09-19T18:00:00.000000Z" } }, "InvalidArgument": { "summary": "invalid argument", "value": { "code": "invalid_argument", "message": "Check the documented fields." } }, "Cancelled": { "summary": "Cancelled before production", "value": { "id": "OM-XMF1NT2E", "created_at": "2026-09-18T18:00:00.000000Z", "quote_id": "quote_6c82bd3e319b4bb099310d54a761879e", "currency": "usd", "items": [ { "model_id": "MD-739YQ549", "quantity": 2, "unit_price": 3000, "subtotal": 6000, "repair": { "required": false, "applied": false, "reason": null, "status": "not_applied", "fee": 0, "covered_by_order_id": null }, "longest_dimension_mm": 100, "dimensions_mm": { "x": 50, "y": 100, "z": 40 } } ], "shipping_address": { "name": "Alex Example", "company": "Example Retail", "line1": "123 Example Street", "city": "Seattle", "state": "WA", "postal_code": "98101", "country": "US" }, "buyer": { "company": "Example Store", "email": "orders@example.com" }, "shipping_option": { "id": "shipopt_6c82bd3e319b4bb099310d54a761879e", "name": "Standard", "totals": { "subtotal": 6000, "shipping": 1000, "total": 7000 }, "estimated_transit_business_days": { "min": 3, "max": 5 }, "estimated_delivery": null }, "external_id": "checkout-123", "purchase_order_number": "PO-2026-0042", "metadata": { "project": "launch" }, "updated_at": "2026-09-18T18:01:00.000000Z", "status": "cancelled", "events": [ { "id": "evt_00000000000000000000000000000001", "sequence": 1, "type": "order.created", "at": "2026-09-18T18:00:00.000000Z", "reason": null, "data": { "status": "awaiting_payment" } }, { "id": "evt_0000000000000000000000000000000c", "sequence": 2, "type": "order.cancelled", "at": "2026-09-18T18:01:00.000000Z", "reason": null, "data": { "previous_status": "awaiting_payment", "status": "cancelled" } } ], "estimated_ship_date": null, "estimated_delivery": null, "hold": null, "payment": { "status": "cancelled", "amount": 7000, "currency": "usd", "method": null, "paid_at": null, "receipt_url": null }, "shipment": null, "pricing_version": "pv_2026_09_a", "preparation": { "status": "completed", "items": [ { "model_id": "MD-739YQ549", "status": "completed", "longest_dimension_mm": 100 } ] }, "expires_at": null } }, "PermissionDenied_2": { "summary": "permission denied", "value": { "code": "permission_denied", "message": "This key requires the orders:read scope." } }, "NotFound_2": { "value": { "code": "order_not_found", "message": "Order was not found." } }, "Internal": { "summary": "internal", "value": { "code": "internal", "message": "Order request failed." } }, "Unavailable": { "summary": "unavailable", "value": { "code": "unavailable", "message": "Payment provider is temporarily unavailable. Retry with the same Idempotency-Key." } } } } }