{ "openapi": "3.0.3", "info": { "title": "Pictorem ArtFlow API", "description": "Programmatic access to Pictorem's print fulfillment platform: validate product configurations, retrieve live pricing and lead times, submit production orders, track orders, manage webhooks and browse artwork catalogs. All endpoints use HTTPS POST with multipart/form-data and return application/json.", "version": "0.1", "contact": { "url": "https://www.pictorem.com/artflow/0.1/docs" } }, "servers": [ { "url": "https://www.pictorem.com/artflow/0.1" } ], "components": { "securitySchemes": { "ArtFlowKey": { "type": "apiKey", "in": "header", "name": "ArtFlowKey" } } }, "security": [ { "ArtFlowKey": [] } ], "paths": { "/validatepreorder/": { "post": { "summary": "Validate a pre-order code", "operationId": "validatePreOrder", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "preordercode" ], "properties": { "preordercode": { "type": "string", "description": "Pipe-delimited product configuration: numCopies|material|type|orientation|width|height|additional\u2026 Orientation accepts vertical, horizontal, square or auto (\"auto\" skips the orientation check \u2014 the orientation is taken directly from width x height). Width and height are in inches; fractional dimensions (e.g. 37.25) are supported per product according to its decimaldim flag (\"1\" = any decimal, \"Q\" = quarter inches, \"\" = whole inches) returned by getcatalog and buildproductlist.", "example": "1|canvas|stretched|horizontal|16|12" }, "bordercolorhex": { "type": "string", "example": "ffffff" } } } } } }, "responses": [ { "description": "Validation result with sanitized code breakdown" }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/getprice/": { "post": { "summary": "Get a full pricing worksheet (USD, taxes included)", "operationId": "getPrice", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "preordercode" ], "properties": { "preordercode": { "type": "string", "description": "Pipe-delimited product configuration: numCopies|material|type|orientation|width|height|additional\u2026 Orientation accepts vertical, horizontal, square or auto (\"auto\" skips the orientation check \u2014 the orientation is taken directly from width x height). Width and height are in inches; fractional dimensions (e.g. 37.25) are supported per product according to its decimaldim flag (\"1\" = any decimal, \"Q\" = quarter inches, \"\" = whole inches) returned by getcatalog and buildproductlist.", "example": "1|canvas|stretched|horizontal|16|12" }, "collectionid": { "type": "string" }, "deliveryprovince": { "type": "string", "example": "QC" }, "deliverycountry": { "type": "string", "example": "Canada" } } } } } }, "responses": [ { "description": "Pricing worksheet: list price, discount, commission, taxes, total (all amounts rounded to 2 decimals). The list/discount/commission maps hold one key per component of the preordercode \u2014 use the listTotal, discountTotal, artistCommissionTotal and artistCommissionDiscountTotal aggregates rather than reading the main key alone. list is the price before discount; discount is an amount to subtract." }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/getleadtime/": { "post": { "summary": "Get production lead time in business days", "operationId": "getLeadTime", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "preordercode" ], "properties": { "preordercode": { "type": "string", "description": "Pipe-delimited product configuration: numCopies|material|type|orientation|width|height|additional\u2026 Orientation accepts vertical, horizontal, square or auto (\"auto\" skips the orientation check \u2014 the orientation is taken directly from width x height). Width and height are in inches; fractional dimensions (e.g. 37.25) are supported per product according to its decimaldim flag (\"1\" = any decimal, \"Q\" = quarter inches, \"\" = whole inches) returned by getcatalog and buildproductlist.", "example": "1|canvas|stretched|horizontal|16|12" } } } } } }, "responses": [ { "description": "Production lead time in business days" }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/getshippingquote/": { "post": { "summary": "Quote shipping for an order before taking payment", "description": "Returns every UPS service available for the whole order to one address, priced at our negotiated rate, plus a quoteid to pass to /sendorder/ so the freight billed is the freight quoted. Send all lines in one call: they are packed the way they will actually ship, so quoting per item and summing overcharges a multi-item order. Express services need no special field \u2014 the returned list is the express options. Hawaii, Alaska and Puerto Rico are air-only, so ground is absent from services and groundavailable is false. A quote lasts 60 minutes and is good for one order. HTTP 200 with an empty services array means UPS would not rate the address; treat it as \"shipping unavailable\", not an error.", "operationId": "getShippingQuote", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "deliveryInfo", "orderList" ], "properties": { "deliveryInfo": { "type": "object", "required": [ "city", "province", "country", "cp" ], "properties": { "city": { "type": "string", "example": "Honolulu" }, "province": { "type": "string", "description": "State / province code", "example": "HI" }, "country": { "type": "string", "description": "ISO code or full country name", "example": "USA" }, "cp": { "type": "string", "description": "Postal / zip code", "example": "96815" }, "address1": { "type": "string", "description": "Optional here \u2014 rating needs only city, province, postal and country. Still required on /sendorder/." } } }, "orderList": { "type": "array", "description": "Every line of the order. No image source is needed \u2014 this prices the carton, not the artwork.", "items": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Pipe-delimited product configuration: numCopies|material|type|orientation|width|height|additional\u2026 Orientation accepts vertical, horizontal, square or auto (\"auto\" skips the orientation check \u2014 the orientation is taken directly from width x height). Width and height are in inches; fractional dimensions (e.g. 37.25) are supported per product according to its decimaldim flag (\"1\" = any decimal, \"Q\" = quarter inches, \"\" = whole inches) returned by getcatalog and buildproductlist.", "example": "1|canvas|stretched|horizontal|16|12" } } } } } } } } }, "responses": [ { "description": "Available services, cheapest first. An empty services array means UPS would not rate this destination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "quoteid": { "type": "string", "nullable": true, "description": "Pass to /sendorder/ as quoteid. null when nothing could be rated.", "example": "q_8f14e45fceea167a5a36dedd4bea2543" }, "expires": { "type": "string", "description": "When the quote stops being spendable (60 minutes)", "example": "2026-09-14 15:42:00" }, "cached": { "type": "boolean", "description": "true when the same lines to the same address were quoted within the TTL and this is that quote" }, "services": { "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string", "description": "UPS service code \u2014 send this back as shippingservice", "example": "02" }, "name": { "type": "string", "example": "UPS 2nd Day Air" }, "price": { "type": "number", "example": 148.72 }, "currency": { "type": "string", "example": "USD" }, "transitdays": { "type": "integer", "nullable": true, "description": "UPS guaranteed business days in transit, from dispatch \u2014 add the /getleadtime/ production time for a delivery date. null when UPS does not guarantee the service." }, "ground": { "type": "boolean", "description": "true for the ground service, when one is offered" } } } }, "groundavailable": { "type": "boolean", "description": "false for air-only destinations such as HI, AK and PR" }, "packages": { "type": "integer", "description": "How many cartons the order consolidates into" } } } } } }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/sendorder/": { "post": { "summary": "Submit a production order", "description": "Supports three image sources per line item: direct file upload (jpg/png/tiff), a public image URL, or a Pictorem collection ID. POs are idempotent: reusing a PO returns HTTP 409 with the existing order ID. Set testmode=1 (or use a test-mode API key) to validate without creating a real order. Send quoteid + shippingservice from /getshippingquote/ to have shipping billed at the quoted price; omit both and no shipping is charged. An optional document (waybill, shipping label, PDF\u2026) can be attached via document[file] or documenturl. An optional 7x5\" printed thank-you card can be added via thanksnotemsg (text, typeset by Pictorem) or thanksnoteurl (print-ready image) \u2014 one card per order, USD 2.99 flat, free for Premium accounts.", "operationId": "sendOrder", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "deliveryInfo", "orderList" ], "properties": { "ordercomment": { "type": "string" }, "po": { "type": "string", "description": "Your own reference \u2014 must be unique per order" }, "testmode": { "type": "string", "enum": [ "1" ], "description": "Sandbox: validate everything, create nothing" }, "quoteid": { "type": "string", "description": "Shipping quote from /getshippingquote/. We bill the price that quote carried for shippingservice. Valid 60 minutes, one order per quote, and only for the postal code it was priced for. Omit for no shipping charge.", "example": "q_8f14e45fceea167a5a36dedd4bea2543" }, "shippingservice": { "type": "string", "description": "The service code the customer paid for, from that quote. Required whenever quoteid is sent.", "example": "02" }, "document": { "type": "string", "format": "binary", "description": "Optional document to attach to the order (waybill, shipping label\u2026). Accepted: pdf / jpg / jpeg / png. Mutually exclusive with documenturl." }, "documenturl": { "type": "string", "description": "Public http(s) URL to a document to attach (pdf / jpg / jpeg / png). Mutually exclusive with document[file]." }, "thanksnotemsg": { "type": "string", "description": "Optional 7x5\" printed thank-you card, one per order (USD 2.99 flat, free for Premium accounts). Pictorem typesets this message on the card. Mutually exclusive with thanksnoteurl." }, "thanksnoteurl": { "type": "string", "description": "Public http(s) URL to your own print-ready thank-you card (jpg / jpeg / png, 7:5 landscape, 2100x1500 px recommended). Mutually exclusive with thanksnotemsg." }, "deliveryInfo": { "type": "object", "required": [ "firstname", "lastname", "address1", "city", "province", "country", "cp" ], "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "company": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" }, "cp": { "type": "string" }, "phone": { "type": "string" } } }, "orderList": { "type": "array", "items": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Pipe-delimited product configuration: numCopies|material|type|orientation|width|height|additional\u2026 Orientation accepts vertical, horizontal, square or auto (\"auto\" skips the orientation check \u2014 the orientation is taken directly from width x height). Width and height are in inches; fractional dimensions (e.g. 37.25) are supported per product according to its decimaldim flag (\"1\" = any decimal, \"Q\" = quarter inches, \"\" = whole inches) returned by getcatalog and buildproductlist.", "example": "1|canvas|stretched|horizontal|16|12" }, "file": { "type": "string", "format": "binary", "description": "jpg / png / tiff" }, "fileurl": { "type": "string", "description": "Public https image URL" }, "filetype": { "type": "string", "enum": [ "jpg", "jpeg", "png", "tif", "tiff" ] }, "collectionID": { "type": "string" }, "bordercolorhex": { "type": "string" }, "comment": { "type": "string", "maxLength": 255, "description": "Your own reference for this item, such as the end customer it is for. Kept on the order line." } } } } } } } } }, "responses": [ { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Order created \u2014 returns orderid" }, { "description": "Duplicate PO \u2014 existing orderid returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed \u2014 failedstep names the rejecting stage, msg.detail carries the per-item diagnosis", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } }, "detail": { "type": "array", "description": "Per-item diagnosis when a preordercode is rejected", "items": { "type": "object", "properties": { "item": { "type": "integer", "description": "Failing orderList index" }, "preordercode": { "type": "string", "description": "Code as submitted" }, "preordersanitize": { "type": "string", "description": "Code the validator expected (same value validatepreorder returns)" }, "processerror": { "type": "array", "items": { "type": "string" }, "description": "Sanitizer error codes (Error::\u2026) explaining what was changed or dropped" } } } } } }, "orderid": { "type": "integer", "nullable": true }, "failedstep": { "type": "string", "description": "First pipeline step that failed (e.g. sanitizePreOrderList)" } } } } } }, { "description": "Internal pipeline failure (pricing, order creation, file transfer) \u2014 failedstep names the stage; safe to retry with the same po", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } }, "detail": { "type": "array", "description": "Per-item diagnosis when a preordercode is rejected", "items": { "type": "object", "properties": { "item": { "type": "integer", "description": "Failing orderList index" }, "preordercode": { "type": "string", "description": "Code as submitted" }, "preordersanitize": { "type": "string", "description": "Code the validator expected (same value validatepreorder returns)" }, "processerror": { "type": "array", "items": { "type": "string" }, "description": "Sanitizer error codes (Error::\u2026) explaining what was changed or dropped" } } } } } }, "orderid": { "type": "integer", "nullable": true }, "failedstep": { "type": "string", "description": "First pipeline step that failed (e.g. sanitizePreOrderList)" } } } } } } ] } }, "/getorderstatus/": { "post": { "summary": "Get full order status by order ID or PO", "description": "Returns both the commercial order_status and the derived production_status. Production stages such as 27 Ready for Print only ever exist on the line items, so read production_status (or lines[].status) rather than order_status to follow an order through the workshop.", "operationId": "getOrderStatus", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "orderid": { "type": "string", "description": "Pictorem order ID" }, "po": { "type": "string", "description": "Your own PO number" } } } } } }, "responses": [ { "description": "Order with production stage, delivery info, tracking and line items", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "order": { "type": "object", "properties": { "orderid": { "type": "integer" }, "po": { "type": "string", "nullable": true }, "date": { "type": "string" }, "order_status": { "type": "string", "description": "Commercial status of the order, from the Pictorem status table \u2014 common values: 9 QUOTE - Waiting payment, 0 Processing, 11 Action required, 2 Shipped, 3 Canceled. It does not move while the order is in the workshop, so it never reports a production stage \u2014 read production_status for that." }, "order_status_label": { "type": "string" }, "production_status": { "type": "string", "nullable": true, "description": "Production stage of the items, derived from the line statuses \u2014 e.g. 27 Ready for Print, 75 Printing, 67 Framing, 28 Boxing. Reflects the least advanced item, so the order only reaches a stage once every item has. null for an order with no items." }, "production_status_label": { "type": "string", "nullable": true }, "production_progress": { "type": "integer", "nullable": true, "description": "Completion percentage (0-100) of production_status. Comparable across codes \u2014 higher always means further along." }, "billing_status": { "type": "string" }, "billing_status_label": { "type": "string" }, "tracking_number": { "type": "string", "nullable": true }, "tracking_carrier": { "type": "string", "nullable": true }, "total": { "type": "number" }, "currency": { "type": "string" }, "delivery": { "type": "object", "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "company": { "type": "string", "nullable": true }, "address1": { "type": "string" }, "address2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" }, "postal": { "type": "string" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "line_id": { "type": "integer" }, "status": { "type": "string", "description": "Production stage of this item" }, "status_label": { "type": "string" }, "is_option": { "type": "boolean", "description": "true for attachments (frames, mounts, thank-you cards) that follow their parent item and are excluded from production_status" }, "product": { "type": "string" }, "type": { "type": "string" }, "orientation": { "type": "string" }, "width": { "type": "string" }, "height": { "type": "string" }, "qty": { "type": "integer" }, "total": { "type": "number" }, "tracking": { "type": "string", "nullable": true } } } } } } } } } } }, { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/getorderlist/": { "post": { "summary": "List your orders (paginated, filterable)", "operationId": "getOrderList", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "page": { "type": "string", "default": "1" }, "limit": { "type": "string", "default": "25", "description": "Max 100" }, "status": { "type": "string", "description": "Filter by order status code \u2014 e.g. 2 Shipped, 3 Canceled, 0 Processing (see docs for the full list). Filters on order_status only; production stages are not filterable, so scan production_status in the results instead." }, "datefrom": { "type": "string", "example": "2026-01-01" }, "dateto": { "type": "string", "example": "2026-12-31" } } } } } }, "responses": [ { "description": "Paginated list of orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "pages": { "type": "integer" }, "orders": { "type": "array", "items": { "type": "object", "properties": { "orderid": { "type": "integer" }, "po": { "type": "string", "nullable": true }, "date": { "type": "string" }, "order_status": { "type": "string", "description": "Commercial status of the order, from the Pictorem status table \u2014 common values: 9 QUOTE - Waiting payment, 0 Processing, 11 Action required, 2 Shipped, 3 Canceled. It does not move while the order is in the workshop, so it never reports a production stage \u2014 read production_status for that." }, "order_status_label": { "type": "string" }, "production_status": { "type": "string", "nullable": true, "description": "Production stage of the items, derived from the line statuses \u2014 e.g. 27 Ready for Print, 75 Printing, 67 Framing, 28 Boxing. Reflects the least advanced item, so the order only reaches a stage once every item has. null for an order with no items." }, "production_status_label": { "type": "string", "nullable": true }, "production_progress": { "type": "integer", "nullable": true, "description": "Completion percentage (0-100) of production_status. Comparable across codes \u2014 higher always means further along." }, "billing_status": { "type": "string" }, "billing_status_label": { "type": "string" }, "tracking_number": { "type": "string", "nullable": true }, "tracking_carrier": { "type": "string", "nullable": true }, "total": { "type": "number" }, "currency": { "type": "string" } } } } } } } } } } }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/cancelorder/": { "post": { "summary": "Cancel a pre-production order", "description": "Only orders in QUOTE - Waiting payment (9), Processing (0) or Action required (11) can be cancelled via the API.", "operationId": "cancelOrder", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "orderid": { "type": "string" }, "po": { "type": "string" } } } } } }, "responses": [ { "description": "Order cancelled" }, { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Order already in production or already cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/buildproductlist/": { "post": { "summary": "Expand a partial pre-order code into valid configurations", "operationId": "buildProductList", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "preordercode" ], "properties": { "preordercode": { "type": "string", "description": "Pipe-delimited product configuration: numCopies|material|type|orientation|width|height|additional\u2026 Orientation accepts vertical, horizontal, square or auto (\"auto\" skips the orientation check \u2014 the orientation is taken directly from width x height). Width and height are in inches; fractional dimensions (e.g. 37.25) are supported per product according to its decimaldim flag (\"1\" = any decimal, \"Q\" = quarter inches, \"\" = whole inches) returned by getcatalog and buildproductlist.", "example": "1|canvas|stretched|horizontal|16|12" } } } } } }, "responses": [ { "description": "Valid material / type / orientation / size / additional choices for the given base code" }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/getcatalog/": { "post": { "summary": "Get the full product catalog tree", "description": "Machine-readable tree of all materials, types, orientations, sizes, additionals and frames \u2014 the same data the validator uses. Build product pickers programmatically instead of hardcoding codes.", "operationId": "getCatalog", "responses": [ { "description": "Catalog tree: products, orientations, sizes, additionals, frames" }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/getartworklist/": { "post": { "summary": "List your own artworks with verified image URLs", "description": "Paginated listing of the artworks belonging to the account behind the ArtFlowKey. Every URL returned is verified to resolve before it is sent: an image that has not been generated is omitted rather than returned as a dead link, so any URL in the response can be handed straight to a downstream importer. Each artwork always carries an image object (thumb / preview / full / source); generated print renders are opt-in through the previews parameter. Retired renders (book2, book3, split panels, deco frame, imglink, wallgenerate) are no longer returned.", "operationId": "getArtworkList", "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "userid": { "type": "string", "description": "Optional. Results are always scoped to the ArtFlowKey owner; if sent, this must equal your own UserID or the request is refused with HTTP 403." }, "page": { "type": "string", "default": "1" }, "limit": { "type": "string", "default": "48", "description": "Max 100. Both the default and the maximum drop to 24 when previews is used." }, "sort": { "type": "string", "enum": [ "featured", "newest", "oldest", "name", "views" ], "default": "featured" }, "previews": { "type": "string", "description": "Comma-separated print renders to resolve and include, e.g. \"wallpreview,book,acr1\". Omitted by default. Accepted values: wallpreview, wallrandomsmall, wall, wallsmall, book, acr1-acr4 (+ small variants), metalbrush1-2 (+ smalls), sublim1-3 (+ smalls), wood1, wood2, mural1-3 (+ smalls), puzzle1, puzzle2 (+ smalls), pf, gallerysmall. An unknown value returns HTTP 422 listing the accepted ones.", "example": "wallpreview,book,acr1" }, "pricing": { "type": "string", "enum": [ "1" ], "description": "Adds a commission object per artwork (strategy: percentage | sqft | dynamic | fixed, value, source: collection | account) describing what the artist earns when someone else orders it. Use /getprice/ for the price of a specific configuration." }, "includeprivate": { "type": "string", "enum": [ "1" ], "description": "Also list artwork in hidden or password-protected albums. Off by default so an export cannot republish private work. Staff takedowns are never listed." } } } } } }, "responses": [ { "description": "Paginated artworks with metadata and verified image URLs" }, { "description": "userid was supplied but does not match the ArtFlowKey owner", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/registerwebhook/": { "post": { "summary": "Register a webhook callback URL", "description": "Pictorem POSTs a signed JSON payload to your URL whenever an ArtFlow order changes order status or production stage. Payloads are signed with HMAC-SHA256 (your API key is the secret) in the X-ArtFlow-Signature header, and carry X-ArtFlow-Delivery (a per-change ID, stable across retries \u2014 use it as an idempotency key) plus X-ArtFlow-Attempt. Respond 2xx within 10 seconds; anything else is retried with a growing delay for about half a day.", "operationId": "registerWebhook", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Your https:// callback URL" }, "event": { "type": "string", "enum": [ "order.status_changed" ], "default": "order.status_changed" } } } } } }, "responses": [ { "description": "Webhook registered \u2014 returns webhookid" }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/listwebhooks/": { "post": { "summary": "List your registered webhooks", "operationId": "listWebhooks", "responses": [ { "description": "Array of webhook subscriptions" }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/deletewebhook/": { "post": { "summary": "Deactivate a webhook", "operationId": "deleteWebhook", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "webhookid" ], "properties": { "webhookid": { "type": "string" } } } } } }, "responses": [ { "description": "Webhook deactivated" }, { "description": "Webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Invalid or missing ArtFlowKey header", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "description": "Rate limit exceeded (120 requests / minute / key)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "msg": { "type": "object", "properties": { "error": { "type": "array", "items": { "type": "string" } } } } } } } } } ] } }, "/shc/": { "post": { "summary": "System Health Check", "description": "Lightweight ping to verify API availability and ArtFlowKey validity. Empty multipart/form-data body. Does not count toward the rate limit. artFlowKey is only checked when status is true (API not in maintenance). Unlike other endpoints, an invalid key returns HTTP 200 with artFlowKey: false instead of HTTP 401.", "operationId": "shc", "responses": { "200": { "description": "Health check result \u2014 status reflects maintenance mode; artFlowKey reflects key validity", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "true when the API is accepting traffic; false during maintenance mode" }, "artFlowKey": { "type": "boolean", "description": "Only evaluated when status is true \u2014 true when the ArtFlowKey header matches a registered key; false when missing, invalid, or when status is false" } }, "required": [ "status", "artFlowKey" ] }, "examples": { "apiUpValidKey": { "summary": "API up, valid key", "value": { "status": true, "artFlowKey": true } }, "apiUpInvalidKey": { "summary": "API up, invalid key", "value": { "status": true, "artFlowKey": false } } } } } }, "503": { "description": "API maintenance mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "true when the API is accepting traffic; false during maintenance mode" }, "artFlowKey": { "type": "boolean", "description": "Only evaluated when status is true \u2014 true when the ArtFlowKey header matches a registered key; false when missing, invalid, or when status is false" } }, "required": [ "status", "artFlowKey" ] }, "example": { "status": false, "artFlowKey": false } } } }, "405": { "description": "Method not allowed \u2014 only POST is accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "true when the API is accepting traffic; false during maintenance mode" }, "artFlowKey": { "type": "boolean", "description": "Only evaluated when status is true \u2014 true when the ArtFlowKey header matches a registered key; false when missing, invalid, or when status is false" } }, "required": [ "status", "artFlowKey" ] }, "example": { "status": false, "artFlowKey": false } } } } } } } } }