{"openapi":"3.1.2","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"Create Prints API","version":"1.1.0","summary":"Turn images into wall prints","description":"Create Prints turns images and generated artwork into physical wall prints, posters, and framed artwork. It prepares chat images for printing, shows compatible products and prices, creates secure checkout links, and tracks Create Prints orders through delivery.","contact":{"name":"Create Prints support","url":"https://www.createprints.ai/contact"},"license":{"name":"Proprietary","url":"https://www.createprints.ai/terms"}},"servers":[{"url":"https://api.createprints.ai","description":"Create Prints API origin"}],"externalDocs":{"description":"Create Prints developer resources","url":"https://www.createprints.ai/developers"},"tags":[{"name":"Artwork","description":"Create, import, inspect, retry, and list account-owned artwork."},{"name":"Account","description":"Read account resources used by the artwork workflow."},{"name":"Product discovery","description":"Read print variants, generation dimensions, frames, prices, and postage estimates."},{"name":"Checkout","description":"Create a human-completed checkout and inspect payment and fulfilment progress."},{"name":"Orders","description":"List orders belonging to the authenticated account."}],"paths":{"/api/image-generations":{"post":{"operationId":"createArtwork","summary":"Queue an artwork generation","description":"Spends one available generation credit and queues an artwork job. For text-only creation, send JSON with `inputType: describe`, a prompt, and an image-model size. Multipart form data additionally supports an uploaded reference image; `printPhoto` and `interiorPhoto` require that image. An interior photo supplies palette, mood, and style context—the output is standalone artwork, not a recreation of the room. Use the selected print variant's exact `generation.imageModelSize` to guarantee aspect compatibility at checkout.","tags":["Artwork"],"security":[{"agentApiKey":[]},{"agentBearer":[]},{"userSessionBearer":[]},{"oauth2":["artwork:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateArtworkJson"},"example":{"inputType":"describe","prompt":"A calm abstract coastal landscape in muted blue and sand tones","size":"1536x1024","keywords":["coastal","abstract","calm"]}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateArtworkMultipart"}}}},"responses":{"202":{"description":"The artwork job was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueuedArtwork"},"example":{"jobId":"1ae94a6e-f1dd-44c7-8314-a869e8357cc1","status":"queued","statusUrl":"/api/image-generations?id=1ae94a6e-f1dd-44c7-8314-a869e8357cc1","creditsRemaining":4}}}},"400":{"description":"Missing or invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getArtworkStatus","summary":"Get an artwork job","description":"Returns processing state and print eligibility for one account-owned artwork. `purchasable` becomes true only after processing completes and an image is uploaded. For a private import, image paths are returned only to the signed-in owner using a user-session token and are null for account API keys and MCP access tokens.","tags":["Artwork"],"security":[{"agentApiKey":[]},{"agentBearer":[]},{"userSessionBearer":[]},{"oauth2":["artwork:read"]}],"parameters":[{"$ref":"#/components/parameters/ArtworkJobId"}],"responses":{"200":{"description":"Current artwork state and metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtworkStatus"}}}},"400":{"description":"Missing or invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The resource was not found for the authenticated account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/image-generations/import":{"post":{"operationId":"importArtwork","summary":"Import a standalone artwork file","description":"Runs safety and artwork-presentation checks on a PNG, JPEG, or WebP file up to 20 MB. An accepted file is stored privately and returned as completed and purchasable (`201`). If it appears to be a room scene, framed mockup, or another image rather than standalone artwork, no bytes or job are retained and the endpoint returns a structured rejection with HTTP `200`. If the safety service cannot run, the import is not accepted and the endpoint returns `503`.","tags":["Artwork"],"security":[{"agentApiKey":[]},{"agentBearer":[]},{"userSessionBearer":[]},{"oauth2":["artwork:create"]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary","description":"Standalone PNG, JPEG, or WebP artwork; maximum 20 MB."},"title":{"type":"string","description":"Optional title stored with an accepted import."}}}}}},"responses":{"200":{"description":"The file was rejected as non-standalone artwork and was not retained.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectedImport"}}}},"201":{"description":"The artwork passed both checks and was retained privately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedImport"}}}},"400":{"description":"Missing or invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The image safety check was unavailable; the file was not imported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/image-generations/list":{"get":{"operationId":"listArtworks","summary":"List account artwork","description":"Returns the authenticated account's artwork newest first. Set `purchasable=true` to retain only completed jobs with uploaded images. Private image paths are exposed only to the signed-in owner using a user-session token; API keys and MCP tokens receive `null`.","tags":["Artwork"],"security":[{"agentApiKey":[]},{"agentBearer":[]},{"userSessionBearer":[]},{"oauth2":["artwork:read"]}],"parameters":[{"name":"limit","in":"query","description":"Maximum records to return. Values are clamped to 1–50.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"cursor","in":"query","description":"Return records created before this ISO 8601 timestamp, normally the previous response's cursor.","schema":{"type":"string","format":"date-time"}},{"name":"purchasable","in":"query","description":"Return only completed artwork with an uploaded image.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"A cursor-paginated artwork page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtworkList"}}}},"400":{"description":"Missing or invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/image-generations/retry":{"post":{"operationId":"retryArtworkGeneration","summary":"Requeue a stalled artwork job","description":"Requeues an account-owned processing job only after it has been inactive for at least 90 seconds. Completed, failed, and actively processing jobs return `409`; create a new generation instead of retrying a job marked failed.","tags":["Artwork"],"security":[{"agentApiKey":[]},{"agentBearer":[]},{"userSessionBearer":[]},{"oauth2":["artwork:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtworkJobRequest"}}}},"responses":{"202":{"description":"The stalled job was requeued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequeuedArtwork"}}}},"400":{"description":"Missing or invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The resource was not found for the authenticated account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The resource state does not permit this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/credits-balance":{"get":{"operationId":"getCreditsBalance","summary":"Get the artwork-generation credit balance","description":"Returns the remaining generation-job count. This endpoint currently accepts a Create Prints MCP OAuth access token with `orders:read` or a signed-in user-session token. It does not accept an account API key.","tags":["Account"],"security":[{"userSessionBearer":[]},{"oauth2":["orders:read"]}],"responses":{"200":{"description":"Current remaining generation credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsBalance"},"example":{"generation_jobs_count":4,"creditsRemaining":4}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent-print-options":{"get":{"operationId":"listAgentPrintOptions","summary":"List purchasable physical print variants","description":"Returns canonical `productVariantId` values, print dimensions, format, optional extras, compatible generation size, frame choices, product price, and a single-item postage estimate. That estimate is not final basket postage: checkout recalculates postage for quantity and multi-item baskets. Use `generation.imageModelSize` when creating artwork for the selected variant.","tags":["Product discovery"],"security":[],"parameters":[{"name":"country","in":"query","description":"Supported destination market. `GB` returns GBP; `US` returns USD.","schema":{"type":"string","enum":["GB","US"],"default":"GB"}}],"responses":{"200":{"description":"Currently purchasable physical print variants.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrintOptions"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/print-sizes":{"get":{"operationId":"listPrintSizes","summary":"List unframed print sizes","description":"Returns the legacy unframed-print size list in GBP. New agent integrations should normally use `/api/agent-print-options`, which also supplies generation dimensions, formats, frames, currency selection, and postage estimates.","tags":["Product discovery"],"security":[],"responses":{"200":{"description":"Available unframed print sizes and GBP prices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrintSizes"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/frame-options":{"get":{"operationId":"listFrameOptions","summary":"List frame colours","description":"Returns frame-option identifiers and labels. `frameOptionId` is required only when the chosen product variant has `requiresFrameOption: true`.","tags":["Product discovery"],"security":[],"responses":{"200":{"description":"Available frame colour options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FrameOptions"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/checkout":{"post":{"operationId":"createAgentCheckout","summary":"Create a human-completed checkout","description":"Creates a checkout link on the Create Prints website for one or more completed, account-owned artworks. Every artwork must have an uploaded image and its aspect must match the selected variant. The agent returns `checkoutUrl` to the person, who reviews the basket and completes payment. A basket supports at most 20 line items; each line supports quantity 1–20. `GB` uses GBP and `US` uses USD. Multi-item or multi-quantity shipping is quoted before checkout; a temporary quote failure returns `503` with `retryable: true`.","tags":["Checkout"],"security":[{"agentApiKey":[]},{"agentBearer":[]},{"oauth2":["checkout:create"]}],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Optional opaque key passed to checkout creation. Reuse it when retrying the same logical request.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"},"example":{"country":"GB","jobId":"1ae94a6e-f1dd-44c7-8314-a869e8357cc1","productVariantId":"a5894107-bd91-48fb-a37c-49718c82ec84","quantity":1}}}},"responses":{"200":{"description":"Checkout was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"400":{"description":"Missing or invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The resource was not found for the authenticated account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The resource state does not permit this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The selected product is no longer available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The payment provider could not create the checkout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A shipping quote could not be obtained for the basket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/checkout-status":{"get":{"operationId":"getAgentCheckoutStatus","summary":"Get checkout, fulfilment, and shipment status","description":"For a simple payment lookup, provide `sessionId` and omit `view`. For the combined agent workflow, set `view=agent` and provide at least one of `jobId`, `sessionId`, or `orderId`. Agent view combines artwork readiness, checkout state, print-asset preparation, production, shipments, and a machine-readable `nextAction`. A signed-in user-session token is accepted for this read operation in addition to account API keys and MCP OAuth tokens.","tags":["Checkout"],"security":[{"agentApiKey":[]},{"agentBearer":[]},{"userSessionBearer":[]},{"oauth2":["checkout:read"]}],"parameters":[{"$ref":"#/components/parameters/SessionId"},{"name":"jobId","in":"query","description":"Account-owned artwork job ID.","schema":{"type":"string","format":"uuid"}},{"name":"orderId","in":"query","description":"Account-owned order ID.","schema":{"type":"string","format":"uuid"}},{"name":"view","in":"query","description":"Set to `agent` for combined workflow status.","schema":{"type":"string","const":"agent"}}],"responses":{"200":{"description":"Current payment and, when requested, fulfilment and shipment state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutStatus"}}}},"400":{"description":"Missing or invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The resource was not found for the authenticated account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"retryAgentFulfilment","summary":"Retry production submission for prepared print assets","description":"Attempts production submission for an account-owned order whose print assets are already prepared. It does not restart image upscaling. An already-submitted order returns `200` with `accepted: false` and `reason: already_submitted`; orders still preparing assets or containing failed assets return `409`. The endpoint currently returns `200` after a successful submission attempt.","tags":["Checkout"],"security":[{"agentApiKey":[]},{"agentBearer":[]},{"oauth2":["checkout:create"]}],"parameters":[{"name":"action","in":"query","required":true,"description":"Selects the fulfilment retry action.","schema":{"type":"string","const":"retry-fulfillment"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderIdRequest"}}}},"responses":{"200":{"description":"The order was already submitted or its prepared assets were submitted to production.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfilmentRetry"}}}},"400":{"description":"Missing or invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The resource was not found for the authenticated account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The resource state does not permit this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/orders/list":{"get":{"operationId":"listOrders","summary":"List account orders","description":"Returns the authenticated account's orders newest first, including a short reference, customer-facing status, total item quantity, charged total, currency, and checkout-session ID. The current endpoint formats order totals in GBP.","tags":["Orders"],"security":[{"agentApiKey":[]},{"agentBearer":[]},{"oauth2":["orders:read"]}],"parameters":[{"name":"limit","in":"query","description":"Maximum records to return. Values are clamped to 1–50.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"cursor","in":"query","description":"Return records created before this ISO 8601 timestamp, normally the previous response's cursor.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"A cursor-paginated order page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"}}}},"401":{"description":"The credential is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The credential lacks the required scope or cannot perform this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Create Prints could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"agentApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Create Prints account API key beginning with `cp_`. Required scopes vary by operation."},"agentBearer":{"type":"http","scheme":"bearer","description":"Account API key (`cp_…`) or MCP OAuth token (`cp_mcp_access_…`) in Authorization."},"userSessionBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Signed-in Create Prints user-session token; supported only where this scheme is listed."},"oauth2":{"type":"oauth2","description":"Create Prints OAuth 2.0 authorization-code flow with PKCE for MCP and agent clients.","flows":{"authorizationCode":{"authorizationUrl":"https://api.createprints.ai/api/oauth/authorize","tokenUrl":"https://api.createprints.ai/api/oauth/token","scopes":{"artwork:create":"Create, import, and retry artwork jobs.","artwork:read":"Read and list artwork jobs.","print_options:read":"Read print variants, frames, prices, and postage estimates.","checkout:create":"Create checkout sessions and retry production submission.","checkout:read":"Read checkout, fulfilment, and shipment status.","orders:read":"Read orders and, on the current credit endpoint, generation credits."}}}}},"parameters":{"ArtworkJobId":{"name":"id","in":"query","required":true,"description":"Account-owned artwork job ID.","schema":{"type":"string","format":"uuid"}},"SessionId":{"name":"sessionId","in":"query","description":"Checkout-session ID returned by checkout creation.","schema":{"type":"string","pattern":"^cs_"}}},"schemas":{"Error":{"type":"object","description":"Errors use `error`; some endpoints also return a stable `code`, validation `details`, or `retryable` hint.","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"array","items":{"type":"string"}},"retryable":{"type":"boolean"}},"additionalProperties":true},"Aspect":{"type":"string","enum":["square","portrait","landscape"]},"CreateArtworkJson":{"type":"object","required":["prompt","size"],"properties":{"inputType":{"type":"string","enum":["describe","printPhoto","interiorPhoto"],"default":"describe"},"prompt":{"type":"string","minLength":1,"description":"Artwork description; required for JSON."},"size":{"type":"string","pattern":"^[0-9]+x[0-9]+$","description":"Width and height must be multiples of 16; longest side ≤3840 px; aspect ≤3:1; 655,360–8,294,400 total pixels. Prefer the selected variant's `generation.imageModelSize`.","examples":["1536x1536","1024x1536","1536x1024"]},"keywords":{"type":"array","items":{"type":"string"}},"colors":{"type":"array","items":{"type":"string"}},"styleId":{"type":["string","integer","null"]},"seedId":{"type":["string","null"]},"forceOriginalPrompt":{"type":"boolean","default":false},"referenceImageUrl":{"type":["string","null"],"format":"uri"},"revision":{"type":"boolean","default":false}},"additionalProperties":true},"CreateArtworkMultipart":{"type":"object","required":["inputType","size"],"properties":{"inputType":{"type":"string","enum":["describe","printPhoto","interiorPhoto"]},"size":{"type":"string","examples":["1536x1536","1024x1536","1536x1024"]},"prompt":{"type":"string","description":"Required for `describe` unless an image is supplied."},"image":{"type":"string","format":"binary","description":"Required for photo inputs; optional for `describe`."},"keywords":{"type":"string","description":"Comma-separated values or a JSON array encoded as a form field."},"colors":{"type":"string","description":"Comma-separated values or a JSON array encoded as a form field."},"styleId":{"type":"string"},"seedId":{"type":"string"},"creativeDirection":{"type":"string"},"forceOriginalPrompt":{"type":"string","enum":["true","false"],"default":"false"},"revision":{"type":"string","enum":["true","false"],"default":"false"}}},"QueuedArtwork":{"type":"object","required":["jobId","status","statusUrl","creditsRemaining"],"properties":{"jobId":{"type":"string","format":"uuid"},"status":{"type":"string","const":"queued"},"statusUrl":{"type":"string","description":"Relative polling URL."},"creditsRemaining":{"type":"integer","minimum":0}}},"ArtworkJobRequest":{"type":"object","required":["jobId"],"properties":{"jobId":{"type":"string","format":"uuid"}},"additionalProperties":false},"RequeuedArtwork":{"type":"object","required":["code","jobId","status"],"properties":{"code":{"type":"string","const":"ok"},"jobId":{"type":"string","format":"uuid"},"status":{"type":"string","const":"requeued"}}},"ImportWarning":{"type":"object","required":["code","severity","message"],"properties":{"code":{"type":"string"},"severity":{"type":"string","const":"warning"},"message":{"type":"string"}}},"ArtworkCheck":{"type":"object","description":"Standalone-artwork classifier result; fields may expand.","properties":{"status":{"type":"string"},"warningCodes":{"type":"array","items":{"type":"string"}},"error":{"type":["string","null"]}},"additionalProperties":true},"AcceptedImport":{"type":"object","required":["jobId","status","purchasable","imageUploaded","retained","imagePrivate","aspect","width","height","warnings"],"properties":{"jobId":{"type":"string","format":"uuid"},"status":{"type":"string","const":"complete"},"purchasable":{"type":"boolean","const":true},"imageUploaded":{"type":"boolean","const":true},"retained":{"type":"boolean","const":true},"imagePrivate":{"type":"boolean","const":true},"aspect":{"$ref":"#/components/schemas/Aspect"},"width":{"type":"integer","minimum":1},"height":{"type":"integer","minimum":1},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ImportWarning"}},"artworkCheck":{"$ref":"#/components/schemas/ArtworkCheck"}}},"RejectedImport":{"type":"object","required":["status","purchasable","imageUploaded","retained","aspect","width","height","warnings","artworkCheck"],"properties":{"status":{"type":"string","const":"rejected"},"purchasable":{"type":"boolean","const":false},"imageUploaded":{"type":"boolean","const":false},"retained":{"type":"boolean","const":false},"aspect":{"$ref":"#/components/schemas/Aspect"},"width":{"type":"integer","minimum":1},"height":{"type":"integer","minimum":1},"warnings":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ImportWarning"}},"artworkCheck":{"$ref":"#/components/schemas/ArtworkCheck"}}},"ArtworkStatus":{"type":"object","required":["jobId","id","status","statusCode","creditsRemaining","imageUploaded","imagePrivate","purchasable","aspect","imageModelSize","colorScheme"],"properties":{"jobId":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid","description":"Legacy alias of `jobId`."},"status":{"type":"string","enum":["processing","failed","complete","unknown"]},"statusCode":{"type":"integer","enum":[1,2,3]},"creditsRemaining":{"type":"integer","minimum":0},"imageUploaded":{"type":"boolean"},"imagePaths":{"type":["array","null"],"items":{"type":"string"}},"image_paths":{"type":["array","null"],"items":{"type":"string"}},"imagePrivate":{"type":"boolean"},"visibility":{"type":["string","null"]},"source":{"type":["string","null"]},"purchasable":{"type":"boolean"},"aspect":{"$ref":"#/components/schemas/Aspect"},"imageModelSize":{"type":"string"},"promptSize":{"type":["integer","null"]},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"originalPrompt":{"type":["string","null"]},"revisedPrompt":{"type":["string","null"]},"keywords":{"type":["array","null"],"items":{"type":"string"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ImportWarning"}},"artworkCheck":{"$ref":"#/components/schemas/ArtworkCheck"},"colorScheme":{"$ref":"#/components/schemas/ColorScheme"}},"additionalProperties":true},"ColorScheme":{"type":"object","description":"Persisted colour classification and affect analysis. Legacy palette fields retain their stored JSON value shapes.","required":["colorPsychology","colorPalette","dominantColor","vibrantColor","complementaryColors","affect"],"properties":{"colorCategory":{"type":["string","null"]},"colorPsychology":{"type":"object","required":["impactLevel","primaryTrait"],"properties":{"impactLevel":{"type":["string","null"]},"primaryTrait":{"type":["string","null"]}}},"recommendedRoom":{"type":["string","null"]},"colorPalette":{"type":"array","items":{}},"dominantColor":{"type":"array","items":{}},"vibrantColor":{"type":"array","items":{}},"complementaryColors":{"type":"array","items":{}},"affect":{"oneOf":[{"$ref":"#/components/schemas/ColorAffect"},{"type":"null"}]}}},"ColorAffect":{"type":"object","description":"Continuous mood and colour analysis generated from the artwork palette.","required":["arousal","valence","warmth","complexity","emotions","primaryTrait","temperature","energyLevel","impactLevel","harmony","rooms","recommendedRooms","rationale"],"properties":{"arousal":{"type":"number","minimum":0,"maximum":1},"valence":{"type":"number","minimum":0,"maximum":1},"warmth":{"type":"number","minimum":0,"maximum":1},"complexity":{"type":["number","null"],"minimum":0,"maximum":1},"emotions":{"type":"array","maxItems":4,"items":{"type":"string"}},"primaryTrait":{"type":"string"},"temperature":{"type":"string"},"energyLevel":{"type":"string"},"impactLevel":{"type":"string"},"harmony":{"type":"object","required":["type","hueClusters"],"properties":{"type":{"type":"string"},"hueClusters":{"type":"integer","minimum":0}}},"rooms":{"type":"array","maxItems":5,"items":{"type":"object","required":["room","score"],"properties":{"room":{"type":"string"},"score":{"type":"number","minimum":0,"maximum":1}}}},"recommendedRooms":{"type":"array","maxItems":3,"items":{"type":"string"}},"rationale":{"type":"string"}},"additionalProperties":true},"ArtworkListItem":{"type":"object","required":["jobId","status","purchasable","imagePrivate","createdAt"],"properties":{"jobId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["processing","failed","complete","unknown"]},"purchasable":{"type":"boolean"},"title":{"type":["string","null"]},"imagePaths":{"type":["array","null"],"items":{"type":"string"}},"imagePrivate":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"ArtworkList":{"type":"object","required":["jobs","cursor"],"properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/ArtworkListItem"}},"cursor":{"type":["string","null"],"format":"date-time"}}},"CreditsBalance":{"type":"object","required":["generation_jobs_count","creditsRemaining"],"properties":{"generation_jobs_count":{"type":["integer","null"],"minimum":0},"creditsRemaining":{"type":["integer","null"],"minimum":0}}},"Option":{"type":"object","required":["id","value","name"],"properties":{"id":{"type":["integer","string"]},"value":{"type":["string","null"]},"name":{"type":"string"}}},"GenerationSpec":{"type":"object","required":["aspect","imageModelSize","promptSizeId"],"properties":{"aspect":{"$ref":"#/components/schemas/Aspect"},"imageModelSize":{"type":"string","examples":["1536x1536","1024x1536","1536x1024"]},"promptSizeId":{"type":"integer","enum":[1,2,3]}}},"ProductVariant":{"type":"object","required":["productVariantId","productId","sizeOptionId","size","format","extra","generation","requiresFrameOption","frameOptions","price","priceFormatted","shippingPrice","shippingPriceFormatted","estimatedCheckoutTotal","estimatedCheckoutTotalFormatted","shipping","checkout"],"properties":{"productVariantId":{"type":"string","format":"uuid"},"productId":{"type":["string","integer"]},"sku":{"type":["string","null"]},"sizeOptionId":{"type":"string","format":"uuid","description":"Legacy alias; use `productVariantId`."},"size":{"$ref":"#/components/schemas/Option"},"format":{"$ref":"#/components/schemas/Option"},"extra":{"oneOf":[{"$ref":"#/components/schemas/Option"},{"type":"null"}]},"generation":{"$ref":"#/components/schemas/GenerationSpec"},"requiresFrameOption":{"type":"boolean"},"frameOptions":{"type":"array","items":{"$ref":"#/components/schemas/Option"}},"price":{"type":"number","minimum":0},"priceFormatted":{"type":"string"},"shippingPrice":{"type":["number","null"],"minimum":0},"shippingPriceFormatted":{"type":["string","null"]},"estimatedCheckoutTotal":{"type":["number","null"],"minimum":0},"estimatedCheckoutTotalFormatted":{"type":["string","null"]},"shipping":{"type":"object","required":["price","priceFormatted","includedInPrice","note"],"properties":{"price":{"type":["number","null"]},"priceFormatted":{"type":["string","null"]},"includedInPrice":{"type":"boolean","const":false},"note":{"type":"string"}}},"checkout":{"type":"object","required":["productVariantId","frameOptionId"],"properties":{"productVariantId":{"type":"string","format":"uuid"},"frameOptionId":{"type":["string","null"]}}}}},"PrintOptions":{"type":"object","required":["currency","usage","productVariants"],"properties":{"currency":{"type":"string","enum":["GBP","USD"]},"usage":{"type":"string"},"productVariants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}}}},"PrintSize":{"type":"object","required":["id","productVariantId","sizeOptionId","name","price","priceFormatted"],"properties":{"id":{"type":"string","format":"uuid"},"productVariantId":{"type":"string","format":"uuid"},"sizeOptionId":{"type":"string","format":"uuid"},"name":{"type":"string"},"price":{"type":"number","minimum":0},"priceFormatted":{"type":"string"}}},"PrintSizes":{"type":"object","required":["sizes"],"properties":{"sizes":{"type":"array","items":{"$ref":"#/components/schemas/PrintSize"}}}},"FrameOptions":{"type":"object","required":["frameOptions"],"properties":{"frameOptions":{"type":"array","items":{"$ref":"#/components/schemas/Option"}}}},"CheckoutItem":{"type":"object","required":["jobId","productVariantId"],"properties":{"jobId":{"type":"string","format":"uuid"},"productVariantId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1,"maximum":20,"default":1},"frameOptionId":{"type":"integer","description":"Required for framed variants; invalid for unframed variants."}}},"CheckoutRequest":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/CheckoutItem"},{"type":"object","properties":{"country":{"type":"string","enum":["GB","US"],"default":"GB"}}}]},{"type":"object","required":["items"],"properties":{"country":{"type":"string","enum":["GB","US"],"default":"GB"},"items":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/CheckoutItem"}}}}]},"CheckoutResponse":{"type":"object","required":["code","checkoutUrl","checkoutSessionId","currency"],"properties":{"code":{"type":"string","const":"ok"},"checkoutUrl":{"type":"string","format":"uri","description":"Create Prints website URL for human review and payment."},"checkoutSessionId":{"type":"string","pattern":"^cs_"},"basketId":{"type":"string","format":"uuid"},"jobId":{"type":"string","format":"uuid"},"productVariantId":{"type":"string","format":"uuid"},"productAmountCents":{"type":"integer","minimum":0},"shippingAmountCents":{"type":"integer","minimum":0},"totalAmountCents":{"type":"integer","minimum":0},"currency":{"type":"string","enum":["GBP","USD"]},"productAmountFormatted":{"type":"string"},"shippingAmountFormatted":{"type":"string"},"totalAmountFormatted":{"type":"string"}}},"SimpleCheckoutStatus":{"type":"object","required":["checkoutSessionId","status","paymentStatus","orderId"],"properties":{"checkoutSessionId":{"type":"string","pattern":"^cs_"},"status":{"type":["string","null"]},"paymentStatus":{"type":["string","null"]},"orderId":{"type":["string","null"],"format":"uuid"}}},"AgentJobState":{"type":"object","required":["id","status","purchasable","nextAction"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"purchasable":{"type":"boolean"},"nextAction":{"type":"string"}}},"AgentCheckoutState":{"type":"object","required":["sessionId","status","paymentStatus","orderId","nextAction"],"properties":{"sessionId":{"type":["string","null"]},"status":{"type":["string","null"]},"paymentStatus":{"type":["string","null"]},"orderId":{"type":["string","null"],"format":"uuid"},"nextAction":{"type":"string"}}},"FulfilmentItem":{"type":"object","required":["id","generationJobId","productVariantId","quantity","status"],"properties":{"id":{"type":"string","format":"uuid"},"generationJobId":{"type":"string","format":"uuid"},"productVariantId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1},"status":{"type":"string","enum":["pending","ready","failed"]}}},"FulfilmentStatus":{"type":"object","required":["orderId","stage","retryable","nextAction"],"properties":{"orderId":{"type":"string","format":"uuid"},"stage":{"type":"string"},"retryable":{"type":"boolean"},"nextAction":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfilmentItem"}},"retryFulfillment":{"type":"object","additionalProperties":true}}},"Shipment":{"type":"object","required":["status","shippedAt","carrier","trackingNumber","trackingUrl"],"properties":{"status":{"type":"string"},"shippedAt":{"type":["string","null"],"format":"date-time"},"carrier":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"trackingUrl":{"type":["string","null"],"format":"uri"}}},"ProductionStatus":{"type":"object","required":["stage","isShipped","shipments","updatedAt","nextAction"],"properties":{"stage":{"type":"string"},"isShipped":{"type":"boolean"},"shipments":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"}},"updatedAt":{"type":["string","null"],"format":"date-time"},"nextAction":{"type":"string"}}},"AgentCheckoutStatus":{"type":"object","required":["code","job","checkout","fulfillment","orderStatus"],"properties":{"code":{"type":"string","const":"ok"},"job":{"oneOf":[{"$ref":"#/components/schemas/AgentJobState"},{"type":"null"}]},"checkout":{"oneOf":[{"$ref":"#/components/schemas/AgentCheckoutState"},{"type":"null"}]},"fulfillment":{"oneOf":[{"$ref":"#/components/schemas/FulfilmentStatus"},{"type":"null"}]},"orderStatus":{"oneOf":[{"$ref":"#/components/schemas/ProductionStatus"},{"type":"null"}]}}},"CheckoutStatus":{"oneOf":[{"$ref":"#/components/schemas/SimpleCheckoutStatus"},{"$ref":"#/components/schemas/AgentCheckoutStatus"}]},"OrderIdRequest":{"type":"object","required":["orderId"],"properties":{"orderId":{"type":"string","format":"uuid"}},"additionalProperties":false},"FulfilmentRetry":{"type":"object","required":["code","orderId","accepted","reason"],"properties":{"code":{"type":"string","const":"ok"},"orderId":{"type":"string","format":"uuid"},"accepted":{"type":"boolean","const":false},"reason":{"type":"string","enum":["already_submitted","submitted_existing_asset"]}}},"OrderListItem":{"type":"object","required":["orderId","orderReference","createdAt","status","itemQuantity","totalAmountCents","totalAmountFormatted","currency","stripeSessionId"],"properties":{"orderId":{"type":"string","format":"uuid"},"orderReference":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"status":{"type":"string"},"itemQuantity":{"type":"integer","minimum":0},"totalAmountCents":{"type":"integer","minimum":0},"totalAmountFormatted":{"type":"string"},"currency":{"type":"string","const":"GBP"},"stripeSessionId":{"type":["string","null"]}}},"OrderList":{"type":"object","required":["orders","cursor"],"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderListItem"}},"cursor":{"type":["string","null"],"format":"date-time"}}}}}}