{"openapi":"3.1.0","info":{"title":"Agentzon API","version":"1.0.0","summary":"Search 500 household essentials and start Agentzon checkouts with Stripe Embedded Form.","description":"Read-only catalog endpoints allow cross-origin GET and are limited to 120 requests per minute per client IP. Checkout and order endpoints are rate limited in shared storage. Only purchase with the buyer's authorization and present the policies at https://agentzon.co/terms, https://agentzon.co/returns and https://agentzon.co/privacy before purchase. Full agent guidance: https://agentzon.co/llms.txt","contact":{"email":"agentzon-support@merit.systems"},"termsOfService":"https://agentzon.co/terms"},"servers":[{"url":"https://agentzon.co"}],"security":[],"externalDocs":{"description":"Agent quick start","url":"https://agentzon.co/agents.md"},"paths":{"/api/catalog-requests":{"post":{"operationId":"requestCatalogItems","summary":"Suggest missing products (optional; not an order or reservation)","description":"Product details only, no personal information. Send 1–10 suggestions. Reuse the same key and body for retries. Limited to 10 submissions per minute per trusted client IP.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,100}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","additionalProperties":false,"properties":{"searchTerm":{"type":"string","maxLength":200},"intent":{"type":"string","maxLength":500},"desiredBrand":{"type":"string","maxLength":100}},"anyOf":[{"required":["searchTerm"],"properties":{"searchTerm":{"minLength":1}}},{"required":["intent"],"properties":{"intent":{"minLength":1}}}]}}},"required":["requests"],"additionalProperties":false}}}},"responses":{"200":{"description":"Suggestions received; no follow-up required","content":{"application/json":{"schema":{"type":"object","required":["status","count","message"],"properties":{"status":{"const":"received"},"count":{"type":"integer","minimum":1,"maximum":10},"message":{"type":"string"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Retry after the number of seconds given.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/products":{"get":{"operationId":"searchProducts","summary":"Search the catalog","description":"Keyword search. All query words must match the product name, brand or category.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","description":"Exact catalog category name.","schema":{"type":"string","enum":["All","Cleaning and laundry","Paper products","Bags and food wrap","Toiletries","Pet care","School and office","Consumer technology","Kitchen tools","Bedding and sleep","Baby essentials","Health and first aid","Pantry and snacks","Home maintenance"]}},{"name":"brand","in":"query","description":"Exact catalog brand name.","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["featured","low","high","az"],"default":"featured"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Matching products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductList"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Retry after the number of seconds given.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/products/{id}":{"get":{"operationId":"getProduct","summary":"Get product details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"HH-0001"}}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Retry after the number of seconds given.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/products/{id}/image":{"get":{"operationId":"getProductImage","summary":"Get the product photo","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"HH-0001"}}],"responses":{"200":{"description":"Product image bytes","content":{"image/webp":{"schema":{"type":"string","contentEncoding":"binary"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Retry after the number of seconds given.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/checkout":{"get":{"operationId":"getCheckoutAvailability","summary":"Check whether checkout is available","responses":{"200":{"description":"Checkout availability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutAvailability"}}}}}},"post":{"operationId":"createCheckout","summary":"Start checkout for an entire basket","description":"Prices are resolved on the server. Open the returned url for the buyer to review and pay; creating a session is not payment. Optional buyer details prefill the payment form and remain editable there. Reuse the Idempotency-Key only to retry the same cart and details. Production checkout accepts real payments.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{16,100}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"additionalProperties":false,"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"description":"Distinct product IDs.","items":{"type":"object","required":["id","quantity"],"additionalProperties":false,"properties":{"id":{"type":"string","example":"HH-0001"},"quantity":{"type":"integer","minimum":1,"maximum":99}}}},"email":{"type":"string","format":"email","maxLength":254,"description":"Prefills the buyer's email."},"phone":{"type":"string","maxLength":30,"example":"+12125550100","description":"Prefills the buyer's phone number."},"shipping":{"$ref":"#/components/schemas/CheckoutContact","description":"Prefills the shipping address. U.S. addresses only."},"billing":{"$ref":"#/components/schemas/CheckoutContact","description":"Prefills the card's billing address. Send only when it differs from shipping; name defaults to the shipping name."}}}}}},"responses":{"200":{"description":"Checkout session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The attempt expired, was already paid, or the key was reused with another cart or other buyer details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Retry after the number of seconds given.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Checkout is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/orders/{id}":{"get":{"operationId":"getOrder","summary":"Get verified order status","description":"A paid status confirms payment, not shipment. Keep the order token private.","security":[{"orderToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Retry after the number of seconds given.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"orderToken":{"type":"http","scheme":"bearer","description":"The orderToken returned by createCheckout."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Mode":{"type":"string","enum":["test","live"]},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brand":{"type":"string"},"category":{"type":"string"},"size":{"type":"string"},"taxIncluded":{"type":"boolean","const":false},"taxCalculation":{"type":"string","const":"at_checkout"},"referencePrice":{"type":["number","null"],"description":"USD. Null means unknown, never free."},"currency":{"type":"string","const":"USD"},"priceStatus":{"type":"string","enum":["sale","reference","pending"]},"availability":{"type":"string","enum":["available","preview","unavailable"]},"checkoutAvailable":{"type":"boolean"},"checkoutMode":{"$ref":"#/components/schemas/Mode"},"unitAmount":{"type":["integer","null"],"description":"Price in USD cents."},"url":{"type":"string","format":"uri"},"imageUrl":{"type":"string","format":"uri"},"details":{"type":"object","description":"Verified product information. Unavailable fields are omitted.","properties":{"description":{"type":"string"},"highlights":{"type":"array","items":{"type":"string"}},"ingredients":{"type":"string"},"allergens":{"type":"string"},"directions":{"type":"string"},"warnings":{"type":"string"},"specifications":{"type":"object","additionalProperties":{"type":"string"}}}}}},"ProductList":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"nextOffset":{"type":["integer","null"]},"categories":{"type":"array","items":{"type":"string"}},"checkoutAvailable":{"type":"boolean"},"checkoutMode":{"$ref":"#/components/schemas/Mode"}}},"CheckoutAvailability":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"$ref":"#/components/schemas/Mode"}}},"CheckoutContact":{"type":"object","required":["address"],"additionalProperties":false,"properties":{"name":{"type":"string","maxLength":100},"address":{"type":"object","required":["line1","city"],"additionalProperties":false,"description":"U.S. addresses require state (two letters) and postal_code (5-digit ZIP).","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100,"example":"NY"},"postal_code":{"type":"string","maxLength":20,"example":"10118"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","default":"US"}}}}},"CheckoutSession":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Private Agentzon payment page for the buyer; keep the complete URL including its fragment. Existing hosted sessions may return a Stripe URL."},"orderId":{"type":"string"},"orderToken":{"type":"string"},"mode":{"$ref":"#/components/schemas/Mode"}}},"Order":{"type":"object","description":"Amounts are integer USD cents.","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","paid","expired"]},"paymentState":{"type":"string","enum":["unpaid","processing","paid","expired"],"description":"Verified Stripe state. An unpaid checkout is not a processing payment."},"mode":{"$ref":"#/components/schemas/Mode"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"integer"},"unitAmount":{"type":"integer"},"taxCode":{"type":"string"}}}},"subtotal":{"type":"integer"},"total":{"type":["integer","null"]},"tax":{"type":["integer","null"]},"shipping":{"type":["integer","null"]},"currency":{"type":"string","const":"usd"}}}}}}