{"openapi":"3.1.0","info":{"title":"OrderForge agent API","version":"1.0.0","description":"Sandbox demo with synthetic data. An agent can ask a demo shop for a priced box and read the result. It cannot choose a price, accept a quote, pay, or read any other request. A human opens the returned humanUrl to choose the box, accept the exact price and approve the payment on PayPal."},"paths":{"/api/agent/v1/stores":{"get":{"summary":"List the demo shops","responses":{"200":{"description":"The shops","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"stores":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"simulated":{"type":"boolean","const":true},"links":{"type":"object","properties":{"describe":{"type":"string"},"createRequest":{"type":"string"}},"required":["describe","createRequest"],"additionalProperties":false}},"required":["slug","name","kind","simulated","links"],"additionalProperties":false}}},"required":["stores"],"additionalProperties":false}}}}}}},"/api/agent/v1/stores/{slug}":{"get":{"summary":"What a shop needs to make a request","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The shop and its request fields","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"simulated":{"type":"boolean","const":true},"currency":{"type":"string","const":"USD"},"fulfilment":{"type":"string","const":"customer_pickup"},"parts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"request":{"type":"object","properties":{"method":{"type":"string","const":"POST"},"path":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"},"min":{"type":"number"},"max":{"type":"number"},"description":{"type":"string"}},"required":["name","type","required","description"],"additionalProperties":false}},"unknownFieldsRejected":{"type":"boolean","const":true},"freeText":{"type":"boolean","const":false}},"required":["method","path","fields","unknownFieldsRejected","freeText"],"additionalProperties":false},"payment":{"type":"object","properties":{"approvedBy":{"type":"string","const":"human"},"note":{"type":"string"}},"required":["approvedBy","note"],"additionalProperties":false}},"required":["slug","name","kind","simulated","currency","fulfilment","parts","request","payment"],"additionalProperties":false}}}},"404":{"description":"No such shop","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","INVALID_INPUT","INVALID_JSON","PAYLOAD_TOO_LARGE","RATE_LIMITED","UNSUPPORTED_MEDIA_TYPE"]},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"}},"required":["field","code"],"additionalProperties":false}}},"required":["code"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/agent/v1/stores/{slug}/requests":{"post":{"summary":"Ask a shop for a priced box","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"boxCount":{"type":"integer","minimum":1,"maximum":10000},"noFood":{"type":"boolean"},"logoRequired":{"type":"boolean"},"maxPricePerBoxMinor":{"type":"integer","minimum":1,"maximum":10000000},"requestedPickupDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["boxCount","noFood","logoRequired","maxPricePerBoxMinor"],"additionalProperties":false}}}},"responses":{"201":{"description":"The request, the box code chose and priced, a link for a human, and a read-only token","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"request":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"proposalStatus":{"type":"string","enum":["VALID","BLOCKED"]},"proposals":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["BOX","SWAP"]},"lines":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string"},"sku":{"type":"string"},"name":{"type":"string"},"unitPriceMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["slotId","sku","name","unitPriceMinor","quantity"],"additionalProperties":false}},"perBoxMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"boxCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currency":{"type":"string","const":"USD"},"swap":{"type":"object","properties":{"slotId":{"type":"string"},"fromSku":{"type":"string"},"toSku":{"type":"string"}},"required":["slotId","fromSku","toSku"],"additionalProperties":false}},"required":["kind","lines","perBoxMinor","totalMinor","boxCount","currency"],"additionalProperties":false}},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":{}}}},"required":["id","status","proposalStatus","proposals","blockers"],"additionalProperties":false},"humanUrl":{"type":"string"},"requestToken":{"type":"string"},"note":{"type":"string"}},"required":["request","humanUrl","requestToken","note"],"additionalProperties":false}}}},"400":{"description":"Invalid body or invalid JSON; nothing was stored","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","INVALID_INPUT","INVALID_JSON","PAYLOAD_TOO_LARGE","RATE_LIMITED","UNSUPPORTED_MEDIA_TYPE"]},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"}},"required":["field","code"],"additionalProperties":false}}},"required":["code"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No such shop","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","INVALID_INPUT","INVALID_JSON","PAYLOAD_TOO_LARGE","RATE_LIMITED","UNSUPPORTED_MEDIA_TYPE"]},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"}},"required":["field","code"],"additionalProperties":false}}},"required":["code"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","INVALID_INPUT","INVALID_JSON","PAYLOAD_TOO_LARGE","RATE_LIMITED","UNSUPPORTED_MEDIA_TYPE"]},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"}},"required":["field","code"],"additionalProperties":false}}},"required":["code"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","INVALID_INPUT","INVALID_JSON","PAYLOAD_TOO_LARGE","RATE_LIMITED","UNSUPPORTED_MEDIA_TYPE"]},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"}},"required":["field","code"],"additionalProperties":false}}},"required":["code"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Too many requests; see Retry-After","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","INVALID_INPUT","INVALID_JSON","PAYLOAD_TOO_LARGE","RATE_LIMITED","UNSUPPORTED_MEDIA_TYPE"]},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"}},"required":["field","code"],"additionalProperties":false}}},"required":["code"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/agent/v1/requests/{id}":{"get":{"summary":"Read the request you made","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"requestToken":[]}],"responses":{"200":{"description":"Status and proposals, computed now by code","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"request":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"proposalStatus":{"anyOf":[{"type":"string","enum":["VALID","BLOCKED"]},{"type":"null"}]},"proposals":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["BOX","SWAP"]},"lines":{"type":"array","items":{"type":"object","properties":{"slotId":{"type":"string"},"sku":{"type":"string"},"name":{"type":"string"},"unitPriceMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["slotId","sku","name","unitPriceMinor","quantity"],"additionalProperties":false}},"perBoxMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"boxCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currency":{"type":"string","const":"USD"},"swap":{"type":"object","properties":{"slotId":{"type":"string"},"fromSku":{"type":"string"},"toSku":{"type":"string"}},"required":["slotId","fromSku","toSku"],"additionalProperties":false}},"required":["kind","lines","perBoxMinor","totalMinor","boxCount","currency"],"additionalProperties":false}},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":{}}},"missing":{"type":"array","items":{"type":"string"}}},"required":["id","status","proposalStatus","proposals","blockers","missing"],"additionalProperties":false}},"required":["request"],"additionalProperties":false}}}},"404":{"description":"Wrong token, wrong id, expired or revoked: always the same answer","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","INVALID_INPUT","INVALID_JSON","PAYLOAD_TOO_LARGE","RATE_LIMITED","UNSUPPORTED_MEDIA_TYPE"]},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"}},"required":["field","code"],"additionalProperties":false}}},"required":["code"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}}},"components":{"securitySchemes":{"requestToken":{"type":"http","scheme":"bearer","description":"The requestToken returned when the request was made. Read-only."}}}}