{"openapi":"3.0.0","info":{"title":"Receiptor AI API","description":"API for Receiptor AI — automates financial document extraction, categorization, and integration with accounting systems. All capabilities are available via `POST /v1/capabilities/{slug}` with a JSON request body.","version":"1.0.0","contact":{"name":"Receiptor AI","url":"https://receiptor.ai","email":"info@receiptor.ai"}},"servers":[{"url":"https://developer.api.receiptor.ai/v1","description":"Production"}],"tags":[{"name":"Capabilities","description":"Execute product capabilities"},{"name":"Discovery","description":"Discover available capabilities"},{"name":"Files","description":"Upload financial documents"},{"name":"OAuth2","description":"OAuth 2.0 authorization flow"}],"paths":{"/capabilities":{"get":{"summary":"List all capabilities","description":"Returns all available capabilities with their names, descriptions, permissions, and JSON Schema input definitions. No authentication required.","operationId":"discoverCapabilities","tags":["Discovery"],"security":[],"responses":{"200":{"description":"List of available capabilities","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"capabilities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Internal camelCase identifier"},"slug":{"type":"string","description":"External resource.action identifier"},"description":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"inputSchema":{"type":"object","description":"JSON Schema for the action input"}}}}}}}}}}}},"/capabilities/billing.get":{"post":{"summary":"billing.get","description":"Get billing account and subscription details for the active workspace, or the user's own billing account when no workspace is active.","operationId":"billing.get","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"includeUsage":{"type":"boolean","default":true},"includeFeatures":{"type":"boolean","default":true},"includeUpcomingInvoice":{"type":"boolean","default":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/billing.listHistory":{"post":{"summary":"billing.listHistory","description":"List invoices and one-off charges for the authenticated user's own billing account. This does not expose another workspace owner's invoice history.","operationId":"billing.listHistory","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100,"default":100},"startingAfter":{"type":"string","minLength":1}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/activity.search":{"post":{"summary":"activity.search","description":"Search past source activity logs across email, WhatsApp, uploads, and forwarded inbound email. For email sources, this first searches connected providers, then cross-checks matching message IDs against stored activity logs and returns any saved processing reasoning. Forwarded inbound email is matched directly against stored activity by its alias address.","operationId":"activity.search","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":2,"description":"Natural-language or exact search query such as merchant, sender, or invoice keyword."},"sourceTypes":{"type":"array","items":{"type":"string","enum":["email","whatsapp","upload","inbound-email"]},"default":["email","whatsapp","upload","inbound-email"],"description":"Which source activity types to search."},"statuses":{"type":"array","items":{"type":"string","enum":["queued","processed","skipped","failed","processing","warning"]},"description":"Optional activity statuses to include."},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for paginated results."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Maximum number of activity items to return."},"includeSourceDetails":{"type":"boolean","default":true,"description":"Whether to reload matching provider messages for richer email details like subject, sender, and snippet."},"providerResultLimit":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Maximum number of provider search matches to cross-check before filtering activity logs."}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/help-center.search":{"post":{"summary":"help-center.search","description":"Search public Receiptor help-center documentation for setup, troubleshooting, and product how-to answers. Returns grouped article results with the most relevant snippets.","operationId":"help-center.search","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":2,"description":"Natural language help-center query such as 'connect gmail', 'imap not connecting', or 'does receiptor send emails'."},"limit":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"Maximum number of help-center articles to return."},"snippetsPerResult":{"type":"integer","minimum":1,"maximum":3,"default":2,"description":"Maximum number of matching snippets to keep for each help-center article."}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/approvals.get":{"post":{"summary":"approvals.get","description":"Get the details of a pending or resolved approval request by ID.","operationId":"approvals.get","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approvalRequestId":{"type":"string","minLength":1,"description":"The approval request ID."}},"required":["approvalRequestId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/approvals.approve":{"post":{"summary":"approvals.approve","description":"Approve a pending request and run the reviewed action.","operationId":"approvals.approve","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approvalRequestId":{"type":"string","minLength":1,"description":"The approval request ID."}},"required":["approvalRequestId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/approvals.reject":{"post":{"summary":"approvals.reject","description":"Reject a pending request without running the reviewed action.","operationId":"approvals.reject","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approvalRequestId":{"type":"string","minLength":1,"description":"The approval request ID."},"message":{"type":"string","minLength":1,"maxLength":500}},"required":["approvalRequestId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.search":{"post":{"summary":"documents.search","description":"Search, filter, and retrieve user's documents. Supports text search, filtering by document type, export status, date ranges, sorting, and semantic similarity. Use documents.count for totals or grouped summaries across all matching documents.","operationId":"documents.search","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Text query (used only when useSearch=true). Omit in filter-only mode."},"limit":{"type":"number","default":5,"description":"Max documents to return"},"sortBy":{"type":"string","default":"docDate","description":"Sort field (docDate, amount, merchant, ...)"},"sortOrder":{"type":"number","default":-1,"description":"Sort order: 1 asc, -1 desc"},"where":{"type":"object","properties":{"logic":{"type":"string","enum":["and","or"],"default":"and"},"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["id","amount","docDate","merchant","category","docType","invoiceId","receiptId","preferredCurrency","currency","paymentStatus","paymentMethod","paymentMethodEnding","fromEmail","toEmail","summary","expenseLocation.primary.countryCode","expenseLocation.primary.country","expenseLocation.primary.city","expenseLocation.primary.stateOrProvince","expenseLocation.primary.kind","taxAmount","subtotal","isRecurring","recurringType","entityId"]},"op":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","nin","regex","exists"]},"value":{}},"required":["field","op"],"additionalProperties":false},"minItems":1}},"required":["conditions"],"additionalProperties":false,"description":"Typed filter clause. Allowed fields: id, amount, docDate, merchant, category, docType, invoiceId, receiptId, preferredCurrency, currency, paymentStatus, paymentMethod, paymentMethodEnding, fromEmail, toEmail, summary, expenseLocation.primary.countryCode, expenseLocation.primary.country, expenseLocation.primary.city, expenseLocation.primary.stateOrProvince, expenseLocation.primary.kind, taxAmount, subtotal, isRecurring, recurringType, entityId. Allowed ops: eq, ne, gt, gte, lt, lte, in, nin, regex, exists. Regex filters are already case-insensitive, so pass plain values like \"grab\" instead of inline flags like \"(?i)grab\"."},"useSearch":{"type":"boolean","default":true,"description":"Enable semantic/text search"},"searchType":{"type":"string","enum":["similarity","mmr"],"default":"mmr","description":"Search mode when useSearch=true: similarity (exact-ish) or mmr (broader)"},"exportStatus":{"type":"string","enum":["all","exported","not-exported"],"description":"Export status filter"},"archived":{"type":"string","enum":["exclude","only","include"],"default":"exclude","description":"Archive filter: exclude (default, active docs), only (archived docs), include (both)."},"outputMode":{"type":"string","enum":["compact","complete"],"default":"compact","description":"Response shape: compact (default) or complete"},"requiredFields":{"type":"array","items":{"type":"string","enum":["id","merchant","amount","currency","preferredCurrency","conversionRate","date","docDate","receivedAt","category","docType","summary","expenseLocation","invoiceId","receiptId","paymentStatus","entityId","entityName","exportStatus","link"]},"default":[],"description":"Always include these extra fields (in addition to outputMode defaults). Allowed fields: id, merchant, amount, currency, preferredCurrency, conversionRate, date, docDate, receivedAt, category, docType, summary, expenseLocation, invoiceId, receiptId, paymentStatus, entityId, entityName, exportStatus, link."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.get":{"post":{"summary":"documents.get","description":"Retrieve a single document by ID with full details. Returns all extracted fields including merchant info, line items, amounts, file URL, and source.","operationId":"documents.get","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The document ID to fetch"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.update":{"post":{"summary":"documents.update","description":"Update a single document by ID. Use this for precise corrections to extracted document fields that should not be applied through bulk edit.","operationId":"documents.update","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"changes":{"type":"object","properties":{"merchant":{"type":"string","minLength":1,"maxLength":255,"description":"Vendor/supplier/merchant name shown on the document. Do not use this for 'Billed to'."},"amount":{"type":"number","description":"Document amount in major currency units (for example 12.34)"},"currency":{"type":"string","pattern":"^[a-z]{3}$"},"preferredCurrency":{"$ref":"#/properties/changes/properties/currency"},"docDate":{"type":"string"},"category":{"$ref":"#/properties/changes/properties/merchant"},"docType":{"type":"string","enum":["invoice","receipt","credit_note","quote","purchase_order","order_confirmation"]},"invoiceId":{"allOf":[{"$ref":"#/properties/changes/properties/merchant"}],"nullable":true},"receiptId":{"$ref":"#/properties/changes/properties/invoiceId"},"taxAmount":{"$ref":"#/properties/changes/properties/amount","description":"Tax amount in major currency units (for example 1.23)"},"subtotal":{"$ref":"#/properties/changes/properties/amount","description":"Subtotal in major currency units (for example 11.11)"},"paymentMethod":{"anyOf":[{"allOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"string","enum":["cash","check","credit_card","debit_card","paypal","bank_transfer","other","unknown"]}]},{"enum":["null"],"nullable":true}]},"paymentMethodEnding":{"anyOf":[{"type":"string","minLength":1,"maxLength":16},{"enum":["null"],"nullable":true}]},"paymentStatus":{"type":"string","enum":["paid","unpaid","partial","refunded","unknown"]},"summary":{"anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"enum":["null"],"nullable":true}]},"entityId":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"enum":["null"],"nullable":true}],"description":"Legal entity ID assigned to the document. Use entity_list to resolve the entity ID from a business/entity name."},"labels":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":50},"taxRate":{"type":"number"},"isRecurring":{"type":"boolean"},"recurringType":{"anyOf":[{"type":"string","enum":["subscription","retainer","membership","license","lease","installment"]},{"enum":["null"],"nullable":true}]}},"additionalProperties":false,"description":"Single-document edits. Does not support fromEmail or toEmail."}},"required":["id","changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.list-duplicates":{"post":{"summary":"documents.list-duplicates","description":"List existing duplicate document groups for the current workspace.","operationId":"documents.list-duplicates","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Maximum duplicate groups to return"},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of duplicate groups to skip"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.scan-duplicates":{"post":{"summary":"documents.scan-duplicates","description":"Scan active unresolved documents in the current workspace for likely duplicate groups. Read-only: returns possible duplicate groups and recommends which documents to keep.","operationId":"documents.scan-duplicates","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Maximum candidate duplicate groups to return"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.inspect":{"post":{"summary":"documents.inspect","description":"Inspect the original document file (image/PDF) with a vision model and compare visible values against the saved document fields.","operationId":"documents.inspect","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Document ID to inspect"},"fields":{"type":"array","items":{"type":"string","enum":["merchant","amount","currency","docDate","invoiceId","receiptId","taxAmount","subtotal","paymentMethod","category","summary","docType"]},"description":"Specific fields to inspect from file. Defaults to core financial fields."},"maxPages":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"For PDFs, maximum pages to inspect (1-5). Defaults to 3."}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.count":{"post":{"summary":"documents.count","description":"Count documents and aggregate data. Use for spending totals and financial analysis. Supports grouping by merchant, category, date, export status, etc. Gets ALL matching documents.","operationId":"documents.count","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"where":{"type":"object","properties":{"logic":{"type":"string","enum":["and","or"],"default":"and"},"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["id","amount","docDate","merchant","category","docType","invoiceId","receiptId","preferredCurrency","currency","paymentStatus","paymentMethod","paymentMethodEnding","fromEmail","toEmail","summary","expenseLocation.primary.countryCode","expenseLocation.primary.country","expenseLocation.primary.city","expenseLocation.primary.stateOrProvince","expenseLocation.primary.kind","taxAmount","subtotal","isRecurring","recurringType","entityId"]},"op":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","nin","regex","exists"]},"value":{}},"required":["field","op"],"additionalProperties":false},"minItems":1}},"required":["conditions"],"additionalProperties":false,"description":"Typed filter clause. Allowed fields: id, amount, docDate, merchant, category, docType, invoiceId, receiptId, preferredCurrency, currency, paymentStatus, paymentMethod, paymentMethodEnding, fromEmail, toEmail, summary, expenseLocation.primary.countryCode, expenseLocation.primary.country, expenseLocation.primary.city, expenseLocation.primary.stateOrProvince, expenseLocation.primary.kind, taxAmount, subtotal, isRecurring, recurringType, entityId. Allowed ops: eq, ne, gt, gte, lt, lte, in, nin, regex, exists. Regex filters are already case-insensitive, so pass plain values like \"grab\" instead of inline flags like \"(?i)grab\"."},"exportStatus":{"type":"string","enum":["all","exported","not-exported"],"description":"Optional export status filter before aggregation"},"archived":{"type":"string","enum":["exclude","only","include"],"default":"exclude","description":"Archive filter: exclude (default, active docs), only (archived docs), include (both)."},"groupBy":{"type":"string","enum":["merchant","category","docType","currency","preferredCurrency","paymentMethod","paymentMethodEnding","paymentStatus","entityId","docDate","expenseLocation.primary.countryCode","expenseLocation.primary.country","expenseLocation.primary.city","expenseLocation.primary.stateOrProvince","expenseLocation.primary.kind","exportStatus"],"description":"Aggregation key. Allowed values: merchant, category, docType, currency, preferredCurrency, paymentMethod, paymentMethodEnding, paymentStatus, entityId, docDate, expenseLocation.primary.countryCode, expenseLocation.primary.country, expenseLocation.primary.city, expenseLocation.primary.stateOrProvince, expenseLocation.primary.kind, exportStatus. Use exportStatus to summarize exported vs not-exported documents."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.bulk-edit":{"post":{"summary":"documents.bulk-edit","description":"Bulk edit documents. Supports dry-run preview (default) and execute modes. Preview returns matching documents with proposed changes and available merchants/categories for context.","operationId":"documents.bulk-edit","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentIds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"Exact document IDs to edit. Use this for deterministic single-document or hand-picked multi-document edits."},"query":{"type":"string","description":"Search query to find documents (optional)"},"merchant":{"type":"string","description":"Specific merchant to filter for editing"},"category":{"type":"string","description":"Specific category to filter for editing"},"where":{"type":"object","properties":{"logic":{"type":"string","enum":["and","or"],"default":"and"},"conditions":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["id","amount","docDate","merchant","category","docType","invoiceId","receiptId","preferredCurrency","currency","paymentStatus","paymentMethod","paymentMethodEnding","fromEmail","toEmail","summary","expenseLocation.primary.countryCode","expenseLocation.primary.country","expenseLocation.primary.city","expenseLocation.primary.stateOrProvince","expenseLocation.primary.kind","taxAmount","subtotal","isRecurring","recurringType","entityId"]},"op":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","nin","regex","exists"]},"value":{}},"required":["field","op"],"additionalProperties":false},"minItems":1}},"required":["conditions"],"additionalProperties":false,"description":"Typed filter clause for targeted bulk edits. Allowed fields: id, amount, docDate, merchant, category, docType, invoiceId, receiptId, preferredCurrency, currency, paymentStatus, paymentMethod, paymentMethodEnding, fromEmail, toEmail, summary, expenseLocation.primary.countryCode, expenseLocation.primary.country, expenseLocation.primary.city, expenseLocation.primary.stateOrProvince, expenseLocation.primary.kind, taxAmount, subtotal, isRecurring, recurringType, entityId. Allowed ops: eq, ne, gt, gte, lt, lte, in, nin, regex, exists."},"changes":{"type":"object","properties":{"merchant":{"type":"string","description":"New vendor/supplier/merchant name to apply. Not for 'Billed to'."},"category":{"type":"string","description":"New category to apply"},"entityId":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"enum":["null"],"nullable":true}],"description":"Legal entity ID to assign to matching documents. Use null to clear it."},"paymentStatus":{"type":"string","enum":["paid","unpaid","partial","refunded","unknown"],"description":"New payment status to apply"},"labels":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":50,"description":"Replace labels with this exact set"},"shouldClearLabels":{"type":"boolean","description":"If true, remove all labels from matching documents"}},"additionalProperties":false,"description":"Changes to apply to matching documents"},"dryRun":{"type":"boolean","default":true,"description":"If true, shows preview without making changes. If false, executes the bulk edit."}},"required":["changes"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.resolve-duplicates":{"post":{"summary":"documents.resolve-duplicates","description":"Analyze a selected set of documents as possible duplicates. Use dryRun=true (default) to preview which document should be kept first. Use dryRun=false with masterId set to the document ID the user chose to keep.","operationId":"documents.resolve-duplicates","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":2,"maxItems":20,"description":"Document IDs to analyze as a possible duplicate set"},"masterId":{"type":"string","description":"The document ID to keep. Required only when dryRun=false and must be one of documentIds."},"dryRun":{"type":"boolean","default":true,"description":"If true, preview duplicate resolution. If false, keep the chosen document and archive the duplicates."}},"required":["documentIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.unlink-duplicate":{"post":{"summary":"documents.unlink-duplicate","description":"Remove one document from its duplicate group. If the selected document is the group master, the remaining duplicates are either dissolved or reassigned to a replacement master.","operationId":"documents.unlink-duplicate","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string","minLength":1,"description":"Document ID to remove from its duplicate group"},"replacementMasterId":{"type":"string","minLength":1,"description":"Optional duplicate child ID to promote when unlinking the current master"}},"required":["documentId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.repair-relationships":{"post":{"summary":"documents.repair-relationships","description":"Retroactively diagnose and repair deterministic document relationships for a bounded document set. Uses shared schemas logic to mark true same-type duplicates and link related invoice/receipt documents.","operationId":"documents.repair-relationships","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":2,"maxItems":100,"description":"Specific document IDs to diagnose and repair together"},"messageId":{"type":"string","minLength":1,"description":"Email message ID whose extracted documents should be repaired"},"processedEntityId":{"type":"string","minLength":1,"description":"Processed entity ID whose extracted documents should be repaired"},"limit":{"type":"integer","minimum":2,"maximum":500,"default":100,"description":"Maximum active documents to inspect"},"dryRun":{"type":"boolean","default":true,"description":"If true, preview deterministic repairs without writing changes"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.delete":{"post":{"summary":"documents.delete","description":"Soft-delete a document (receipt, invoice, etc.). The document is archived and can be recovered. Also archives any duplicate documents and cleans up cross-references.","operationId":"documents.delete","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The document ID to delete"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/documents.unarchive":{"post":{"summary":"documents.unarchive","description":"Restore a previously archived document so it is active again.","operationId":"documents.unarchive","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The archived document ID to restore"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/currency.convert":{"post":{"summary":"currency.convert","description":"Convert amounts between different currencies. Uses current rates by default, or historical rates for a specific date.","operationId":"currency.convert","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"The amount to convert"},"fromCurrency":{"type":"string","description":"The source currency code (e.g., 'USD', 'EUR', 'IDR')"},"toCurrency":{"type":"string","description":"The target currency code (e.g., 'USD', 'EUR', 'IDR')"},"date":{"type":"string","description":"Optional date for historical rates (YYYY-MM-DD format). Defaults to current rates if not provided."}},"required":["amount","fromCurrency","toCurrency"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/files.upload":{"post":{"summary":"files.upload","description":"Upload a receipt, invoice, or financial document for processing.","operationId":"files.upload","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"description":"Original file name including extension"},"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/gif","image/webp","image/bmp","image/tiff","application/pdf"],"description":"MIME type of the file"},"base64Data":{"type":"string","minLength":1,"description":"Base64-encoded file content"}},"required":["fileName","mimeType","base64Data"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/integrations.list":{"post":{"summary":"integrations.list","description":"List available integrations for the user. Can filter by category (email, accounting, storage, social, banking) and status. Returns integration IDs needed for sendToIntegration, reconcileWithIntegration, and other operations.","operationId":"integrations.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","enum":["email","accounting","storage","social","banking"],"description":"Filter by integration category"},"status":{"type":"string","enum":["active","disconnected"],"description":"Filter by integration status"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/integrations.send":{"post":{"summary":"integrations.send","description":"Send a document (receipt/invoice) to a supported accounting integration (Xero or QuickBooks). Requires integrationId. targetId is required for Xero/QuickBooks. Set dryRun=true (default) to preview, dryRun=false to queue for sending.","operationId":"integrations.send","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string","description":"The receipt/invoice document ID to send"},"integrationId":{"type":"string","description":"The integration ID to send to (use listIntegrations to find)"},"targetId":{"type":"string","description":"Optional target ID from listIntegrations. Use for accounting tenants or companies."},"dryRun":{"type":"boolean","default":true,"description":"If true, shows preview without sending. If false, queues the document for sending."}},"required":["documentId","integrationId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/integrations.reconcile":{"post":{"summary":"integrations.reconcile","description":"Reconcile a document (receipt/invoice) with a supported banking integration such as Mercury. Requires integrationId. targetId is optional for Mercury. Set dryRun=true (default) to preview, dryRun=false to queue for reconciliation.","operationId":"integrations.reconcile","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string","description":"The receipt/invoice document ID to reconcile"},"integrationId":{"type":"string","description":"The banking integration ID to reconcile with (use listIntegrations to find)"},"targetId":{"type":"string","description":"Optional target ID from listIntegrations. Use for Mercury account IDs when narrowing reconciliation."},"dryRun":{"type":"boolean","default":true,"description":"If true, shows preview without reconciling. If false, queues the document for reconciliation."}},"required":["documentId","integrationId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/integrations.unlink":{"post":{"summary":"integrations.unlink","description":"Unlink a document from an integration (supports Xero and QuickBooks). Set dryRun=true (default) to preview, including invoice details and orphaned attachments. Set dryRun=false to execute. This action is IRREVERSIBLE.","operationId":"integrations.unlink","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string","description":"The receipt history document ID"},"exportRecordId":{"type":"string","description":"The export record ID linking the document to the integration"},"dryRun":{"type":"boolean","default":true,"description":"If true, shows preview without making changes. If false, executes the unlinking."}},"required":["documentId","exportRecordId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/automations.list":{"post":{"summary":"automations.list","description":"List automations with name, status, trigger type, and execution stats.","operationId":"automations.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"includeDisabled":{"type":"boolean","default":false,"description":"Include disabled automations in results"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Number of automations to return (max 50)"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/automations.execute":{"post":{"summary":"automations.execute","description":"Create an automation from a natural language description. Approval includes the generated automation details before creation.","operationId":"automations.execute","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"naturalLanguageAutomation":{"type":"string","minLength":1,"maxLength":1000,"description":"Natural language description of the automation to create"}},"required":["naturalLanguageAutomation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/automations.delete":{"post":{"summary":"automations.delete","description":"Delete an automation permanently.","operationId":"automations.delete","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The ID of the automation to delete"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/automations.disable":{"post":{"summary":"automations.disable","description":"Disable an automation without deleting it.","operationId":"automations.disable","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The ID of the automation to disable"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/views.list":{"post":{"summary":"views.list","description":"List saved document views for the current workspace. These saved views can be reused by automations and workflows.","operationId":"views.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum views to return"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/views.create":{"post":{"summary":"views.create","description":"Create a saved document view from document filters. Saved views are reusable inputs for automations and workflows.","operationId":"views.create","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Saved view name"},"description":{"type":"string","description":"Optional saved view description"},"query":{"type":"object","properties":{"search":{"type":"string","description":"Text search"},"docType":{"type":"string","description":"Document type filter (comma-separated)"},"paymentStatus":{"type":"string","description":"Payment status filter (comma-separated)"},"integrationId":{"type":"string","description":"Integration ID filter (comma-separated)"},"merchants":{"type":"string","description":"Merchant filter (comma-separated)"},"last4":{"type":"string","description":"Card last-4 filter (comma-separated)"},"labels":{"type":"string","description":"Label filter (comma-separated)"},"source":{"type":"string","description":"Source filter (comma-separated: upload,email,whatsapp)"},"category":{"type":"string","description":"Category filter (comma-separated)"},"entityId":{"type":"string","description":"Entity ID filter (comma-separated)"},"workspaceMemberId":{"type":"string","description":"Workspace member filter (comma-separated user IDs)"},"amountDirection":{"type":"string","enum":["any","in","out"],"description":"Amount direction filter"},"amountEq":{"type":"string","description":"Exact amount filter in major units"},"amountMin":{"type":"string","description":"Minimum amount filter in major units"},"amountMax":{"type":"string","description":"Maximum amount filter in major units"},"fromDate":{"type":"string","description":"Absolute from date in YYYY-MM-DD format"},"toDate":{"type":"string","description":"Absolute to date in YYYY-MM-DD format"},"relativeDateRange":{"type":"string","enum":["today","yesterday","last_7_days","last_14_days","last_30_days","last_90_days","this_week","last_week","this_month","last_month","this_quarter","last_quarter","this_year","last_year","year_to_date"],"description":"Relative date range"}},"additionalProperties":false,"description":"Saved document filter query"},"sort":{"type":"object","properties":{"field":{"type":"string","minLength":1,"description":"Sort field"},"direction":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[-1]}],"description":"Sort direction: 1 asc, -1 desc"}},"required":["field","direction"],"additionalProperties":false,"description":"Optional sort configuration for the saved view"}},"required":["name","query"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/views.delete":{"post":{"summary":"views.delete","description":"Delete a saved document view. Use this when a saved filter preset is no longer needed.","operationId":"views.delete","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Saved view ID to delete"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/workspaces.list":{"post":{"summary":"workspaces.list","description":"List available workspaces (organizations) for the authenticated user.","operationId":"workspaces.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/workspaces.list-members":{"post":{"summary":"workspaces.list-members","description":"List members (users) of a workspace (organization), defaulting to the active workspace.","operationId":"workspaces.list-members","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","minLength":1},"limit":{"type":"integer","minimum":1,"maximum":200},"offset":{"type":"integer","minimum":0}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/workspace.context.patch":{"post":{"summary":"workspace.context.patch","description":"Update workspace business profile and location/tax context fields used for categorization readiness.","operationId":"workspace.context.patch","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessType":{"type":"string"},"businessSize":{"type":"string"},"annualRevenue":{"type":"string"},"revenueModel":{"type":"string"},"industry":{"type":"string"},"subindustry":{"type":"string"},"primaryExpenseCategories":{"type":"array","items":{"type":"string"}},"sellsPhysicalProducts":{"type":"boolean"},"tracksInventory":{"type":"boolean"},"hasManufacturingWholesale":{"type":"boolean"},"businessLocations":{"type":"string"},"taxRequirements":{"type":"string"},"separateReporting":{"type":"boolean"},"differentCountries":{"type":"boolean"},"jurisdictionTracking":{"type":"boolean"},"country":{"type":"string"},"exportPreferences":{"type":"array","items":{"type":"string","enum":["xero","quickbooks","mercury","google-drive","dropbox","pdf-export","csv-export","zip-export","email-forward"]}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/context.readiness":{"post":{"summary":"context.readiness","description":"Get workspace context readiness for categorization, including missing business profile, tax, chart of accounts, and entity setup fields.","operationId":"context.readiness","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/context_requests.list":{"post":{"summary":"context_requests.list","description":"List pending request-for-context records that are blocking categorization.","operationId":"context_requests.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":50,"default":20},"offset":{"type":"integer","minimum":0,"default":0},"subjectType":{"type":"string","minLength":1,"maxLength":120}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/context_requests.group":{"post":{"summary":"context_requests.group","description":"Group pending request-for-context records by suggested account, account, merchant, or document type.","operationId":"context_requests.group","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":50,"default":50}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/context_requests.resolve":{"post":{"summary":"context_requests.resolve","description":"Resolve one request-for-context.","operationId":"context_requests.resolve","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hitlRequestId":{"type":"string","minLength":1},"action":{"anyOf":[{"type":"object","properties":{"action":{"type":"string","enum":["leave_uncategorized"]},"reason":{"type":"string","maxLength":500}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["provide_context"]},"context":{"type":"string","minLength":1,"maxLength":2000},"saveAsMemory":{"type":"boolean","default":false}},"required":["action","context"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["archive_document"]},"archiveReason":{"type":"string","maxLength":500}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["suggest_account"]},"suggestedAccount":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":255},"accountNumber":{"type":"string","maxLength":50},"rationale":{"type":"string","maxLength":500}},"required":["name"],"additionalProperties":false}},"required":["action"],"additionalProperties":false}]}},"required":["hitlRequestId","action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/context_requests.bulk_resolve":{"post":{"summary":"context_requests.bulk_resolve","description":"Resolve selected request-for-context records in bulk.","operationId":"context_requests.bulk_resolve","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hitlRequestIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50},"action":{"anyOf":[{"type":"object","properties":{"action":{"type":"string","enum":["leave_uncategorized"]},"reason":{"type":"string","maxLength":500}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["provide_context"]},"context":{"type":"string","minLength":1,"maxLength":2000},"saveAsMemory":{"type":"boolean","default":false}},"required":["action","context"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["archive_document"]},"archiveReason":{"type":"string","maxLength":500}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["suggest_account"]},"suggestedAccount":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":255},"accountNumber":{"type":"string","maxLength":50},"rationale":{"type":"string","maxLength":500}},"required":["name"],"additionalProperties":false}},"required":["action"],"additionalProperties":false}]}},"required":["hitlRequestIds","action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/chartOfAccounts.list":{"post":{"summary":"chartOfAccounts.list","description":"List Charts of Accounts available to the current workspace.","operationId":"chartOfAccounts.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","minimum":1,"default":1},"limit":{"type":"integer","minimum":1,"maximum":200,"default":25},"search":{"type":"string","minLength":1,"maxLength":200},"includeAccounts":{"type":"boolean","default":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/chartOfAccounts.listAccounts":{"post":{"summary":"chartOfAccounts.listAccounts","description":"List or search accounts from the active chart of accounts for the current workspace so the agent can ground categorization decisions.","operationId":"chartOfAccounts.listAccounts","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chartId":{"type":"string","minLength":1,"maxLength":200},"query":{"type":"string","minLength":1,"maxLength":200},"limit":{"type":"integer","minimum":1,"maximum":100,"default":100},"includeIds":{"type":"boolean","default":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/exports.create":{"post":{"summary":"exports.create","description":"Preview or queue document exports using the same behavior as the in-app Export dropdown. Supports CSV/PDF/ZIP to the user's registered email, email forwarding, and connected export integrations. Use filters or viewId for broad exports. Use docIds only for exact selections of 10 or fewer documents.","operationId":"exports.create","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["csv","pdf","zip","forward","xero","quickbooks","mercury","google-drive","dropbox"],"description":"Export destination/format to queue"},"dryRun":{"type":"boolean","default":true,"description":"Preview matching documents when true; queue the export when false"},"docIds":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Specific document IDs to export. Maximum 10; use export filters for larger exports."},"viewId":{"type":"string","minLength":1,"description":"Saved document view ID to use as the export filter source"},"docType":{"type":"string","description":"Comma-separated document type filter, e.g. receipt,invoice"},"paymentStatus":{"type":"string","description":"Comma-separated payment status filter, e.g. paid,unpaid"},"dateFrom":{"type":"string","description":"Start date filter (ISO format)"},"dateTo":{"type":"string","description":"End date filter (ISO format)"},"search":{"type":"string","description":"Search query filter"},"merchants":{"type":"string","description":"Comma-separated merchant filter"},"labels":{"type":"string","description":"Comma-separated label filter"},"timeCapsuleId":{"type":"string","description":"Retroactive Scan/time capsule ID"},"integrationId":{"type":"string","description":"Integration ID for accounting/storage exports"},"targetId":{"type":"string","description":"Tenant/company/account target ID for integrations"},"forwardTo":{"type":"array","items":{"type":"string","format":"email"},"description":"Recipient emails for forward exports"},"storageNamingFormat":{"type":"string","minLength":1,"description":"ZIP storage naming format"},"includeLineItems":{"type":"boolean","default":false,"description":"Include line items in CSV export"},"csvTemplateId":{"type":"string","description":"CSV template ID"},"customFields":{"type":"array","items":{"type":"string"},"description":"Custom CSV field names"}},"required":["format"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/exports.list":{"post":{"summary":"exports.list","description":"List export records with filters (document, integration, date range) for the current workspace.","operationId":"exports.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string","description":"Filter export records by document ID"},"integrationSlug":{"type":"string","enum":["xero","quickbooks","mercury","google-drive","dropbox","pdf-export","csv-export","zip-export","email-forward"],"description":"Filter export records by integration (xero, quickbooks, google-drive, etc.)"},"dateFrom":{"type":"string","description":"Start date filter (ISO format)"},"dateTo":{"type":"string","description":"End date filter (ISO format)"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Max records to return (1-100)"},"offset":{"type":"integer","minimum":0,"default":0,"description":"Pagination offset"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/exports.get":{"post":{"summary":"exports.get","description":"Get one export record by ID for the current workspace.","operationId":"exports.get","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The export record ID to fetch"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/retroactiveExtractions.estimate":{"post":{"summary":"retroactiveExtractions.estimate","description":"Queue a Retroactive Scan estimate for the given email integration and date range. Returns a jobId immediately; poll with getRetroactiveExtractionEstimate. Estimation against a real mailbox can take minutes; use the poll capability rather than waiting.","operationId":"retroactiveExtractions.estimate","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationId":{"type":"string","minLength":1,"description":"The email integration ID to estimate against (use listIntegrations to find)."},"fromDate":{"type":"string","pattern":"^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$","description":"Inclusive start date in YYYY-MM-DD format."},"toDate":{"type":"string","pattern":"^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$","description":"Inclusive end date in YYYY-MM-DD format."},"sendersPreference":{"type":"string","enum":["allowed","blocked"],"description":"Whether the sender list is an allow-list or block-list."},"mailboxId":{"type":"string","description":"Mailbox/folder id to scope the estimate. Defaults to 'all'."}},"required":["integrationId","fromDate","toDate","sendersPreference"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/retroactiveExtractions.getEstimate":{"post":{"summary":"retroactiveExtractions.getEstimate","description":"Fetch the current status of a Retroactive Scan estimate by jobId. Returns queued/active/completed/failed status, in-flight progress, and the final result when completed.","operationId":"retroactiveExtractions.getEstimate","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","minLength":1,"description":"The estimation job ID returned by retroactiveExtractions.estimate."}},"required":["jobId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/referrals.get_or_create":{"post":{"summary":"referrals.get_or_create","description":"Get the authenticated user's referral link and stats, creating their referral profile only when missing.","operationId":"referrals.get_or_create","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.email.list":{"post":{"summary":"sources.email.list","description":"List email sources connected to the account, including provider and monitoring status.","operationId":"sources.email.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"includeInactive":{"type":"boolean","description":"Include inactive/disconnected email sources. Default: false (active only)"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.mobile-scanners.list":{"post":{"summary":"sources.mobile-scanners.list","description":"List mobile scanners connected to the account, including activation and AI chat status.","operationId":"sources.mobile-scanners.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"includeInactive":{"type":"boolean","description":"Include inactive/deactivated scanners. Default: false (active only)"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.email.enable-monitoring":{"post":{"summary":"sources.email.enable-monitoring","description":"Enable monitoring for an email source to resume syncing new receipts and invoices.","operationId":"sources.email.enable-monitoring","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationId":{"type":"string","minLength":1,"description":"The email integration ID"}},"required":["integrationId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.email.delete":{"post":{"summary":"sources.email.delete","description":"Delete an email source from the account and stop monitoring it permanently.","operationId":"sources.email.delete","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationId":{"type":"string","minLength":1,"description":"The email integration ID"}},"required":["integrationId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.email.disable-monitoring":{"post":{"summary":"sources.email.disable-monitoring","description":"Disable monitoring for an email source without removing the connection.","operationId":"sources.email.disable-monitoring","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationId":{"type":"string","minLength":1,"description":"The email integration ID"}},"required":["integrationId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.email.reauthorize":{"post":{"summary":"sources.email.reauthorize","description":"Prepare reauthorization instructions for an email source with expired or invalid credentials.","operationId":"sources.email.reauthorize","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"integrationId":{"type":"string","minLength":1,"description":"The email integration ID"}},"required":["integrationId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.mobile-scanners.activate":{"post":{"summary":"sources.mobile-scanners.activate","description":"Activate a mobile scanner so documents from that number are processed again.","operationId":"sources.mobile-scanners.activate","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scannerId":{"type":"string","minLength":1,"description":"The mobile scanner ID"}},"required":["scannerId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.mobile-scanners.enable-ai":{"post":{"summary":"sources.mobile-scanners.enable-ai","description":"Enable WhatsApp AI assistant replies for a mobile scanner without changing document processing.","operationId":"sources.mobile-scanners.enable-ai","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scannerId":{"type":"string","minLength":1,"description":"The mobile scanner ID"}},"required":["scannerId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.mobile-scanners.delete":{"post":{"summary":"sources.mobile-scanners.delete","description":"Delete a mobile scanner from the account permanently.","operationId":"sources.mobile-scanners.delete","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scannerId":{"type":"string","minLength":1,"description":"The mobile scanner ID"}},"required":["scannerId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.mobile-scanners.deactivate":{"post":{"summary":"sources.mobile-scanners.deactivate","description":"Deactivate a mobile scanner without deleting it.","operationId":"sources.mobile-scanners.deactivate","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scannerId":{"type":"string","minLength":1,"description":"The mobile scanner ID"}},"required":["scannerId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/sources.mobile-scanners.disable-ai":{"post":{"summary":"sources.mobile-scanners.disable-ai","description":"Disable WhatsApp AI assistant replies for a mobile scanner without changing document processing.","operationId":"sources.mobile-scanners.disable-ai","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scannerId":{"type":"string","minLength":1,"description":"The mobile scanner ID"}},"required":["scannerId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/entities.cleanup":{"post":{"summary":"entities.cleanup","description":"Analyze and clean up the user's own legal entities: enrich with Google Places data, find duplicates via place_id and embedding similarity, and merge them. This is for companies/legal entities/subsidiaries, not merchant or document duplicates.","operationId":"entities.cleanup","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":true,"description":"Preview changes without executing. Set to false after user confirms."},"maxEntities":{"type":"number","default":200,"description":"Maximum number of entities to process in one invocation"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/entities.review_consolidation":{"post":{"summary":"entities.review_consolidation","description":"Review possible legal entity consolidation groups without making changes.","operationId":"entities.review_consolidation","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"maxEntities":{"type":"integer","minimum":1,"maximum":500,"default":200,"description":"Maximum number of entities to scan for consolidation candidates"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/entities.execute_consolidation_plan":{"post":{"summary":"entities.execute_consolidation_plan","description":"Execute one approved group from a reviewed legal entity consolidation plan.","operationId":"entities.execute_consolidation_plan","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"planHash":{"type":"string"},"groupId":{"type":"string"},"plan":{"type":"object","properties":{"planHash":{"type":"string"},"generatedAt":{"type":"string"},"maxEntities":{"type":"integer","minimum":1},"totalEntities":{"type":"integer","minimum":0},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"keepEntity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"},"default":[]},"streetAddress":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateOrProvince":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"googlePlaceId":{"type":"string"},"taxId":{"type":"string"},"linkedDocumentsCount":{"type":"integer","minimum":0,"default":0},"signature":{"type":"string"}},"required":["id","name","signature"],"additionalProperties":false},"mergeEntities":{"type":"array","items":{"$ref":"#/properties/plan/properties/groups/items/properties/keepEntity"},"minItems":1},"matchReason":{"type":"string","enum":["same_place_id","embedding_similarity"]},"confidence":{"type":"number","minimum":0,"maximum":1},"policy":{"type":"object","properties":{"status":{"type":"string","enum":["executable","needs_review","blocked"]},"reason":{"type":"string","enum":["same_google_place","compatible_name_and_location","conflicting_location","embedding_only"]},"executable":{"type":"boolean"},"message":{"type":"string"}},"required":["status","reason","executable","message"],"additionalProperties":false},"linkedDocumentsCount":{"type":"integer","minimum":0}},"required":["id","keepEntity","mergeEntities","matchReason","confidence","policy","linkedDocumentsCount"],"additionalProperties":false}}},"required":["planHash","generatedAt","maxEntities","totalEntities","groups"],"additionalProperties":false}},"required":["planHash","groupId","plan"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/entities.list":{"post":{"summary":"entities.list","description":"List and search legal entities with pagination.","operationId":"entities.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Search term to filter entities by name, address, or aliases"},"page":{"type":"number","default":1,"description":"Page number"},"limit":{"type":"number","default":25,"description":"Results per page (max 50)"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/entities.upsert":{"post":{"summary":"entities.upsert","description":"Create a new legal entity or update an existing one.","operationId":"entities.upsert","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"string","description":"Entity ID to update. Omit to create a new entity."},"name":{"type":"string","description":"Legal entity name"},"entityKind":{"type":"string","enum":["individual","organization"],"nullable":true,"description":"Whether the legal entity is an individual or organization. Null clears the assignment."},"streetAddress":{"type":"string","description":"Street address"},"addressLine2":{"type":"string","description":"Address line 2"},"city":{"type":"string","description":"City"},"stateOrProvince":{"type":"string","description":"State or province"},"postalCode":{"type":"string","description":"Postal/zip code"},"country":{"type":"string","description":"Country name"},"contactNumber":{"type":"string","description":"Phone number"},"email":{"type":"string","description":"Email address"},"taxId":{"type":"string","description":"Tax ID / VAT number"},"chartOfAccountsId":{"anyOf":[{"$ref":"#/properties/entityId"},{"type":"string","enum":["default"]}],"nullable":true,"description":"Chart of accounts used to categorize this entity's documents. Null clears the assignment."},"aliases":{"type":"array","items":{"type":"string"},"description":"Alternative names for this entity"}},"required":["name","country"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/entities.update":{"post":{"summary":"entities.update","description":"Apply typed partial updates to one or more legal entities.","operationId":"entities.update","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string"},"patch":{"type":"object","properties":{"chartOfAccountsId":{"anyOf":[{"$ref":"#/properties/updates/items/properties/entityId"},{"type":"string","enum":["default"]}],"nullable":true,"description":"Chart of accounts used to categorize this entity's documents. Null clears the assignment."}},"required":["chartOfAccountsId"],"additionalProperties":false}},"required":["entityId","patch"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["updates"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/entities.delete":{"post":{"summary":"entities.delete","description":"Delete a legal entity and unlink associated documents.","operationId":"entities.delete","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entityId":{"type":"string","description":"ID of the entity to delete"}},"required":["entityId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/entities.merge":{"post":{"summary":"entities.merge","description":"Merge multiple legal entities into one. Reassigns all linked documents to the kept entity, adds merged entity names as aliases, and deletes the duplicates.","operationId":"entities.merge","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keepEntityId":{"type":"string","description":"ID of the legal entity to keep as the canonical record"},"mergeEntityIds":{"type":"array","items":{"$ref":"#/properties/keepEntityId"},"minItems":1,"description":"IDs of legal entities to merge into the kept entity. Their names become aliases and linked documents are reassigned."}},"required":["keepEntityId","mergeEntityIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/merchants.list":{"post":{"summary":"merchants.list","description":"List and search merchants with document counts, spend totals, currencies, and profile fields.","operationId":"merchants.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Search term to filter merchants by name"},"fromDate":{"type":"string","description":"Only include documents on or after this date"},"toDate":{"type":"string","description":"Only include documents on or before this date"},"currency":{"type":"string","pattern":"^[a-z]{3}$","description":"Only include documents in this source currency"},"sortBy":{"type":"string","enum":["name","totalSpent","count","lastTransaction"],"default":"name"},"page":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":1,"description":"Page number"},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000,"default":100,"description":"Results per page"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/merchants.merge":{"post":{"summary":"merchants.merge","description":"Merge multiple merchant names into one preferred merchant name and save that preference for future use.","operationId":"merchants.merge","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keepMerchantName":{"type":"string","minLength":1,"maxLength":255,"description":"Preferred merchant name to keep"},"mergeMerchantNames":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"minItems":1,"description":"Merchant names to merge into the preferred merchant name"},"merchantWebsite":{"type":"string","maxLength":500,"description":"Preferred merchant website URL"},"merchantTaxId":{"type":"string","maxLength":255,"description":"Preferred merchant tax ID or VAT number"},"merchantAddress":{"type":"string","maxLength":1000,"description":"Preferred merchant address"}},"required":["keepMerchantName","mergeMerchantNames"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/merchants.rename":{"post":{"summary":"merchants.rename","description":"Rename one merchant to a preferred merchant name, optionally updating website, tax ID, and address.","operationId":"merchants.rename","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"currentMerchantName":{"type":"string","minLength":1,"maxLength":255,"description":"Current merchant name to rename"},"newMerchantName":{"type":"string","minLength":1,"maxLength":255,"description":"Preferred merchant name to apply"},"merchantWebsite":{"type":"string","maxLength":500,"description":"Preferred merchant website URL"},"merchantTaxId":{"type":"string","maxLength":255,"description":"Preferred merchant tax ID or VAT number"},"merchantAddress":{"type":"string","maxLength":1000,"description":"Preferred merchant address"}},"required":["currentMerchantName","newMerchantName"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/memories.save":{"post":{"summary":"memories.save","description":"Save a long-term memory, preference, canonical mapping, workflow hint, or deterministic document policy.","operationId":"memories.save","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"summary":{"type":"string","minLength":1,"maxLength":1000},"text":{"type":"string","minLength":1,"maxLength":4000},"kind":{"type":"string","enum":["preference","canonical_mapping","workflow_hint","document_policy"],"default":"preference"},"scope":{"type":"string","enum":["user","org","document"],"default":"org"},"documentId":{"type":"string","minLength":1,"maxLength":64},"mappingType":{"type":"string","enum":["merchant_canonicalization","category_preference","label_preference"]},"from":{"type":"string","minLength":1,"maxLength":200},"to":{"type":"string","minLength":1,"maxLength":200},"merchant":{"type":"string","minLength":1,"maxLength":200},"labels":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20},"chartOfAccountsId":{"type":"string","minLength":1,"maxLength":64},"chartAccountId":{"type":"string","minLength":1,"maxLength":128},"policyDomain":{"type":"string","enum":["recurring"],"description":"Document policy domain. Use recurring for subscription or repeat-charge decisions."},"policyAction":{"type":"string","enum":["not_recurring","stopped","set_recurring_schedule"],"description":"Deterministic action to apply when the document policy matcher applies."},"amount":{"type":"integer","nullable":true,"description":"Optional amount in the currency's minor units."},"currency":{"type":"string","minLength":3,"maxLength":3,"nullable":true,"description":"Optional ISO currency code for amount matching."},"amountTolerance":{"type":"integer","minimum":0,"nullable":true,"description":"Optional amount tolerance in minor currency units."},"recurringType":{"type":"string","enum":["subscription","retainer","membership","license","lease","installment"],"nullable":true,"description":"Optional recurring type matcher."},"recurringFrequency":{"type":"string","enum":["weekly","bi-weekly","monthly","quarterly","semi-annual","annual"],"nullable":true,"description":"Optional recurring frequency matcher."},"setRecurringType":{"type":"string","enum":["subscription","retainer","membership","license","lease","installment"],"nullable":true,"description":"Recurring type to set when policyAction is set_recurring_schedule."},"setRecurringFrequency":{"type":"string","enum":["weekly","bi-weekly","monthly","quarterly","semi-annual","annual"],"nullable":true,"description":"Recurring frequency to set when policyAction is set_recurring_schedule."},"sourceDocumentId":{"type":"string","minLength":1,"maxLength":64,"nullable":true,"description":"Optional source document ID."},"note":{"type":"string","maxLength":500,"nullable":true,"description":"Optional user note explaining the policy."}},"required":["title","summary"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/memories.archive":{"post":{"summary":"memories.archive","description":"Archive a stored long-term memory so it is no longer used at runtime.","operationId":"memories.archive","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"memoryId":{"type":"string","minLength":1,"maxLength":64}},"required":["memoryId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/memories.list":{"post":{"summary":"memories.list","description":"List current long-term memories stored for the current user/workspace.","operationId":"memories.list","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"statuses":{"type":"array","items":{"type":"string","enum":["active","candidate","rejected","archived"]},"maxItems":4},"kinds":{"type":"array","items":{"type":"string","enum":["preference","canonical_mapping","workflow_hint","document_policy","integration_preference","approval_policy_hint","playbook","routing_preference"]},"maxItems":8},"includeDocumentMemories":{"type":"boolean","default":true},"documentIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/memories.recall":{"post":{"summary":"memories.recall","description":"Recall task-relevant long-term memories just in time for an agent task.","operationId":"memories.recall","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"intent":{"type":"string","enum":["categorization","document_policy","integration","approval","routing","user_preference","workflow"],"description":"Task intent that determines which memory kinds are relevant."},"query":{"type":"string","minLength":1,"maxLength":1000,"description":"Current user request or focused search text."},"merchant":{"type":"string","minLength":1,"maxLength":200,"description":"Known merchant/vendor to match memory against."},"documentIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":20,"description":"Known document IDs relevant to this task."},"kinds":{"type":"array","items":{"type":"string","enum":["preference","canonical_mapping","workflow_hint","document_policy","integration_preference","approval_policy_hint","playbook","routing_preference"]},"maxItems":8,"description":"Optional explicit memory kinds to recall. Omit to use the intent defaults."},"limit":{"type":"integer","minimum":1,"maximum":20,"default":8}},"required":["intent"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/capabilities/onboarding.status":{"post":{"summary":"onboarding.status","description":"Get the user's onboarding/setup progress including which steps are completed and what's pending.","operationId":"onboarding.status","tags":["Capabilities"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"result":{"type":"object","description":"Capability-specific result"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/files":{"post":{"summary":"Upload a financial document","description":"Upload a receipt, invoice, or PDF using multipart form data. Send exactly one file in the `file` field. Authenticate with either a Receiptor API key or a Bearer token for your Receiptor account.","operationId":"uploadFile","tags":["Files"],"security":[{"apiKey":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Receipt, invoice, or PDF to upload"}}}}}},"responses":{"200":{"description":"File upload accepted for processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"file":{"type":"object","properties":{"uploadId":{"type":"string"},"fileName":{"type":"string"},"status":{"type":"string","example":"queued"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/authorize":{"get":{"summary":"OAuth 2.0 authorization","description":"Initiate the OAuth 2.0 authorization code flow with PKCE.","operationId":"oauthAuthorize","tags":["OAuth2"],"servers":[{"url":"https://api.receiptor.ai/oauth2"}],"security":[],"parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"client_secret","in":"query","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","description":"Space-delimited OAuth scopes","enum":["all","read_time_capsules","write_time_capsules","read_documents","write_documents","read_entities","write_entities","read_currency","read_integrations","write_integrations","write_exports","read_memories","write_memories","read_automations","write_automations","read_workspaces","write_workspaces","read_referrals","write_referrals","read_billing","offline_access"]}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string"}},{"name":"response_type","in":"query","required":true,"schema":{"type":"string","default":"code","enum":["code"]}},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":true,"schema":{"type":"string","default":"S256","enum":["S256"]}}],"responses":{"200":{"description":"Authorization code issued","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Temporary authorization code"},"redirect_uri":{"type":"string"}}}}}}}}},"/token":{"post":{"summary":"Exchange token","description":"Exchange a refresh token for a new access token.","operationId":"oauthToken","tags":["OAuth2"],"security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["client_id","client_secret","grant_type","refresh_token"],"properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"grant_type":{"type":"string","default":"refresh_token","enum":["refresh_token"]},"refresh_token":{"type":"string"}}}}}},"responses":{"200":{"description":"New access token"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-receiptor-api-key","description":"Receiptor API key prefixed with `sk_`. Provide via the x-receiptor-api-key header or as a Bearer token."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token for a Receiptor account. Include x-receiptor-org-id for workspace-scoped endpoints."},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authorization code flow with PKCE.","flows":{"authorizationCode":{"authorizationUrl":"https://api.receiptor.ai/oauth2/authorize","tokenUrl":"https://api.receiptor.ai/oauth2/token","scopes":{"all":"Full access","offline_access":"Maintain access without repeated authorization","read_time_capsules":"Read time capsules","write_time_capsules":"Create, update, and delete time capsules","read_documents":"Read documents","write_documents":"Create and update documents","read_entities":"Read legal entities","write_entities":"Create, update, merge, and clean up legal entities","read_currency":"Read currency conversion data","read_integrations":"Read integrations","write_integrations":"Create, update, and remove integration links","write_exports":"Create document exports","read_memories":"Read AI memories","write_memories":"Create, update, and archive AI memories","read_automations":"Read automations","write_automations":"Create, update, and execute automations","read_workspaces":"Read workspace membership and context","write_workspaces":"Update workspace context","read_referrals":"Read referral profile and stats","write_referrals":"Create and update referral profile","read_billing":"Read billing account, subscription, invoice, and payment history"}}}}},"responses":{"BadRequest":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"code":{"type":"integer","example":400},"error":{"type":"object","properties":{"errorCode":{"type":"integer","example":400},"errorMessage":{"type":"string"}}}}}}}},"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"code":{"type":"integer","example":401},"error":{"type":"object","properties":{"errorCode":{"type":"integer","example":401},"errorMessage":{"type":"string","example":"API key authentication required"}}}}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"code":{"type":"integer","example":404},"error":{"type":"object","properties":{"errorCode":{"type":"integer","example":404},"errorMessage":{"type":"string"}}}}}}}}}}}