{"openapi":"3.1.0","info":{"title":"Receipt Keep API","version":"0.1.0","description":"A digital-receipt organization methodology: computed categorization into tax-deductible/warranty/returnable/general buckets, computed warranty-expiry and return-window date maths (with IRS-sourced tax-retention guidance), a hand-curated filing system across three organization styles, a batch report tool, and a glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://receiptkeep.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/receiptkeep/docs"},"termsOfService":"https://connectorbay.com/receiptkeep/terms"},"servers":[{"url":"https://receiptkeep.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/receiptkeep/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/categorize_receipt":{"post":{"operationId":"categorize_receipt","summary":"Scores a plain-language purchase description against four categories — tax-deductible, warranty-relevant,","description":"Scores a plain-language purchase description against four categories — tax-deductible, warranty-relevant,\n    returnable-window, general-household — and returns the best match with the matched keywords as its\n    reasoning, plus that category's retention guidance. Use for \"what category is a new laptop receipt\", \"is a\n    client lunch tax-deductible or general\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"description":{"description":"Plain-language description of the purchase.","examples":["a new laptop from an electronics store","client lunch meeting","a pair of running shoes"],"minLength":1,"title":"Description","type":"string"}},"required":["description"],"title":"categorize_receiptArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/retention_guidance":{"post":{"operationId":"retention_guidance","summary":"How long to keep a receipt in one category, with sourcing — including the IRS's actual 3-year general","description":"How long to keep a receipt in one category, with sourcing — including the IRS's actual 3-year general\n    rule, 6-year underreported-income rule, 7-year bad-debt rule, and indefinite-retention situations for the\n    tax-deductible category. Use for \"how long do I need to keep tax receipts\", \"when can I throw out a warranty\n    receipt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"One of: tax_deductible, warranty_relevant, returnable_window, general_household.","examples":["tax_deductible"],"title":"Category","type":"string"}},"required":["category"],"title":"retention_guidanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/warranty_expiry_date":{"post":{"operationId":"warranty_expiry_date","summary":"Computes the exact warranty expiry date from a purchase date and a warranty length in months, plus how many","description":"Computes the exact warranty expiry date from a purchase date and a warranty length in months, plus how many\n    days remain and a status (active / expiring_soon / expired). Use for \"when does the warranty expire if I\n    bought it March 1 with a 12-month warranty\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"purchase_date":{"description":"Purchase date, YYYY-MM-DD.","examples":["2026-03-01"],"title":"Purchase Date","type":"string"},"warranty_months":{"description":"Warranty length in months.","examples":[12],"maximum":360,"minimum":1,"title":"Warranty Months","type":"integer"}},"required":["purchase_date","warranty_months"],"title":"warranty_expiry_dateArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/return_window_deadline":{"post":{"operationId":"return_window_deadline","summary":"Computes the exact return-window deadline from a purchase date and the store's return window in days, plus","description":"Computes the exact return-window deadline from a purchase date and the store's return window in days, plus\n    how many days remain and a status (active / expiring_soon / expired). Use for \"when's the last day I can\n    return something bought September 20 with a 30-day return policy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"purchase_date":{"description":"Purchase date, YYYY-MM-DD.","examples":["2026-09-20"],"title":"Purchase Date","type":"string"},"window_days":{"description":"The store's return window, in days.","examples":[30],"maximum":365,"minimum":1,"title":"Window Days","type":"integer"}},"required":["purchase_date","window_days"],"title":"return_window_deadlineArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/tax_deduction_categories":{"post":{"operationId":"tax_deduction_categories","summary":"Common tax-deductible purchase categories (business expenses, home office, charitable donations, medical,","description":"Common tax-deductible purchase categories (business expenses, home office, charitable donations, medical,\n    professional development) with the IRS retention guidance that applies to them. Use for \"what counts as a\n    tax-deductible purchase\", \"how long do I keep business receipts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"tax_deduction_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/organization_system":{"post":{"operationId":"organization_system","summary":"Step-by-step setup for one concrete receipt-organization method: a digital folder structure, a spreadsheet","description":"Step-by-step setup for one concrete receipt-organization method: a digital folder structure, a spreadsheet\n    ledger, or a receipt-scanning app workflow. Use for \"give me a filing system for my receipts\", \"how should I\n    set up a spreadsheet to track receipts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"method":{"description":"One of: digital_folder, spreadsheet, app.","examples":["spreadsheet"],"title":"Method","type":"string"}},"required":["method"],"title":"organization_systemArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/organization_systems_list":{"post":{"operationId":"organization_systems_list","summary":"Names the three organization methods this reference covers, one line each. Use for \"what receipt","description":"Names the three organization methods this reference covers, one line each. Use for \"what receipt\n    organization systems do you know about\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"organization_systems_listArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/filing_checklist":{"post":{"operationId":"filing_checklist","summary":"A weekly / monthly / annual routine for staying on top of receipt organization without a backlog building","description":"A weekly / monthly / annual routine for staying on top of receipt organization without a backlog building\n    up. Use for \"what's a good routine for managing receipts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"filing_checklistArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/batch_receipt_report":{"post":{"operationId":"batch_receipt_report","summary":"Computes a category, and where enough detail is given a keep-until date and status, for up to 50 receipts","description":"Computes a category, and where enough detail is given a keep-until date and status, for up to 50 receipts\n    in a single call — useful for reviewing a batch at once instead of one at a time. Use for \"check the status\n    of these receipts\", \"categorize this list of purchases\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"receipts":{"description":"Each item: {description, category?, purchase_date? (YYYY-MM-DD), warranty_months?, window_days?}.","examples":[[{"description":"new laptop","purchase_date":"2026-06-01","warranty_months":12},{"description":"running shoes","purchase_date":"2026-09-20","window_days":30}]],"items":{"additionalProperties":true,"type":"object"},"maxItems":50,"minItems":1,"title":"Receipts","type":"array"}},"required":["receipts"],"title":"batch_receipt_reportArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/receiptkeep_glossary":{"post":{"operationId":"receiptkeep_glossary","summary":"Defines receipt-organization terms — retention period, keep-until date, proof of purchase, audit window,","description":"Defines receipt-organization terms — retention period, keep-until date, proof of purchase, audit window,\n    warranty period, return window. Use for \"what's a keep-until date\", \"what's an audit window\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"receiptkeep_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}