{"service":"Receipt Monster","api_version":"1","docs":"/developers","privacy":"/privacy","description":"An invite-only household purchase ledger and shopping-list service. Purchase evidence is not pantry inventory; prices are historical.","authorization":{"type":"owner-issued bearer API key","manage":"/connections","capabilities":"/api/agent/capabilities","header":"Authorization: Bearer <owner-provided key>","required":true,"feedback":"To report a bug, missing field/endpoint or integration blocker, ask the operator for a separate feedback:create key. It can only POST /api/agent/feedback; full ledger keys cannot submit feedback.","instructions":"Ask the invited ledger owner to create a scoped connection. Receive its key privately, store it server-side, and query authenticated capabilities. No public signup, OAuth authorization server, MCP server or A2A endpoint is offered."},"protocols":{"http_json":true,"mcp":false,"a2a":false},"semantics":{"inventory":"not_tracked","purchases":"Purchase evidence only; remaining quantities and current availability are unknown.","estimates":"Historical receipt estimates, not live prices; requested quantities scale only with explicit compatible fixed-size packages; otherwise unpriced. With no requested quantity, estimates use historical line amounts. Unknown prices are null, not zero; check trip.unpriced. A line no receipt prices may carry basis \"guess\": a model's rough typical price, not evidence.","money":"Amounts follow the ledger's recorded currency; no currency conversion or currency code is supplied.","retry":"Only POST /api/agent/feedback accepts an Idempotency-Key. Elsewhere, do not blindly retry mutations after timeouts; read current state first. Partial effects may remain after a failed plan or upload."},"operations":[{"id":"capabilities","method":"GET","path":"/api/agent/capabilities","scopes":[],"mutates":false,"model":"never","description":"Describe this client's permitted operations and data limitations."},{"id":"summary","method":"GET","path":"/api/agent/summary","scopes":["summary:read"],"mutates":false,"model":"never","description":"Read monthly spending and a shopping-list summary. Optional today=YYYY-MM-DD; defaults to UTC date."},{"id":"receipts","method":"GET","path":"/api/agent/receipts","scopes":["receipts:read"],"mutates":false,"model":"never","description":"Read recent receipts. Optional since=ISO timestamp (exclusive added_at filter), limit=1..20 (default 10). Not an exhaustive change feed."},{"id":"uploadReceipt","method":"POST","path":"/api/agent/receipts","scopes":["receipts:write"],"mutates":true,"model":"always","description":"Upload multipart file (photo/PDF); updates ledger and checks off purchased list items. A duplicate returns 409; force=1 overrides only after confirmation."},{"id":"list","method":"GET","path":"/api/agent/list","scopes":["list:read"],"mutates":false,"model":"never","description":"Read shopping list and historical estimates. Optional store (max 100 characters); check store_matched for fallback."},{"id":"previewIngredients","method":"POST","path":"/api/agent/list/preview","scopes":["ingredients:preview"],"mutates":false,"model":"never","description":"Preview 1–20 ingredients against purchase evidence. Read-only: no list or budget changes. All candidates require confirmation; pantry availability is unknown. Estimates only for explicit compatible package sizes; otherwise null. Prices are historical, pre-tax, in the ledger currency.","body":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"quantity":{"anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]}},"required":["name"]}}},"required":["items"]}},{"id":"addList","method":"POST","path":"/api/agent/list","scopes":["list:read","list:write"],"mutates":true,"model":"never","description":"Add up to 20 items; skips matching unchecked names. Does not merge quantities or guarantee idempotency under concurrent requests.","body":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"section":{"type":"string","enum":["Produce","Meat & Seafood","Dairy & Eggs","Bakery","Beverages","Snacks","Frozen","Pantry Staples","Condiments & Sauces","Household","Health & Beauty","Alcohol","Prepared Food","Deli","Other"]},"quantity":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]}},"required":["name"]}}},"required":["items"]}},{"id":"checkListItem","method":"PATCH","path":"/api/agent/list/{id}","scopes":["list:write"],"mutates":true,"model":"never","description":"Set checked state of a shopping-list UUID. Repeating the same state is safe.","body":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"checked":{"type":"boolean"}},"required":["checked"]}},{"id":"removeListItem","method":"DELETE","path":"/api/agent/list/{id}","scopes":["list:write"],"mutates":true,"model":"never","description":"Remove a shopping-list UUID; missing or other-ledger items return 404."},{"id":"planList","method":"POST","path":"/api/agent/list/plan","scopes":["list:read","list:plan"],"mutates":true,"model":"when ideas=true","description":"Adds due items and optionally sets trip budget. budget=null clears it; absent preserves it. ideas=true calls a paid model with cooldown. Not a read-only preview.","body":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"store":{"type":"string","minLength":1,"maxLength":100},"budget":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":5000},{"type":"null"}]},"ideas":{"type":"boolean"}}}},{"id":"submitFeedback","method":"POST","path":"/api/agent/feedback","scopes":["feedback:create"],"mutates":true,"model":"never","description":"Submit one bug report, feature request or integration blocker about Receipt Monster. Returns only a random id; there is no list or read route. Text only; never include receipts, household members, addresses, purchase details or secrets. Optional Idempotency-Key header.","body":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"type":"string","enum":["bug","feature","integration"]},"title":{"type":"string","maxLength":120},"scenario":{"type":"string","maxLength":2000},"steps":{"type":"string","maxLength":2000},"expected":{"type":"string","maxLength":1000},"actual":{"type":"string","maxLength":1000},"impact":{"type":"string","maxLength":1000},"evidence":{"type":"string","maxLength":4000}},"required":["type","title","scenario"],"additionalProperties":false}}]}