API and MCP access

What an API key can do

An API key lets a program or an AI assistant work with one workspace without signing in. It reads invoices with their fields and review status, downloads original PDFs, lists suppliers and their defaults, and builds the same cost reports as Reports. A member key can also start a collection and save invoice fields.

The workspace owner creates keys under Settings → API access: give the key a name and an access level, then copy it. The key is shown once. If it is lost, revoke it and create a new one; anything using a revoked key stops working immediately. A workspace can have up to 20 active keys.

Viewer and member keys

Viewer

Reads invoices, suppliers and reports, and downloads PDFs. Cannot change anything. Use it for an accountant’s tools or a read-only assistant.

Member

Everything a viewer key can do, plus starting collections, reading PDFs and saving invoice fields and classification. Keys never manage members, company choices, sources or account settings; those stay with signed-in people.

REST endpoints

Send the key as a bearer token. Every request counts towards a limit of 120 requests per minute per key; above that the API answers 429 with a Retry-After header. Errors are JSON with an error message and a code.

curl https://www.kvitr.com/api/invoices?limit=20 \
  -H "Authorization: Bearer kv_…"

• GET /api/me — the workspace, your key’s role and how you authenticated.
• GET /api/invoices — newest invoices first; integrationId, limit and cursor filters.
• GET /api/invoices/{id} — one invoice with fields, classification and where each read value came from. PATCH saves reviewed fields (member).
• GET /api/invoices/{id}/file — the original PDF.
• POST /api/invoices/{id}/read — read the PDF again (member); PATCH /api/invoices/{id}/classification — department, project and category overrides (member).
• POST /api/invoices/sync — collect from every connected source (member).
• GET /api/suppliers, GET /api/suppliers/{id} — suppliers and defaults; PATCH edits a supplier (member).
• GET /api/reports?period=this-year&dimension=type — monthly totals; period is month, last-month, 3-months, this-year, 12-months or custom with from and to months.
• GET /api/connections — the connected sources and their status.

Paging through lists

Lists return up to 100 items (limit, default 50) and a nextCursor. Pass it back as cursor to get the next, older page; when nextCursor is null you have reached the end. Cursors only move through the list; they never change which workspace you see.

Connect Claude through MCP

The MCP endpoint is https://www.kvitr.com/api/mcp. It offers the tools list_invoices, get_invoice, get_invoice_file, list_suppliers, get_report, list_connections and sync_connection (member keys only; it takes a source id from list_connections), each bounded like the REST endpoints. Send one request at a time: JSON-RPC batches are refused. In Claude Code, add it with your key:

claude mcp add --transport http kvitr https://www.kvitr.com/api/mcp \
  --header "Authorization: Bearer kv_…"

The same server as JSON, for a project’s .mcp.json or any client that accepts HTTP servers with headers:

{
  "mcpServers": {
    "kvitr": {
      "type": "http",
      "url": "https://www.kvitr.com/api/mcp",
      "headers": { "Authorization": "Bearer kv_…" }
    }
  }
}

In Claude Desktop and other MCP clients, add the URL and the same Authorization header. A client that only starts local commands can bridge with npx mcp-remote https://www.kvitr.com/api/mcp --header "Authorization: Bearer kv_…". PDFs up to 4 MB are returned directly to the assistant; larger ones are downloaded through the REST endpoint.

Keys and your data

kvitr stores only a hash of each key, together with its first characters so you can recognise it, its name (encrypted) and when it was last used. Nobody, including kvitr, can read a key back. A key acts as a member or viewer of your workspace, so treat it like a password: keep it in a secret store, give each tool its own key and revoke keys you no longer use.

The same rules as in Privacy and security apply. Stored PDFs and invoice details stay encrypted; the server decrypts them to answer an authorized request, whether it comes from a signed-in person or a key. What an assistant receives through MCP is then held by that assistant.