{"openapi":"3.1.0","info":{"title":"Skylit Studio — ACP (Agentic Commerce Protocol) API","version":"0.1.0","description":"Agent-initiated purchase API for personalised Skylit star map prints. Implements the Agentic Commerce Protocol — see https://agenticcommerce.dev. MVP scope is the Star Map product.","contact":{"name":"Skylit Studio","url":"https://skylitstudio.co.uk"},"license":{"name":"All rights reserved"}},"servers":[{"url":"https://agent.skylitstudio.co.uk/acp/v1"}],"paths":{"/products":{"get":{"summary":"List available products","operationId":"listProducts","responses":{"200":{"description":"Product catalogue","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"ACP disabled (kill switch)"}}}},"/checkout_sessions":{"post":{"summary":"Create a checkout session from agent intent","operationId":"createCheckoutSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gift":{"type":"object","additionalProperties":true,"description":"Optional gift addons paired to the print. Call GET /gift_addons for the runtime catalogue (wrap options, prices, ribbon colours, card designs, card fonts, gift note max length).","properties":{"wrap":{"type":"string","enum":["none","ribbon","wrap","bundle"]},"ribbon_color":{"type":"string"},"wrap_theme":{"type":"string"},"note":{"type":"string","maxLength":250},"card_design":{"type":"string","enum":["editorial","minimal"]},"card_font":{"type":"string","enum":["handwritten","classic"]}}}}}}}},"responses":{"200":{"description":"Session created with Stripe payment artifacts"},"400":{"description":"Validation error"},"422":{"description":"Invalid intent or unsupported shipping address"},"503":{"description":"ACP disabled"}}}},"/checkout_sessions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get session status","operationId":"getCheckoutSession","responses":{"200":{"description":"Session JSON"},"404":{"description":"Not found"}}},"patch":{"summary":"Iterate session state (theme/composition/shape/title/message)","operationId":"patchCheckoutSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gift":{"type":"object","additionalProperties":true,"description":"Optional gift addons paired to the print. Call GET /gift_addons for the runtime catalogue (wrap options, prices, ribbon colours, card designs, card fonts, gift note max length).","properties":{"wrap":{"type":"string","enum":["none","ribbon","wrap","bundle"]},"ribbon_color":{"type":"string"},"wrap_theme":{"type":"string"},"note":{"type":"string","maxLength":250},"card_design":{"type":"string","enum":["editorial","minimal"]},"card_font":{"type":"string","enum":["handwritten","classic"]}}}}}}}},"responses":{"200":{"description":"Patched session"},"400":{"description":"Invalid patch key"},"409":{"description":"Session locked (already paid)"}}},"delete":{"summary":"Cancel a draft session","operationId":"cancelCheckoutSession","responses":{"204":{"description":"Cancelled"},"409":{"description":"Cannot cancel (in fulfillment)"}}}},"/checkout_sessions/{id}/preview":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Render preview JPEG of the current applied state","operationId":"getCheckoutSessionPreview","responses":{"200":{"description":"JPEG","content":{"image/jpeg":{}}},"404":{"description":"Session not found"},"502":{"description":"Preview render failed (retry)"}}}},"/checkout_sessions/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Server-side payment-method confirmation (off-session)","operationId":"completeCheckoutSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"]}}}},"responses":{"200":{"description":"Payment status (succeeded | requires_action)"},"402":{"description":"Payment failed / requires action"},"409":{"description":"Session not in draft state"}}}},"/gift_addons":{"get":{"summary":"Get the runtime catalogue of gift wrap options, ribbon colours, card designs and fonts","operationId":"listGiftAddons","responses":{"200":{"description":"Gift addon catalogue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/health":{"get":{"summary":"Service health (D1 + R2 + Stripe reachability)","operationId":"getHealth","responses":{"200":{"description":"All checks passing"},"503":{"description":"One or more checks degraded"}}}},"/errors/{code}":{"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Markdown documentation for an error code","operationId":"getErrorDoc","responses":{"200":{"description":"Markdown doc","content":{"text/markdown":{}}},"404":{"description":"Unknown error code"}}}}},"components":{"securitySchemes":{}}}