# currency.convert Source: https://docs.receiptor.ai/api-reference/capabilities/currencyconvert https://developer.api.receiptor.ai/openapi.json post /capabilities/currency.convert Convert amounts between different currencies. Uses current rates by default, or historical rates for a specific date. # documents.bulk-edit Source: https://docs.receiptor.ai/api-reference/capabilities/documentsbulk-edit https://developer.api.receiptor.ai/openapi.json post /capabilities/documents.bulk-edit Bulk edit documents. Supports dry-run preview (default) and execute modes. Preview returns matching documents with proposed changes and available merchants/categories for context. # documents.count Source: https://docs.receiptor.ai/api-reference/capabilities/documentscount https://developer.api.receiptor.ai/openapi.json post /capabilities/documents.count Count documents and aggregate data. Use for spending totals and financial analysis. Supports grouping by merchant, category, date, etc. Gets ALL matching documents. # documents.delete Source: https://docs.receiptor.ai/api-reference/capabilities/documentsdelete https://developer.api.receiptor.ai/openapi.json post /capabilities/documents.delete 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. # documents.get Source: https://docs.receiptor.ai/api-reference/capabilities/documentsget https://developer.api.receiptor.ai/openapi.json post /capabilities/documents.get Retrieve a single document by ID with full details. Returns all extracted fields including merchant info, line items, amounts, file URL, and source. # documents.inspect Source: https://docs.receiptor.ai/api-reference/capabilities/documentsinspect https://developer.api.receiptor.ai/openapi.json post /capabilities/documents.inspect Inspect the original document file (image/PDF) with a vision model and compare visible values against currently stored extracted fields. # documents.search Source: https://docs.receiptor.ai/api-reference/capabilities/documentssearch https://developer.api.receiptor.ai/openapi.json post /capabilities/documents.search Search, filter, and retrieve user's documents. Supports text search, filtering by document type, export status, date ranges, sorting, and semantic similarity. # documents.unarchive Source: https://docs.receiptor.ai/api-reference/capabilities/documentsunarchive https://developer.api.receiptor.ai/openapi.json post /capabilities/documents.unarchive Restore a previously archived document so it is active again. # exports.get Source: https://docs.receiptor.ai/api-reference/capabilities/exportsget https://developer.api.receiptor.ai/openapi.json post /capabilities/exports.get Get one export record by ID for the current workspace. # exports.list Source: https://docs.receiptor.ai/api-reference/capabilities/exportslist https://developer.api.receiptor.ai/openapi.json post /capabilities/exports.list List export records with filters (document, integration, date range) for the current workspace. # files.upload Source: https://docs.receiptor.ai/api-reference/capabilities/filesupload https://developer.api.receiptor.ai/openapi.json post /capabilities/files.upload Upload a receipt, invoice, or financial document for processing. Accepts images (JPEG, PNG, GIF, WebP, BMP, TIFF) and PDFs up to 10MB. The file will be extracted and categorized automatically. # integrations.list Source: https://docs.receiptor.ai/api-reference/capabilities/integrationslist https://developer.api.receiptor.ai/openapi.json post /capabilities/integrations.list List available integrations for the user. Can filter by category (email, accounting, storage, social) and status. Returns integration IDs needed for sendToIntegration and other operations. # integrations.send Source: https://docs.receiptor.ai/api-reference/capabilities/integrationssend https://developer.api.receiptor.ai/openapi.json post /capabilities/integrations.send Send a document (receipt/invoice) to an accounting integration (Xero or QuickBooks). Requires integrationId and tenantId. Use listIntegrations to find available integrations. Set dryRun=true (default) to preview, dryRun=false to queue for sending. # integrations.unlink Source: https://docs.receiptor.ai/api-reference/capabilities/integrationsunlink https://developer.api.receiptor.ai/openapi.json post /capabilities/integrations.unlink 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. # rules.execute Source: https://docs.receiptor.ai/api-reference/capabilities/rulesexecute https://developer.api.receiptor.ai/openapi.json post /capabilities/rules.execute Create and save an automation rule from a natural language description. Requires explicit confirmation (confirm=true). Use prepareRule first to preview. # rules.list Source: https://docs.receiptor.ai/api-reference/capabilities/ruleslist https://developer.api.receiptor.ai/openapi.json post /capabilities/rules.list List automation rules for the user. Shows rule information including name, status, trigger type, and execution stats. # rules.prepare Source: https://docs.receiptor.ai/api-reference/capabilities/rulesprepare https://developer.api.receiptor.ai/openapi.json post /capabilities/rules.prepare Prepare a rule creation by converting natural language into a structured rule configuration. Returns a preview of what would be created. Use executeRule to save it. # workspaces.list Source: https://docs.receiptor.ai/api-reference/capabilities/workspaceslist https://developer.api.receiptor.ai/openapi.json post /capabilities/workspaces.list List available workspaces (organizations) for the authenticated user. # List all capabilities Source: https://docs.receiptor.ai/api-reference/discovery/list-all-capabilities https://developer.api.receiptor.ai/openapi.json get /capabilities Returns all available capabilities with their names, descriptions, permissions, and JSON Schema input definitions. No authentication required. # Exchange token Source: https://docs.receiptor.ai/api-reference/oauth2/exchange-token https://developer.api.receiptor.ai/openapi.json post /token Exchange a refresh token for a new access token. # OAuth 2.0 authorization Source: https://docs.receiptor.ai/api-reference/oauth2/oauth-20-authorization https://developer.api.receiptor.ai/openapi.json get /authorize Initiate the OAuth 2.0 authorization code flow with PKCE. # API Keys Source: https://docs.receiptor.ai/api/authentication/api-keys How to create API keys and use them with workspace context. ## Create an API key in the app In Receiptor App: 1. Open **Account -> API Keys** (`/account/api-keys`). 2. Click **Add New API Key**. 3. Copy the generated `sk_...` value. Important: the raw key is only shown once. ## Where API keys are accepted For API execution routes, send key in one of: * `Authorization: Bearer sk_...` * `X-Receiptor-API-Key: sk_...` * `apiKey` query/body fallback Recommended: `Authorization: Bearer ...` ## Workspace scope behavior Receiptor operations run in `userId + orgId` context. * Most capabilities require `orgId` context. * Send `X-Receiptor-Org-Id: org_...` when calling REST endpoints directly. * Use `GET /v1/workspaces` to discover allowed org IDs. If org context is missing on org-required capabilities, API returns `Organization context required`. If an API key is workspace-restricted and the org does not match, API returns `This API key is restricted to a different workspace`. ## OAuth vs API keys * API keys: best for direct REST and CLI usage. * OAuth tokens: required for MCP protected methods (`tools/call`) and are authorized per workspace. # Capability Approvals Source: https://docs.receiptor.ai/api/capabilities/approvals How approval-required capability execution works across REST, MCP, CLI, web assistant, and WhatsApp. ## Overview Some capabilities can preview safely but require explicit approval before execution. Receiptor now enforces this at the capability layer, not only in the web assistant prompt. That means the same approval policy is reused across: * REST API and API key clients * MCP clients * CLI * Web assistant * WhatsApp assistant ## When approval is required Common examples: * `documents.bulk-edit` with `dryRun: false` * `documents.resolve-duplicates` with `dryRun: false` * `integrations.send-to-integration` with `dryRun: false` * `integrations.unlink-document` with `dryRun: false` * `entities.cleanup` with `dryRun: false` * document archive/unarchive * entity delete/merge * `rules.execute` with `dryRun: false` Preview mode remains the default for dry-run capabilities. ## REST API behavior When a capability requires approval, `POST /v1/capabilities/:slug` returns a successful response with `status: "approval_required"` instead of executing the mutation. ```json theme={null} { "status": "approval_required", "approvalRequestId": "01J...", "capability": { "name": "bulkEditDocuments", "slug": "documents.bulk-edit" }, "title": "Apply bulk edit", "description": "Bulk editing updates multiple documents and requires approval before execution." } ``` Resolve it with: * `approvals.get` * `approvals.approve` * `approvals.reject` ## MCP behavior MCP capability tools follow the same policy. Instead of executing immediately, a gated tool call returns an `approval_required` payload and points the client at the approval tools: * `approvals_get` * `approvals_approve` * `approvals_reject` ## CLI behavior The CLI surfaces approval-required executions directly and includes built-in commands: ```bash theme={null} receiptor approval get receiptor approval approve receiptor approval reject --message "optional reason" ``` ## Web assistant behavior The web assistant uses LangGraph interrupt/resume. Risky actions pause the graph and render an approval card inline in the conversation. ## WhatsApp behavior WhatsApp uses reply buttons for approval: * `Approve` * `Reject` The approval reference is also included in the message footer so the request can be traced outside the button flow if needed. ## Currency resolution All approval-capable interfaces resolve currency from workspace context first. Priority order: 1. organization/workspace currency 2. user fallback currency 3. `usd` This matters for preview output because capability previews and execution summaries should reflect the active workspace, not only the individual user profile. # Discover Capabilities Source: https://docs.receiptor.ai/api/capabilities/discover Retrieve the capability catalog and input schemas. ## Endpoint `GET /v1/capabilities` No authentication required. ## Example ```bash theme={null} curl -s https://developer.api.receiptor.ai/v1/capabilities ``` ## What you get The response contains a `capabilities` array with: * `name` (internal) * `slug` (external execution identifier) * `description` * `permissions` * `inputSchema` (JSON Schema generated from Zod) ## Typical usage 1. Fetch discovery output. 2. Select capability by `slug`. 3. Build request body from `inputSchema`. 4. Execute with `POST /v1/capabilities/:slug`. # Execute Capability Source: https://docs.receiptor.ai/api/capabilities/execute Execute a capability by slug using API key authentication. ## Endpoint `POST /v1/capabilities/:slug` Authentication: API key required. ## Example: `documents.search` ```bash theme={null} curl -s -X POST https://developer.api.receiptor.ai/v1/capabilities/documents.search \ -H "Authorization: Bearer $RECEIPTOR_API_KEY" \ -H "X-Receiptor-Org-Id: $RECEIPTOR_ORG_ID" \ -H "Content-Type: application/json" \ -d '{ "query": "airbnb", "limit": 5, "docType": "receipt", "outputMode": "compact" }' ``` ## Example: `documents.bulk-edit` dry run ```bash theme={null} curl -s -X POST https://developer.api.receiptor.ai/v1/capabilities/documents.bulk-edit \ -H "Authorization: Bearer $RECEIPTOR_API_KEY" \ -H "X-Receiptor-Org-Id: $RECEIPTOR_ORG_ID" \ -H "Content-Type: application/json" \ -d '{ "merchant": "Uber", "changes": { "category": "Transport" }, "dryRun": true }' ``` `documents.bulk-edit` defaults to preview mode (`dryRun: true`). Set `dryRun: false` to apply changes. ## Approval-required execution If you call a gated capability in execute mode, the API returns an approval payload instead of running it immediately. Example cases: * `documents.bulk-edit` with `dryRun: false` * `documents.resolve-duplicates` with `dryRun: false` * `integrations.send-to-integration` with `dryRun: false` * `integrations.unlink-document` with `dryRun: false` * `entities.cleanup` with `dryRun: false` * `rules.execute` with `dryRun: false` ```json theme={null} { "status": "approval_required", "approvalRequestId": "01J...", "capability": { "name": "bulkEditDocuments", "slug": "documents.bulk-edit" }, "title": "Apply bulk edit", "description": "Bulk editing updates multiple documents and requires approval before execution." } ``` Approve or reject through the approval capabilities documented in [Capability Approvals](/api/capabilities/approvals). ## Common errors * `401` missing/invalid API key * `401` missing org context (`Organization context required`) * `403` API key restricted to a different workspace * `404` unknown capability slug * `400` input validation errors # Live Capabilities Catalog Source: https://docs.receiptor.ai/api/capabilities/live-catalog Auto-generated capability list and input schemas from the live discovery endpoint. This page is auto-generated from: * `https://developer.api.receiptor.ai/v1/capabilities` Last generated: `2026-03-09T08:32:50.283Z` ## Capabilities | Identifier | Slug | Description | Permissions | | ------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | `bulkEditDocuments` | - | Bulk edit receipts and invoices. Supports dry-run preview (default) and execute modes. Preview returns matching documents with proposed changes and available merchants/categories for context. | `documents:write` | | `countDocuments` | - | Count receipts and aggregate data. Use for spending totals and financial analysis. Supports grouping by merchant, category, date, etc. Gets ALL matching documents. | `documents:read` | | `searchDocuments` | - | Search, filter, and retrieve user's receipts and invoices. Supports text search, filtering by document type, export status, date ranges, sorting, and semantic similarity. | `documents:read` | ## Schemas ### `bulkEditDocuments` Bulk edit receipts and invoices. Supports dry-run preview (default) and execute modes. Preview returns matching documents with proposed changes and available merchants/categories for context. Permissions: * `documents:write` Input schema: ```json theme={null} { "type": "object", "properties": { "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" }, "dateFrom": { "type": "string", "description": "Start date filter (ISO format)" }, "dateTo": { "type": "string", "description": "End date filter (ISO format)" }, "changes": { "type": "object", "properties": { "merchant": { "type": "string", "description": "New merchant name to apply" }, "category": { "type": "string", "description": "New category to apply" } }, "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, "$schema": "http://json-schema.org/draft-07/schema#" } ``` ### `countDocuments` Count receipts and aggregate data. Use for spending totals and financial analysis. Supports grouping by merchant, category, date, etc. Gets ALL matching documents. Permissions: * `documents:read` Input schema: ```json theme={null} { "type": "object", "properties": { "filters": { "type": "object", "additionalProperties": {}, "description": "Advanced MongoDB filters (optional). Only allowed fields: currency, paymentMethod, paymentMethodEnding, fromEmail, toEmail, summary, taxAmount, subtotal, isRecurring, recurringType. Supports safe operators: $eq, $gt, $gte, $lt, $lte, $ne, $in, $nin, $regex, $exists, $and, $or. Example: { currency: { $in: ['usd', 'eur'] }, amount: { $gt: 1000 } }" }, "groupBy": { "type": "string", "description": "Field to group by for aggregation (e.g., 'merchant', 'category', 'date')" }, "merchant": { "type": "string", "description": "Filter by merchant name (case-insensitive, partial match)" }, "category": { "type": "string", "description": "Filter by category (case-insensitive, partial match)" }, "dateFrom": { "type": "string", "description": "Start date filter (ISO format)" }, "dateTo": { "type": "string", "description": "End date filter (ISO format)" }, "docType": { "type": "string", "enum": [ "invoice", "receipt" ], "description": "Filter by document type" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` ### `searchDocuments` Search, filter, and retrieve user's receipts and invoices. Supports text search, filtering by document type, export status, date ranges, sorting, and semantic similarity. Permissions: * `documents:read` Input schema: ```json theme={null} { "type": "object", "properties": { "query": { "type": "string", "description": "Search query for receipts/invoices (merchants, items, categories, etc.)" }, "limit": { "type": "number", "default": 5, "description": "Number of results to return" }, "docType": { "type": "string", "enum": [ "invoice", "receipt" ], "description": "Filter by document type" }, "sortBy": { "type": "string", "default": "docDate", "description": "Field to sort by (docDate, amount, merchant, etc.)" }, "sortOrder": { "type": "number", "default": -1, "description": "Sort order: 1 for ascending, -1 for descending" }, "dateFrom": { "type": "string", "description": "Start date filter (ISO format)" }, "dateTo": { "type": "string", "description": "End date filter (ISO format)" }, "useSearch": { "type": "boolean", "default": true, "description": "Whether to use text/semantic search" }, "searchType": { "type": "string", "enum": [ "similarity", "mmr" ], "default": "mmr", "description": "Search strategy: 'similarity' for specific merchants/exact matches, 'mmr' for diverse/exploratory results" }, "exportStatus": { "type": "string", "enum": [ "all", "exported", "not-exported" ], "description": "Filter by integration export status: 'exported' for documents sent to integrations, 'not-exported' for documents not yet sent, 'all' or omit for no filter" }, "outputMode": { "type": "string", "enum": [ "compact", "complete" ], "default": "compact", "description": "Output format: 'compact' returns essential fields (merchant, amount, date, category), 'complete' returns all available fields" }, "requiredFields": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Additional fields to include regardless of output mode (e.g., ['exportRecords', 'currency'] to always show these)" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` # Capabilities Overview Source: https://docs.receiptor.ai/api/capabilities/overview Discover and execute Receiptor capabilities through the external API. ## Endpoints Base host: `https://developer.api.receiptor.ai` * `GET /v1/capabilities` (public) * `POST /v1/capabilities/:slug` (API key required) Use capability `slug` values, for example `documents.search`. ## Authentication Execution endpoints accept API key in: * `Authorization: Bearer sk_...` * `X-Receiptor-API-Key: sk_...` * `apiKey` query/body fallback Most capabilities require workspace context. Provide: * `X-Receiptor-Org-Id: org_...` `workspaces.list` is intentionally unscoped so you can discover available orgs first. ## Keep capability docs current Do not hardcode capability lists. Always validate against live discovery: ```bash theme={null} curl -s https://developer.api.receiptor.ai/v1/capabilities ``` Use the API Reference tab (OpenAPI) for endpoint-level schema docs. See also: * [Live Capabilities Catalog](/api/capabilities/live-catalog) ## Response envelope ```json theme={null} { "success": true, "code": 200, "data": { "result": {} } } ``` Error shape: ```json theme={null} { "success": false, "code": 400, "error": { "errorCode": 400, "errorMessage": "..." } } ``` # CLI Commands Source: https://docs.receiptor.ai/api/cli/commands Command reference for API key auth, workspace context, and capability execution. ## Authenticate ```bash theme={null} receiptor auth sk_... receiptor auth --status ``` ## Workspace context commands ```bash theme={null} receiptor workspace --status receiptor workspace list receiptor workspace use org_... receiptor workspace clear ``` `workspace list` calls `GET /v1/workspaces`. Capability execution uses selected workspace by setting `X-Receiptor-Org-Id`. Workspace context also controls org-level defaults such as preferred currency. CLI capability execution resolves currency from the active workspace first, then falls back to the user profile. ## List capabilities ```bash theme={null} receiptor list ``` Calls `GET /v1/capabilities` and prints capability metadata. ## Execute capability with flags ```bash theme={null} receiptor documents search --query "uber" --limit 5 --outputMode compact ``` ## Execute using JSON input ```bash theme={null} receiptor documents search '{"query":"uber","limit":5}' ``` ## Execute using stdin ```bash theme={null} echo '{"merchant":"Uber","changes":{"category":"Transport"},"dryRun":true}' | receiptor documents bulk-edit ``` ## Approval commands ```bash theme={null} receiptor approval get 01J... receiptor approval approve 01J... receiptor approval reject 01J... --message "Not yet" ``` When a gated capability is called in execute mode, the CLI prints the `approval_required` payload instead of failing. You can then resolve that request with the `approval` commands above. ## Show input schema help ```bash theme={null} receiptor documents search --help ``` This fetches discovery output and prints selected capability `inputSchema`. # CLI Overview Source: https://docs.receiptor.ai/api/cli/introduction Use the Receiptor CLI to manage workspace context and execute capabilities. ## What the CLI does The CLI is a thin client over external API endpoints. It supports: * API key authentication * workspace context management * capability discovery and execution ## Install ```bash theme={null} npm i -g @receiptor/cli ``` ## Built-in commands * `receiptor auth ` * `receiptor auth --status` * `receiptor workspace --status` * `receiptor workspace list` * `receiptor workspace use ` * `receiptor workspace clear` * `receiptor list` * `receiptor [flags]` ## Default behavior * Default host: `https://developer.api.receiptor.ai` * API key source: * `RECEIPTOR_API_KEY`, or * local config file * Workspace source: * `RECEIPTOR_ORG_ID`, or * local config file (`receiptor workspace use`) ## Config file CLI stores config at: * `~/.receiptor/config.json` Fields include: * `apiKey` * `orgId` # API Overview Source: https://docs.receiptor.ai/api/introduction External API surface and capability-first model. ## Capability-first architecture Receiptor capabilities are defined once in backend and exposed through: * External REST API (`/v1/capabilities/*`) * MCP tools * CLI commands This keeps validation and behavior aligned across interfaces. ## Core external endpoints * `GET /v1/capabilities` (public discovery) * `POST /v1/capabilities/:slug` (execute) * `GET /v1/workspaces` (workspace listing for API key context) ## API reference generation The **API Reference** tab is generated from live OpenAPI: * `https://developer.api.receiptor.ai/openapi.json` Capability paths in OpenAPI are generated from the backend capability registry. Continue with: * [API Key Auth](/api/authentication/api-keys) * [Workspace Context](/api/workspaces/context) * [Capabilities Overview](/api/capabilities/overview) * [MCP Introduction](/api/mcp/introduction) * [CLI Overview](/api/cli/introduction) # MCP Client Setup Source: https://docs.receiptor.ai/api/mcp/client-setup Configure Receiptor MCP in major clients (Claude Code, Cursor, Windsurf, Cline). ## Endpoint Use the dedicated MCP host: * `https://mcp.receiptor.ai` This endpoint supports Streamable HTTP and OAuth2 metadata discovery. ## Claude Code Add Receiptor as a remote HTTP MCP server: ```bash theme={null} claude mcp add --transport http receiptor https://mcp.receiptor.ai ``` Then inside Claude Code: 1. Run `/mcp`. 2. Authenticate with OAuth. 3. Select the workspace you want to authorize. Useful commands: ```bash theme={null} claude mcp list claude mcp get receiptor claude mcp remove receiptor ``` ## Cursor Cursor supports MCP via project or global config: * Project: `.cursor/mcp.json` * Global: `~/.cursor/mcp.json` Example config: ```json theme={null} { "mcpServers": { "receiptor": { "url": "https://mcp.receiptor.ai" } } } ``` After saving config, use Cursor MCP tools to complete OAuth for the server. ## Windsurf (Cascade) Windsurf MCP config file: * `~/.codeium/windsurf/mcp_config.json` Remote HTTP example: ```json theme={null} { "mcpServers": { "receiptor": { "serverUrl": "https://mcp.receiptor.ai" } } } ``` In Cascade, open MCPs and complete OAuth for the Receiptor server. ## Cline Open MCP settings from Cline UI: 1. Click **MCP Servers**. 2. Open **Configure**. 3. Click **Configure MCP Servers**. Add a remote server entry in `cline_mcp_settings.json`: ```json theme={null} { "mcpServers": { "receiptor": { "url": "https://mcp.receiptor.ai", "type": "streamableHttp" } } } ``` Then authenticate in Cline when prompted. ## Verify setup Once connected, run: * `tools/list` You should see Receiptor tools such as: * `documents_search` * `documents_get` * `workspaces_list` If a tool call returns organization context errors, re-run OAuth and select the intended workspace. # MCP Introduction Source: https://docs.receiptor.ai/api/mcp/introduction Receiptor MCP server, transport, tools, and workspace behavior. ## Endpoints MCP is available via: * API host prefix: `https://api.receiptor.ai/mcp` * Dedicated MCP host root: `https://mcp.receiptor.ai` ## Protocol * Transport: Streamable HTTP * Payload format: JSON-RPC 2.0 * Tool registration: dynamic from backend capability registry ## Public methods No bearer token required: * `initialize` * `notifications/initialized` * `tools/list` * `prompts/list` * `resources/list` * `ping` ## Protected methods `tools/call` requires OAuth bearer token. ## Tool naming Capability tools are generated from capability slugs by replacing `.` with `_`. Examples: * `documents.search` -> `documents_search` * `workspaces.list` -> `workspaces_list` ## Native MCP-only tools * `get_server_info` * `workspace_get_context` * `workspace_switch` `workspace_switch` validates target workspace and explains that MCP workspace switching requires OAuth re-authorization with a different `org_id`. ## Client configuration examples For copy-paste setup examples in major MCP clients, see: * [MCP Client Setup](/api/mcp/client-setup) # MCP OAuth2 Source: https://docs.receiptor.ai/api/mcp/oauth Dynamic client registration, scopes, and workspace-bound authorization flow. ## Metadata endpoints Protected Resource Metadata: * `GET /mcp/.well-known/oauth-protected-resource` (or MCP host root equivalent) Authorization Server Metadata: * `GET /mcp/.well-known/oauth-authorization-server` (or MCP host root equivalent) Use metadata as the source of truth for current OAuth endpoints. ## Dynamic client registration Register a client with: * `POST /v1/oauth/register` Common fields: * `client_name` * `redirect_uris` * optional OAuth metadata (`grant_types`, `response_types`, `scope`, etc.) ## Authorization and token flow 1. Read authorization metadata. 2. Send user to `authorization_endpoint` with PKCE (`code_challenge`, `code_challenge_method=S256`). 3. User selects workspace in Receiptor authorization UI. 4. Exchange code at `token_endpoint`. MCP tokens are workspace-bound through selected `org_id`. To switch workspace, re-authorize with the target `org_id`. ## Supported scopes Current scopes include: * `all` * `read_documents` * `write_documents` * `read_time_capsules` * `write_time_capsules` * `read_currency` * `read_integrations` * `write_integrations` * `read_rules` * `write_rules` * `read_workspaces` Unrecognized scopes are rejected with `invalid_scope`. Request minimum required scope set. # MCP Transport & Methods Source: https://docs.receiptor.ai/api/mcp/transport-and-methods JSON-RPC methods, auth behavior, and request examples. ## JSON-RPC endpoint Send POST requests to MCP root: * `POST /mcp/` on API host * `POST /` on MCP host `GET` and `DELETE` on MCP root return `405 Method Not Allowed`. ## Example: initialize ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {} } ``` ## Example: list tools ```json theme={null} { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } ``` ## Example: call capability tool ```json theme={null} { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "documents_search", "arguments": { "query": "notion", "limit": 5 } } } ``` ## Approval-required MCP tool calls If an MCP tool maps to a capability that requires approval, the tool returns a structured payload instead of executing immediately. Example result: ```json theme={null} { "content": [ { "type": "text", "text": "{\n \"status\": \"approval_required\",\n \"approvalRequestId\": \"01J...\",\n \"capability\": {\n \"name\": \"bulkEditDocuments\",\n \"slug\": \"documents.bulk-edit\"\n },\n \"title\": \"Apply bulk edit\",\n \"description\": \"Bulk editing updates multiple documents and requires approval before execution.\",\n \"nextTools\": {\n \"get\": \"approvals_get\",\n \"approve\": \"approvals_approve\",\n \"reject\": \"approvals_reject\"\n }\n}" } ] } ``` Clients should then call: * `approvals_get` * `approvals_approve` * `approvals_reject` ## Example: list workspaces via MCP capability tool ```json theme={null} { "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "workspaces_list", "arguments": {} } } ``` ## Error behavior * Missing bearer token for protected method: JSON-RPC unauthorized error * Unknown tool name: JSON-RPC invalid params error * Capability execution failure: tool response includes error text * OAuth failures include `WWW-Authenticate: Bearer ...` challenge headers ## Workspace currency MCP capability execution resolves currency from the active workspace first, then falls back to the user profile, then `usd`. # AI Memory Source: https://docs.receiptor.ai/api/platform/ai-memory What Receiptor AI currently stores as long-term memory, how it is scoped, and where it is used. ## Overview Receiptor AI separates: * chat history * execution state * approval state * learning evidence * long-term memory This page is about the long-term memory infrastructure centered on `ai-memories` and its relationship to `correction-events`. ## What `ai-memories` is `ai-memories` stores reusable behavior and preferences that the system can apply across sessions. It is intentionally separate from: * Redis chat history * LangGraph thread checkpoints * approval request persistence * `correction-events` `correction-events` is the learning log. `ai-memories` is the durable memory layer that agents and ECR can actually use. ## What is implemented today Today `ai-memories` is used in two ways: * explicit memory saved through `memories.save` * candidate memory promotion from repeated `correction-events` * assistant-facing review and removal through `memories.list` and `memories.archive` Today the system consumes `active` memories in: * the web assistant * the WhatsApp assistant * the ECR extraction pipeline ## Memory model Each memory record has: * `scope` * `user` * `org` * `document` * `agent` * `kind` * implemented in current runtime surfaces: * `preference` * `canonical_mapping` * `workflow_hint` * `integration_preference` * reserved in the shared schema for future workflow intelligence: * `approval_policy_hint` * `playbook` * `source` * `user_declared` * `manual_correction` * `approval_history` * `system` * `status` * `active` * `candidate` * `rejected` * `archived` Records also track confidence, evidence count, and stable deduplication keys used for explicit saves and candidate upserts. ## Current rules ### Workspace-first behavior Operational memories are workspace-scoped by default. * promoted merchant/category/integration/workflow memories are `org` scoped * `user` scope is only allowed for explicit `preference` memories * document-scoped memories still require workspace context * memory operations require `orgId` This is deliberate. Shared operational behavior like categorization, canonical merchant names, and integration targeting should converge at workspace level, not per individual user. ### Activation behavior * promotion currently creates `candidate` memories only * only `active` memories are injected into runtime context * nothing auto-activates from a single correction or approval outcome ## What we currently save ### `preference` Current use: * explicit user-declared memory Examples: * response style preferences * presentation preferences * narrow personal assistant behavior Current scope: * `user`, `org`, or `document` ### `canonical_mapping` Current use: * promoted from repeated merchant/category corrections * explicit merchant/account categorization memories saved by the assistant after resolving the active workspace chart of accounts * explicit merchant label memories for recurring labels such as `personal` or `business` Examples: * merchant canonicalization * preferred chart-of-accounts category/account for a merchant * preferred labels for a merchant, such as `["personal"]` or `["business"]` Current scope: * `org` Important: * when a user asks the assistant to remember a categorization like "classify Vercel as software", the assistant should first resolve the active workspace chart of accounts * those memories should be saved as structured `canonical_mapping` records, not as free-text `preference` records * label memories are also structured `canonical_mapping` records * labels are the right memory mechanism for repeated classification like personal vs business when the user wants recurring document labels rather than an accounting account ### `workflow_hint` Current use: * promoted from repeated approval rejection feedback Examples: * preview first * show original before changing Current scope: * `org` ### `integration_preference` Current use: * promoted from repeated approved integration targets Current scope: * `org` ### Reserved kinds `playbook` and `approval_policy_hint` remain in the shared schema as reserved types for future workflow intelligence. They are not currently accepted by the memory capability surface, promoted by the learning system, or consumed by runtime retrieval. ## Where each type is used today ### Web assistant The web assistant reads `active` memories and injects them into planning context. Currently relevant: * `preference` * `canonical_mapping` * `workflow_hint` * `integration_preference` ### WhatsApp assistant The WhatsApp assistant uses the same long-term memory context model as the web assistant. Currently relevant: * `preference` * `canonical_mapping` * `workflow_hint` * `integration_preference` ### ECR ECR reads `active` memories and turns them into: * `promptHints` * `routingHints` * `entityHints` * `normalizationHints` Currently meaningful inputs: * `canonical_mapping` * merchant normalization * category preference normalization * label preference hints for downstream classification/routing * `workflow_hint` * prompt hints * routing hints * sender-domain hints * `integration_preference` * normalization context for downstream integration-aware behavior * `preference` * prompt hints only ## Important constraint Memories should influence planning, routing, normalization, and workflow selection. They should not silently override raw document truth during extraction. ## What is not implemented yet * a dedicated memory settings UI outside the assistant * richer shared discriminated TypeScript types for every memory-content variant in `@receiptor/schemas` # Backend Surface Map Source: https://docs.receiptor.ai/api/platform/backend-surfaces Host/path/auth mapping for API, MCP, and CLI. ## Integration surfaces The backend exposes three integration surfaces: * External API * MCP server (JSON-RPC) * CLI (wrapper over External API) ## Host and route mapping ### External API * Host: `developer.api.receiptor.ai` * Base path: `/v1` * Discovery: `GET /v1/capabilities` * Execute: `POST /v1/capabilities/:slug` * Workspaces: `GET /v1/workspaces` * Auth: API key for execute/workspace routes ### MCP * Host options: * `api.receiptor.ai/mcp/*` * `mcp.receiptor.ai/*` * JSON-RPC endpoint: * `POST /mcp/` on API host * `POST /` on MCP host * Protected method: `tools/call` (OAuth bearer token required) ### CLI * Binary: `receiptor` * Default host: `https://developer.api.receiptor.ai` * Built-in commands: `auth`, `workspace`, `list` * Capability execution: `receiptor ` ## Workspace context rules * API key calls can set workspace via `X-Receiptor-Org-Id`. * CLI sets the same header using `receiptor workspace use ` (or `RECEIPTOR_ORG_ID`). * MCP OAuth tokens are authorized for a selected `org_id`; switching workspace requires re-authorization. ## Production hosts * API: `https://api.receiptor.ai` * External API: `https://developer.api.receiptor.ai` * MCP: `https://mcp.receiptor.ai` # Correction Events Source: https://docs.receiptor.ai/api/platform/correction-events The raw learning log behind Receiptor AI memory promotion. ## Overview `correction-events` is the raw learning log for Receiptor AI. It is not long-term memory by itself. It is the evidence stream that later promotion logic can turn into typed `ai-memories`. ## What is implemented today The backend currently logs: * single-document manual edits * bulk edits * validation-error dismisses * approval approve/reject outcomes * rule execution * explicit memory submissions These records are stored in Mongo collection `correction-events`. Each event stores: * `subjectType` * `subjectIds` * `subjectCount` * `changedFields` * `changeSet` `subjectIds` is always a non-empty array, even for single-item events. That keeps the event model consistent between single-document and bulk operations. `subjectCount` is derived from the size of `subjectIds`. ## Current event types * `manual_patch` * `bulk_edit` * `validation_error_dismiss` * `capability_approval_approve` * `capability_approval_reject` * `agent_approval_approve` * `agent_approval_reject` * `rule_execute` * `memory_submission` ## Why it exists * it gives the system an auditable learning log * it separates evidence from policy * it lets promotion logic look for repeated patterns * it creates a future base for review flows and evals ## What uses it today ### Memory promotion The current consumer is memory promotion. Repeated patterns in `correction-events` can produce `candidate` `ai-memories`. Implemented promotion patterns today: * repeated merchant rename -> `canonical_mapping` * repeated category correction -> `canonical_mapping` * repeated approved integration target -> `integration_preference` * repeated approval rejection like `preview first` or `show original` -> `workflow_hint` ### Rule execution events Rule execution is currently logged as evidence, not treated as memory by itself. This matters because it shows when a workspace has moved from repeated correction into actual automation. That makes it useful for future workflow learning and evals even if it does not directly create a memory record today. ## Scope behavior The learning log is workspace-aware. * events require `orgId` * promotion signatures are now org-level, not personal * repeated corrections by different users in the same workspace can reinforce the same candidate memory ## Important constraint `correction-events` should stay broader than the current memory system. Not every event needs to become memory immediately, and that is intentional. # Workspace Context Source: https://docs.receiptor.ai/api/workspaces/context List workspaces and apply organization context in API, CLI, and MCP. ## Why workspace context exists Receiptor users can belong to multiple workspaces. Non-session interfaces (API key, CLI, MCP) must run in an explicit workspace context. ## List available workspaces (REST) ```bash theme={null} curl -s https://developer.api.receiptor.ai/v1/workspaces \ -H "Authorization: Bearer $RECEIPTOR_API_KEY" ``` Response includes: * `currentOrgId` * `workspaces[]` with `orgId`, `orgName`, `role`, `isCurrent` ## Apply workspace to capability execution (REST) ```bash theme={null} curl -s -X POST https://developer.api.receiptor.ai/v1/capabilities/documents.search \ -H "Authorization: Bearer $RECEIPTOR_API_KEY" \ -H "X-Receiptor-Org-Id: org_..." \ -H "Content-Type: application/json" \ -d '{"query":"uber"}' ``` ## CLI workspace commands ```bash theme={null} receiptor workspace --status receiptor workspace list receiptor workspace use org_... receiptor workspace clear ``` CLI uses selected workspace by sending `X-Receiptor-Org-Id` on capability calls. `RECEIPTOR_ORG_ID` env var overrides config for one-off runs. ## Capability equivalent `workspaces.list` is also exposed in capability discovery and MCP tooling for workspace listing use cases. ## Workspace-scoped defaults Non-session interfaces also resolve workspace-scoped defaults from the selected organization context. That includes preferred currency. The active workspace currency takes precedence over the user profile currency, with `usd` as the final fallback. Receiptor AI memory retrieval is also workspace-scoped. Long-term operational memory does not fall back to a personal workspace-less mode. # Introduction Source: https://docs.receiptor.ai/introduction Receiptor developer docs for API, capabilities, MCP, and CLI. ## What this documentation covers These docs describe how Receiptor integrates across: * External REST API * Capability discovery and execution * MCP (Model Context Protocol) * CLI command workflows * API key and OAuth2 authentication Create an API key from your account settings and understand workspace scoping. External host, routes, auth behavior, and request patterns. Discover and execute capability endpoints; schemas come from the live backend. Browse available capabilities from live discovery and API Reference. Use the same backend capabilities via MCP tools and OAuth tokens. Run capabilities and workspace commands from terminal. List workspaces and apply the correct org context for non-session interfaces. # Quickstart Source: https://docs.receiptor.ai/quickstart Create an API key, select workspace context, and run your first calls. ## 1. Create an API key In the app: 1. Open **Account -> API Keys** (`/account/api-keys`). 2. Click **Add New API Key**. 3. Copy the key immediately. API keys are shown only once after creation. ## 2. List your workspaces Use the API key to fetch available organizations: ```bash theme={null} curl -s https://developer.api.receiptor.ai/v1/workspaces \ -H "Authorization: Bearer $RECEIPTOR_API_KEY" ``` Pick the `orgId` you want to operate in. ## 3. Discover capabilities ```bash theme={null} curl -s https://developer.api.receiptor.ai/v1/capabilities ``` Use capability `slug` values for execution (for example, `documents.search`). ## 4. Execute a capability with workspace context ```bash theme={null} curl -s -X POST https://developer.api.receiptor.ai/v1/capabilities/documents.search \ -H "Authorization: Bearer $RECEIPTOR_API_KEY" \ -H "X-Receiptor-Org-Id: $RECEIPTOR_ORG_ID" \ -H "Content-Type: application/json" \ -d '{ "query": "uber", "limit": 5, "outputMode": "compact" }' ``` ## 5. Run the same flow in CLI ```bash theme={null} receiptor auth sk_... receiptor workspace list receiptor workspace use org_... receiptor list receiptor documents search --query "uber" --limit 5 ``` ## 6. Validate MCP tools Using your MCP client: 1. Call `initialize` 2. Call `tools/list` 3. Call `tools/call` with a capability tool name such as `documents_search` ## Next * [API Key Auth](/api/authentication/api-keys) * [Workspace Context](/api/workspaces/context) * [Capabilities Overview](/api/capabilities/overview) * [Live Capabilities Catalog](/api/capabilities/live-catalog) * [MCP Client Setup](/api/mcp/client-setup)