{ "openapi": "3.1.0", "info": { "title": "HeatApplied API", "version": "v1", "description": "Generated from the endpoint definitions (RESOURCES / DOCS / SCHEMAS constants)." }, "servers": [ { "url": "https://api.heatapplied.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/artwork/mutators": { "get": { "tags": [ "Artwork" ], "summary": "List variable mutators (staff)", "description": "Staff only. Staff keys. Enumerates the registered variable mutators a master's `mutator_rules` may use, with each one's `params` schema. Mutators run in rule order on every derivative data row: splitters write `_Line1` / `_Line2`, cutters rewrite ``, `TransformText` rewrites `` per `mode`, `CreateField` writes `` from a `{Var}` template, `DismissField` drops `` from the output. Required account permission: _AdminConsole_Artwork_Edit.", "operationId": "getArtworkMutators", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "List variable mutators (staff)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mutator" } }, "page": { "type": "integer" }, "pages": { "type": "integer" }, "total": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object" } } } } } } }, "403": { "description": "Key is not owned by a staff account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/artwork/{uuid}/unarchive": { "get": { "tags": [ "Artwork" ], "summary": "Unarchive artwork", "description": "Restores an archived artwork to the active list. Required account permission: _Account_Artwork_Archive or _AdminConsole_Artwork_Archive.", "operationId": "getArtworkUnarchive", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customer", "in": "query", "required": false, "description": "Staff keys only. Act for this customer account (user uuid or sign-in email; a sub-user resolves to its account root). The request then reads and writes that account exactly as the customer's own key would. 404 when no customer account matches; 403 from a customer key.", "schema": { "type": "string", "description": "Staff keys only. Act for this customer account (user uuid or sign-in email; a sub-user resolves to its account root). The request then reads and writes that account exactly as the customer's own key would. 404 when no customer account matches; 403 from a customer key.", "example": "customer@example.com" } } ], "responses": { "200": { "description": "Unarchive artwork", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artwork" } } } }, "404": { "description": "Artwork not found on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (HTTPS, CIDR or scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/artwork/{uuid}/archive": { "get": { "tags": [ "Artwork" ], "summary": "Archive artwork", "description": "Hides the artwork from listings and blocks new orders for it. Emits the `artwork.archived` webhook. Required account permission: _Account_Artwork_Archive or _AdminConsole_Artwork_Archive.", "operationId": "getArtworkArchive", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customer", "in": "query", "required": false, "description": "Staff keys only. Act for this customer account (user uuid or sign-in email; a sub-user resolves to its account root). The request then reads and writes that account exactly as the customer's own key would. 404 when no customer account matches; 403 from a customer key.", "schema": { "type": "string", "description": "Staff keys only. Act for this customer account (user uuid or sign-in email; a sub-user resolves to its account root). The request then reads and writes that account exactly as the customer's own key would. 404 when no customer account matches; 403 from a customer key.", "example": "customer@example.com" } } ], "responses": { "200": { "description": "Archive artwork", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artwork" } } } }, "404": { "description": "Artwork not found on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (HTTPS, CIDR or scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/artwork/{uuid}/download": { "get": { "tags": [ "Artwork" ], "summary": "Download current file", "description": "Streams the artwork's current file as an attachment: the file you uploaded until preflight completes, then the print-ready file produced by preflight (each preflight completion creates a new version). System-generated artwork (designer output, pre-spaced names) is locked until it has been ordered at least once. Required account permission: _Account_Artwork_Download or _AdminConsole_Artwork_Download.", "operationId": "getArtworkDownload", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customer", "in": "query", "required": false, "description": "Staff keys only. Act for this customer account (user uuid or sign-in email; a sub-user resolves to its account root). The request then reads and writes that account exactly as the customer's own key would. 404 when no customer account matches; 403 from a customer key.", "schema": { "type": "string", "description": "Staff keys only. Act for this customer account (user uuid or sign-in email; a sub-user resolves to its account root). The request then reads and writes that account exactly as the customer's own key would. 404 when no customer account matches; 403 from a customer key.", "example": "customer@example.com" } } ], "responses": { "200": { "description": "Binary file body with `Content-Disposition: attachment`.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Download locked until first order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artwork or file not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/artwork/{uuid}/document": { "get": { "tags": [ "Artwork" ], "summary": "Get master design document (staff)", "description": "Staff only. Staff keys. Returns the schema-v1 design document a lab master was compiled from — the input to re-send (edited) as `PATCH … {document}`. 409 for a non-master, or for an uploaded Illustrator-package master (no document — download its PDF/package with `GET …/download` and replace it with `POST …/package`). Required account permission: _AdminConsole_Artwork_Edit.", "operationId": "getArtworkDocument", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{artwork_uuid, design_uuid, document: {…}}`", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Key is not owned by a staff account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artwork not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not a master, or the master has no design document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/artwork/{uuid}/production": { "post": { "tags": [ "Artwork" ], "summary": "Attach production file (staff)", "description": "Staff only. Staff keys. Attaches a print-ready production PDF to the artwork — the file production actually images from, as Admin → Artwork → Print Files does. The artwork may belong to any customer account. The PDF is stored as a new `print_file` row for the given `print_method_id`, versioned above the artwork's existing files for that method (production always picks the highest version); a 72 dpi preview is rendered and the trimmed image / page dimensions are measured from it. The artwork's `status` is NOT changed — pair with `POST /v1/artwork` using `customer` + `status: 3`, or set the status separately. Send as `multipart/form-data`. Required account permission: _AdminConsole_Artwork_Edit.", "operationId": "postArtworkProduction", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attach production file (staff)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintFile" } } } }, "400": { "description": "Validation failed, file not a PDF, or the PDF could not be rendered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not owned by a staff account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artwork or print method not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The production PDF (≤ 50 MB). Only `.pdf` is accepted." }, "print_method_id": { "type": "integer", "description": "Print method the file is prepared for. 1 = Screen Printing Sheet-Fed (default).", "default": 1 }, "name": { "type": "string", "description": "Display name for the file (≤ 255). Defaults to the artwork name." } }, "required": [ "file" ] } } } } } }, "/v1/artwork/{uuid}/derivative": { "post": { "tags": [ "Artwork" ], "summary": "Ingest a finished derivative (staff)", "description": "Staff only. Staff keys. Adds an already-finished derivative to a master **without running the generator**. `:uuid` is the MASTER (its uuid, any version of the lineage, or its numeric artwork id); the body carries the completed art file and the variable values that file represents.\n\nUse it when a derivative cannot come from the template: it was drawn and sold before the master existed, or the generated output had to be hand-corrected to look right. The result is a true derivative — it lists under the master, inherits its `type`, `formula`, artboard size and colour count, gets the master's press rotations, print colours and tags cloned onto it, and carries one variable row per value you send — so nothing downstream can tell it from a generated one.\n\n`variables` is a JSON object of variable name to the value the file shows, e.g. `{\"City\":\"Dayton\",\"State\":\"OH\"}`. Send the values as they appear in the art. If you are sending a raw data row instead and want the master's mutator waterfall applied first, add `apply_mutators=1` and the mutated result is what gets stored. `name` defaults to the master name with the variable values appended (City first, State abbreviated), matching generated derivatives.\n\n`status` defaults to 3 (Preflight Approved), since the file is finished art; no preflight is run and no preflight webhook fires. Attach the print-ready production PDF afterwards with `POST /v1/artwork/:uuid/production` using the uuid THIS call returns. Send as `multipart/form-data`. Required account permission: _AdminConsole_Artwork_Edit.", "operationId": "postArtworkDerivative", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ingest a finished derivative (staff)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artwork" } } } }, "400": { "description": "Validation failed, `variables` missing or malformed, the target is not a master, or the PDF could not be rendered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not owned by a staff account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Master artwork not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The finished derivative art file (≤ 50 MB). Only `.pdf` is accepted." }, "variables": { "type": "string", "description": "JSON object of variable name to the value the file represents, e.g. `{\"City\":\"Dayton\",\"State\":\"OH\"}`. Stored as the derivative's resolved values." }, "apply_mutators": { "type": "boolean", "description": "When true, run the master's mutator rules over `variables` first and store the result. Use when sending a raw data row rather than resolved values.", "default": false }, "name": { "type": "string", "description": "Derivative name (≤ 255). Defaults to the master name with the variable values appended." }, "status": { "type": "integer", "description": "Status to create the derivative in. Defaults to 3 (Preflight Approved) because the supplied file is finished art.", "enum": [ 1, 2, 3, 4, 5, 6 ], "default": 3 } }, "required": [ "file", "variables" ] } } } } } }, "/v1/artwork/{uuid}/package": { "post": { "tags": [ "Artwork" ], "summary": "Replace master package (staff)", "description": "Staff only. Staff keys. Replaces a master template's finished Illustrator package — the master PDF you hand-finished outside the system — as a NEW version of the master, **without recompiling anything**. `:uuid` is any version of the master lineage (or its numeric id). The ZIP is File → Package output: the master PDF beside `Fonts/` and `Links/` (a wrapper folder is fine). The PDF is stored byte for byte, so a custom distress mask, a re-fit envelope mesh or corrected kerning ship exactly as you drew them.\n\nWhat happens: the PDF is preflighted and refused for the same reasons as creation (several pages, RGB, no Illustrator variables, an ink the colour catalogue cannot name — `errors[0].message` lists them). A PDF edited outside Illustrator (the master downloaded, its text replaced by a tool, re-uploaded) has lost its variables: send `variables` as a JSON object of the text as drawn → variable name (`{\"MISSION BEACH\": \"City\", \"CALIFORNIA\": \"State\"}`) and the API binds those text objects as Illustrator variables before vetting, exactly as on create (see POST /v1/artwork, \"Binding text as variables\"); the refusal for a PDF without variables quotes the text it contains so the map can be written from it. Then a new artwork version is opened on the lineage (new uuid, version N+1, the old version archived and kept for history); the new version takes the package's PDF, ZIP, preview, dimensions, colour type and colour count; print colours and press rotations, variables, fonts and linked files are authored fresh from the package; mutator rules are carried from the previous version pruned to the variables that still exist (send `mutator_rules` to replace them, `[]` to clear); derivatives are re-pointed and live carts / orders / work orders relinked, as a `PATCH {document}` recompile does. Works on a lab master too — its Design Lab entry follows the new version, but the package is now what production reads until someone recompiles it with `PATCH {document}`.\n\nThe response is the new version (its `uuid` differs from the one you sent; `master.document_url` / `master.design_uuid` tell you whether a design document still exists). 409 when the artwork is not a master, or when the uuid you sent is no longer the head of its lineage (someone replaced or recompiled it first — fetch again and resend). Required account permission: _AdminConsole_Artwork_Edit.", "operationId": "postArtworkPackage", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Replace master package (staff)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artwork" } } } }, "400": { "description": "Not a ZIP, no / several PDFs in it, unreadable PDF, several pages, RGB colourspace, no Illustrator variables and no `variables` map, a mapped text the PDF does not contain or a name it already binds, ink not in the colour catalogue, or bad `formula` / `mutator_rules` / `variables`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key is not owned by a staff account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artwork not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not a master, or the uuid is not the current head of its lineage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The Illustrator Package `.zip` (≤ 200 MB): exactly one master PDF outside `Fonts/` / `Links/`." }, "formula": { "type": "string", "description": "Ink formula for the new version. Defaults to the master's current formula.", "enum": [ "Formula-1", "Formula-2", "Formula-4", "Formula-5" ] }, "variables": { "type": "string", "description": "JSON object of text as drawn → variable name, e.g. `{\"MISSION BEACH\": \"City\", \"CALIFORNIA\": \"State\"}`. Binds those text objects as Illustrator variables in the PDF before it is vetted (default value = the text). Omit when the PDF already carries its variables. Names ≤ 64 characters, no braces / whitespace, each used once." }, "mutator_rules": { "type": "string", "description": "JSON array `[{\"mutator\": \"\", \"variable_in\": \"\", \"param\": {…}}]` validated against the variables detected in the new PDF (same rules as create). Omit to carry the current rules, minus any whose `variable_in` no longer exists; `[]` clears them." } }, "required": [ "file" ] } } } } } }, "/v1/artwork/{uuid}": { "patch": { "tags": [ "Artwork" ], "summary": "Update artwork", "description": "Renames the artwork and/or replaces its description. Both fields optional; omitted fields are unchanged.\n\n**Master templates (staff keys).** On an `is_master` artwork with a design document, staff keys may also send `document` (the edited schema-v1 document — recompiled exactly as creation does into a NEW artwork version: new uuid, derivatives re-pointed, live orders relinked; the response is the new version), `variables` (replaces the variable set — with `document` it names the new document's layers, without it the current document's; variables for dropped layers and the mutator rules bound to them are removed), `mutator_rules` (replaces the whole ordered waterfall), `scope` (+ `customer` for `customer` scope; moves the master between the house stock account and the customer) and `categories` (replaces the gallery category set). Validation is the same as on create. `name` renames the Design Lab idea too. A package master (uploaded Illustrator package, no document) takes `name` / `description` / `status` here but 409s on the document fields — replace its PDF with `POST /v1/artwork/:uuid/package` instead. Required account permission: _Account_Artwork_Edit or _AdminConsole_Artwork_Edit.", "operationId": "patchArtworkByUuid", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Update artwork", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artwork" } } } }, "400": { "description": "Validation / compile failed — see `errors[]`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Customer key sent a staff-only field (`status`, `document`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artwork not found on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Artwork name already taken; master field sent for a non-master or a master without a design document; the artwork is no longer the head of its lineage (reload).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New unique name (≤ 255).", "example": "Team Logo — 2026 season" }, "description": { "type": "string", "description": "New description (≤ 65535).", "example": "Front chest, 2-colour spot" }, "status": { "type": "integer", "description": "Staff keys only. Manual status change with the SAME downstream effects as Admin → Artwork → Change Status: 2 (Pending Preflight) places the hold and creates the preflight contract / service request; 3 (Preflight Approved) releases the hold, emails the owner \"preflight approved\" and pushes every Pending Artwork order carrying this artwork into production; 4 records the failure; 1 / 5 / 6 are set with their hold bookkeeping. Each change writes a status event attributed to the key user, mirrored onto open orders, and emits the preflight / approval webhooks. A staff key without `customer` may address artwork on any account.", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "document": { "type": "object", "description": "Staff keys only, masters only. Replacement schema-v1 design document (object, or JSON string). Recompiles into a new artwork version." }, "variables": { "type": "array", "items": { "type": "object", "properties": [ { "type": "string" }, { "type": "string" } ] }, "description": "Staff keys only, masters only. Replacement `[{layer_id, key}]` set (same rules as create)." }, "mutator_rules": { "type": "array", "items": { "type": "object", "properties": [ { "type": "string" }, { "type": "string" }, { "type": "object" } ] }, "description": "Staff keys only, masters only. Replacement ordered rule list (same rules as create). `[]` clears all rules." }, "scope": { "type": "string", "description": "Staff keys only, masters only. New gallery scope; `customer` takes the account from `customer` (or keeps the current owner when the master is already customer-owned).", "enum": [ "global", "customer" ] }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Staff keys only, masters only. Replacement gallery category names (created when new). `[]` clears." }, "customer": { "type": "string", "description": "Staff keys only. Act for this customer account (user uuid or sign-in email; a sub-user resolves to its account root). The request then reads and writes that account exactly as the customer's own key would. 404 when no customer account matches; 403 from a customer key.", "example": "customer@example.com" } } } } } } }, "delete": { "tags": [ "Artwork" ], "summary": "Delete master (staff)", "description": "Staff only. Staff keys. Permanently deletes a master template that has never been ordered or printed, along with its derivatives when THEY have never been ordered or printed. Every version row of the master and of each current derivative is checked: on an order line, in print production (print images), in an open preflight / art-service request, in retain inventory, or on an ordered sheet → 409 listing every blocker, and nothing is deleted. Otherwise all lineage rows are hard-deleted in one transaction (print rotations, variables, mutator rules, print-file rows, pivots), the master Design row leaves the idea gallery (customer designs forked from it survive, unlinked), and an audit event is written. Stored files are not removed. Ordinary (non-master) artwork cannot be deleted — archive it. Required account permission: _AdminConsole_Artwork_Edit.", "operationId": "deleteArtworkByUuid", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{deleted: 1, uuid, versions_deleted, derivatives_deleted, design_uuid}`", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Key is not owned by a staff account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artwork not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not a master, or the master / a derivative is ordered, printed, in review, in retain inventory or on an ordered sheet — `errors[0].message` lists the blockers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Artwork" ], "summary": "Retrieve artwork", "description": " Required account permission: _Account_Artwork_List or _AdminConsole_Artwork_List.", "operationId": "getArtworkByUuid", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customer", "in": "query", "required": false, "description": "Staff keys only. Act for this customer account (user uuid or sign-in email; a sub-user resolves to its account root). The request then reads and writes that account exactly as the customer's own key would. 404 when no customer account matches; 403 from a customer key.", "schema": { "type": "string", "description": "Staff keys only. Act for this customer account (user uuid or sign-in email; a sub-user resolves to its account root). The request then reads and writes that account exactly as the customer's own key would. 404 when no customer account matches; 403 from a customer key.", "example": "customer@example.com" } } ], "responses": { "200": { "description": "Retrieve artwork", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artwork" } } } }, "404": { "description": "Artwork not found on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (HTTPS, CIDR or scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/artwork": { "post": { "tags": [ "Artwork" ], "summary": "Upload artwork", "description": "Creates a new artwork from an uploaded print file, exactly as the website's Art Library → Add Artwork flow does. The artwork is returned with `status` 5 (Preflight Required) and is not preflighted until it is ordered — `POST /v1/orders` submits it and the order waits in status 10 (Pending Artwork) until preflight passes. Pass `preflight=1` to queue preflight immediately instead (the \"Queue for early preflight\" option on the website). Preflight completes asynchronously — subscribe to `artwork.preflight_passed` / `artwork.preflight_failed` or poll `GET /v1/artwork/:uuid`. For `Spot` artwork every PMS colour used in the file must be supplied via `spot_color[]` (name or Pantone code). Staff keys may additionally send `customer` to create the artwork on that customer's account (as Admin → Artwork → Create does) and `status` to create it in any status: 2 (Pending Preflight) submits it to preflight at once, creating the preflight contract and service request exactly as an order would; 1 / 3 / 4 / 6 are written directly with an audit event and without a preflight run — use 3 when importing artwork approved elsewhere, then attach its print-ready file with the staff production-file resource. Customer keys sending either field receive 403. `artwork.created` is emitted to the owning account's webhooks in every case. Send as `multipart/form-data`.\n\n**Master templates (staff keys).** Send `master=1` with `document` — a schema-v1 Design Lab document (the same JSON the design compiler's `--compile` takes: `{schema_version:1, design:{artboard:{width_in,height_in}, layers:[…], colors:[{ref,pms,c,m,y,k}], fonts:[{ref,font}], distress?}}`) — instead of `file` / `type` / `width` / `height`. The document is compiled through the design compiler exactly as Admin → Designs → Convert to Master does and becomes a fully usable master: an `is_master` artwork (Spot, Preflight Approved, print colours + press rotations from the compiled separations, hidden backer plates when inks touch, a Package archive), a master Design row in the Design Lab idea gallery under `scope` / `categories`, one variable per text layer named in `variables` (what derivatives substitute), and the `mutator_rules` waterfall. Every `fonts[].font` must name an installed face (`-