API and MCP
One API key gives your own tools, and assistants like Claude, the same invoices, suppliers and reports your workspace has. Included in both plans.
What a key can do
Everything below is read with a viewer key; the ones marked as member keys also write.
- Read every invoiceFields, currency, review status and where each read value came from, newest first, filtered by source.
- Download the originalsThe PDF exactly as it arrived, straight from the workspace it is stored in.
- Suppliers and their defaultsEvery supplier with its type, keywords, team and project defaults and cost splits.
- Cost reportsThe same monthly totals the dashboard shows, by type, department, project, source or supplier.
- Save a reviewA member key writes corrected fields and classification back, and can read a PDF again.
- Start a collectionA member key syncs one connected source or all of them, and reads their status.
- Two access levelsA viewer key reads and downloads; a member key also writes. Both are scoped to one workspace.
- Assistants over MCPClaude Code, Claude Desktop and any MCP client work with the same records through one HTTP endpoint.
The endpoints
Send the key as a bearer token. Answers are JSON; errors carry a message and a code.
| Method | Path | What it returns |
|---|---|---|
| GET | /api/me | The workspace, your key's role and how you authenticated. |
| GET | /api/invoices | Invoices, newest first, with cursor paging. |
| GET | /api/invoices/{id} | One invoice with its fields and classification. |
| PATCH | /api/invoices/{id} | Save reviewed fields. Member keys. |
| GET | /api/invoices/{id}/file | The original PDF. |
| GET | /api/invoices/download | One zip of PDFs with a CSV index: a folder, a month range or picked ids, at most 500. |
| POST | /api/invoices/{id}/read | Read the PDF again. Member keys. |
| PATCH | /api/invoices/{id}/classification | Department, project and category overrides. Member keys. |
| POST | /api/invoices/sync | Collect from every connected source. Member keys. |
| GET | /api/suppliers | Suppliers and their defaults. |
| PATCH | /api/suppliers/{id} | Edit a supplier. Member keys. |
| GET | /api/reports | Monthly totals for a period and dimension. |
| GET | /api/connections | The connected sources and their status. |
The exact parameters, filters and paging are in the docs.
Connect an assistant
The MCP endpoint is one HTTP address with your key as a header, so Claude Code, Claude Desktop and other MCP clients can answer questions about your invoices, open a PDF and start a collection.
- list_invoices
- get_invoice
- get_invoice_file
- list_suppliers
- get_report
- list_connections
- sync_connection
claude mcp add --transport http kvitr https://www.kvitr.com/api/mcp \ --header "Authorization: Bearer kv_…"
Read-only tools work with a viewer key; collecting needs a member key. The docs cover Claude Desktop, .mcp.json and clients that only start local commands.
Keys and limits
- 120 requests a minute per key
- Above that the API answers 429 with a Retry-After header. Lists return up to 100 items with a cursor for the next page.
- Up to 20 active keys
- The owner creates and revokes them in Settings. A revoked key stops working immediately.
- Shown once, stored as a hash
- kvitr keeps a hash of the key and its first characters, never the key itself. Lose it and you make a new one.