{"openapi":"3.1.0","info":{"title":"AgentMade Print on Demand API","version":"0.1.0","summary":"Print on demand API for AI agents: custom apparel and merch, delivered. No POD supplier account required.","description":"Discover printable products, validate artwork, get a delivered (landed) quote, pay through a hosted checkout link or an agent payment rail, and track manufacturing and shipping. Amounts are integer minor units. The same operations are available as MCP tools at /mcp. UCP (Universal Commerce Protocol 2026-08-25) checkout and catalog: profile at /.well-known/ucp, REST binding under /ucp/v1."},"servers":[{"url":"https://pod.agentmade.dev"}],"paths":{"/v1/products":{"get":{"operationId":"search_products","summary":"Search printable products","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"color","in":"query","required":false,"schema":{"type":"string"}},{"name":"size","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Matching products","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/products/{product_id}":{"get":{"operationId":"get_product","summary":"Product details, placements and variants","parameters":[{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/artworks":{"post":{"operationId":"upload_artwork","summary":"Upload artwork (JSON svg/base64/url, or a raw image body)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtworkSource"}},"image/svg+xml":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"Artwork analysis","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/artworks/validate":{"post":{"operationId":"validate_artwork","summary":"Upload or reference artwork and validate it for a product placement","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateArtwork"}}}},"responses":{"201":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/mockups":{"post":{"operationId":"create_mockup","summary":"Render a preview mockup","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMockup"}}}},"responses":{"201":{"description":"Mockup URL","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/designs":{"post":{"operationId":"create_design","summary":"Create a design id (variant + validated artwork) for UCP checkout line items","description":"UCP has no customization field, so the design travels in the item id. Use the design_id as line_items[].item.id at POST /ucp/v1/checkout-sessions. The UCP business profile is at /.well-known/ucp.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDesign"}}}},"responses":{"201":{"description":"Design id","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/quotes":{"post":{"operationId":"quote","summary":"Delivered price quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"201":{"description":"Quote","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/quotes/{quote_id}":{"get":{"operationId":"get_quote","summary":"Read a quote","parameters":[{"name":"quote_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/orders":{"post":{"operationId":"purchase","summary":"Create the order from a quote and start payment (idempotent per quote_id)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseRequest"}}}},"responses":{"201":{"description":"Order with payment URL","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/orders/{order_id}":{"get":{"operationId":"get_order","summary":"Order status","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/orders/{order_id}/tracking":{"get":{"operationId":"track_order","summary":"Shipment tracking","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tracking","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}},"/v1/orders/{order_id}/cancel":{"post":{"operationId":"cancel_order","summary":"Cancel an order (refunds if paid and not yet in production)","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelOrder"}}}},"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"$ref":"#/components/responses/Error"},"5XX":{"$ref":"#/components/responses/Error"}}}}},"components":{"schemas":{"ArtworkSource":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"svg":{"description":"Inline SVG markup. Best for logos and text.","type":"string","minLength":1},"base64":{"description":"Base64-encoded PNG, JPEG or SVG file contents (no data: prefix needed).","type":"string","minLength":1},"url":{"description":"Public HTTPS URL of a PNG, JPEG or SVG file.","type":"string","format":"uri"},"filename":{"type":"string","maxLength":200}}},"ValidateArtwork":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"artwork":{"description":"New artwork to upload: exactly one of svg, base64 or url.","type":"object","properties":{"svg":{"description":"Inline SVG markup. Best for logos and text.","type":"string","minLength":1},"base64":{"description":"Base64-encoded PNG, JPEG or SVG file contents (no data: prefix needed).","type":"string","minLength":1},"url":{"description":"Public HTTPS URL of a PNG, JPEG or SVG file.","type":"string","format":"uri"},"filename":{"type":"string","maxLength":200}}},"artwork_id":{"description":"Re-validate artwork uploaded earlier.","type":"string"},"product_id":{"type":"string","description":"Product to print on."},"color":{"description":"Product colour, for the contrast check.","type":"string"},"size":{"description":"Garment size, e.g. \"XL\". Print areas can differ by size; without it the smallest size is checked.","type":"string"},"placement":{"default":"front","description":"Print location on the product, e.g. \"front\" or \"back\". See get_product for the list.","type":"string"},"preset":{"description":"Named position inside the placement, e.g. \"center_chest\", \"left_chest\", \"full_front\". Defaults to the placement default.","type":"string"},"width_mm":{"description":"Exact printed width of the visible artwork in millimetres. Height follows the aspect ratio.","type":"number","exclusiveMinimum":0,"maximum":1000},"height_mm":{"description":"Maximum printed height in millimetres.","type":"number","exclusiveMinimum":0,"maximum":1000},"top_mm":{"description":"Distance from the top of the print area to the top of the artwork.","type":"number","minimum":0,"maximum":1000},"left_mm":{"description":"Distance from the left edge of the print area. Default: horizontally centred.","type":"number","minimum":0,"maximum":1000}},"required":["product_id"]},"CreateMockup":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"artwork_id":{"type":"string"},"product_id":{"type":"string"},"color":{"type":"string","description":"Product colour, e.g. \"black\"."},"size":{"type":"string"},"style":{"default":"flat","description":"flat: quick placement drawing. packshot: product photo with the exact print at real size (where a product photo exists).","type":"string","enum":["flat","packshot"]},"placement":{"default":"front","description":"Print location on the product, e.g. \"front\" or \"back\". See get_product for the list.","type":"string"},"preset":{"description":"Named position inside the placement, e.g. \"center_chest\", \"left_chest\", \"full_front\". Defaults to the placement default.","type":"string"},"width_mm":{"description":"Exact printed width of the visible artwork in millimetres. Height follows the aspect ratio.","type":"number","exclusiveMinimum":0,"maximum":1000},"height_mm":{"description":"Maximum printed height in millimetres.","type":"number","exclusiveMinimum":0,"maximum":1000},"top_mm":{"description":"Distance from the top of the print area to the top of the artwork.","type":"number","minimum":0,"maximum":1000},"left_mm":{"description":"Distance from the left edge of the print area. Default: horizontally centred.","type":"number","minimum":0,"maximum":1000}},"required":["artwork_id","product_id","color"]},"CreateDesign":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"product_id":{"type":"string","description":"Product id from search_products, e.g. \"tee-heavyweight\"."},"color":{"type":"string","description":"Colour id or name, e.g. \"black\"."},"size":{"type":"string","description":"Size, e.g. \"XL\". For one-size products use \"ONE SIZE\" (\"ONE\" also works)."},"artwork":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"object","properties":{"placement":{"default":"front","description":"Print location on the product, e.g. \"front\" or \"back\". See get_product for the list.","type":"string"},"preset":{"description":"Named position inside the placement, e.g. \"center_chest\", \"left_chest\", \"full_front\". Defaults to the placement default.","type":"string"},"width_mm":{"description":"Exact printed width of the visible artwork in millimetres. Height follows the aspect ratio.","type":"number","exclusiveMinimum":0,"maximum":1000},"height_mm":{"description":"Maximum printed height in millimetres.","type":"number","exclusiveMinimum":0,"maximum":1000},"top_mm":{"description":"Distance from the top of the print area to the top of the artwork.","type":"number","minimum":0,"maximum":1000},"left_mm":{"description":"Distance from the left edge of the print area. Default: horizontally centred.","type":"number","minimum":0,"maximum":1000},"artwork_id":{"type":"string","description":"artwork_id returned by validate_artwork."}},"required":["artwork_id"]},"description":"One entry per print placement. Each placement may appear once per item."}},"required":["product_id","color","size","artwork"]},"QuoteRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","description":"Product id from search_products, e.g. \"tee-heavyweight\"."},"color":{"type":"string","description":"Colour id or name, e.g. \"black\"."},"size":{"type":"string","description":"Size, e.g. \"XL\". For one-size products use \"ONE SIZE\" (\"ONE\" also works)."},"quantity":{"default":1,"type":"integer","minimum":1,"maximum":50},"artwork":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"object","properties":{"placement":{"default":"front","description":"Print location on the product, e.g. \"front\" or \"back\". See get_product for the list.","type":"string"},"preset":{"description":"Named position inside the placement, e.g. \"center_chest\", \"left_chest\", \"full_front\". Defaults to the placement default.","type":"string"},"width_mm":{"description":"Exact printed width of the visible artwork in millimetres. Height follows the aspect ratio.","type":"number","exclusiveMinimum":0,"maximum":1000},"height_mm":{"description":"Maximum printed height in millimetres.","type":"number","exclusiveMinimum":0,"maximum":1000},"top_mm":{"description":"Distance from the top of the print area to the top of the artwork.","type":"number","minimum":0,"maximum":1000},"left_mm":{"description":"Distance from the left edge of the print area. Default: horizontally centred.","type":"number","minimum":0,"maximum":1000},"artwork_id":{"type":"string","description":"artwork_id returned by validate_artwork."}},"required":["artwork_id"]},"description":"One entry per print placement. Each placement may appear once per item."}},"required":["product_id","color","size","artwork"]}},"ship_to":{"type":"object","properties":{"country_code":{"type":"string","minLength":2,"maxLength":2},"state_code":{"type":"string","maxLength":10},"postal_code":{"type":"string","maxLength":20},"city":{"type":"string","maxLength":60}},"required":["country_code"],"description":"Destination. country_code is required; postal_code and state_code improve shipping accuracy."},"preference":{"default":"fewest_packages","description":"How AgentMade picks the manufacturing route: fewest_packages (default: fewest parcels, then best price among the fastest routes), cheapest, or fastest.","type":"string","enum":["fewest_packages","cheapest","fastest"]}},"required":["items","ship_to"]},"PurchaseRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"quote_id":{"type":"string","description":"quote_id returned by quote."},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Full name of the recipient."},"company":{"type":"string","maxLength":100},"address1":{"type":"string","minLength":1,"maxLength":100,"description":"Street and house number."},"address2":{"description":"Apartment, floor, etc.","type":"string","maxLength":100},"city":{"type":"string","minLength":1,"maxLength":60},"state_code":{"description":"State or province code. Required for US, CA and AU.","type":"string","maxLength":10},"postal_code":{"type":"string","minLength":1,"maxLength":20},"country_code":{"description":"ISO 3166-1 alpha-2 country code, e.g. CZ, DE, US.","type":"string","minLength":2,"maxLength":2},"email":{"description":"Recipient email. Carriers use it for delivery notifications.","type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","maxLength":30}},"required":["name","address1","city","postal_code","country_code"],"description":"Full shipping address. Country, state and postal code must match the quote destination."},"contact_email":{"description":"Email for order and payment receipts. Optional.","type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"payment_capabilities":{"default":["hosted_checkout"],"description":"Payment methods the calling agent can use. \"hosted_checkout\" = a URL a human opens to pay by card, Apple Pay or Google Pay. Always supported.","type":"array","items":{"type":"string","enum":["hosted_checkout","x402"]}},"rights_attestation":{"type":"boolean","const":true,"description":"Must be true: confirms the customer owns or is licensed to print all submitted artwork, and that it is not prohibited content."}},"required":["quote_id","recipient","rights_attestation"]},"CancelOrder":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reason":{"type":"string","maxLength":500}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{}},"required":["code","message"]}}}},"responses":{"Error":{"description":"Error with a machine-readable code and a hint for the next step","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}