Browse the reference
Developer docs
The vokse API
Everything in vokse is an API call away. The web app, external clients and our AI all speak the same REST surface, and so can you. Authenticate with a Bearer key, scope it to exactly what you need, and integrate in minutes.
Authentication
Every request carries a Bearer token in the Authorization header. Mint an API key in Settings → API keys, choose its scopes, and you are ready.
Base URL
https://api.vokse.aiA first request
bash
curl -H "Authorization: Bearer vokse_sk_…" \ https://api.vokse.ai/households/current/accountsResources
188 endpoints across 28 resources. Pick a resource to see every operation, its scope, parameters and a copy-paste example.
Accounts14 endpoints
AI assistant12 endpoints
- GETList pending AI actions awaiting user confirmation. Paginated with opaque cursor.
- POSTCancel a pending destructive action.
- POSTConfirm and execute a pending assistant action.
- POSTStream a chat turn (SSE). Returns text/event-stream. 403 AI_CONSENT_REQUIRED until the ai_processing consent is granted.
- +8
AI insights2 endpoints
Bank connections15 endpoints
- GETList bank accounts in the household
- PATCHPause / resume sync for one bank account
- DELETEUnlink a bank account from its vokse account (the account and imported transactions stay; new movements stop arriving until mapped again)
- POSTMap a bank account to an existing financial_account or create a new one
- +11
Budgets9 endpoints
Categories7 endpoints
Category groups4 endpoints
Currencies2 endpoints
Exchange rates2 endpoints
Forecasts1 endpoint
Goals4 endpoints
History (undo / redo)3 endpoints
- GETChange history, newest first: every recorded change with its performer; filter by member, family, kind, time window, group or explicit ids
- POSTRedo an undone change: reverts its active reversal so the change is in force again (409 HISTORY_NOT_UNDONE when it is not undone, HISTORY_STALE when the data moved on)
- POSTUndo a recorded change: applies its exact inverse, writes the reversal to the history and marks the change undone (409 HISTORY_STALE when the data moved on, HISTORY_ALREADY_UNDONE when another client got there first)
Households2 endpoints
Notifications6 endpoints
Payees13 endpoints
Receipts (OCR)16 endpoints
- GETLine items read from receipts, newest purchase first; unit prices are also given per base unit (kg, l, unit).
- GETUnit price of a product over time (per base unit, quantity-weighted per bucket) with the merchants it was bought at.
- GETPer-product summary across receipts: purchases, total spend, quantity-weighted average / min / max / latest unit price over the base unit, where it was bought.
- GETList receipts in this household; filter by link state, extraction status, kind, day, amount, merchant, tags or free text; sort by date, amount or merchant.
- +12
Recurrences13 endpoints
Reports9 endpoints
- GETPlan vs reality: per-month assigned vs spent totals, adherence share of budgeted categories, and the biggest overruns of the range. Max 5-year range.
- GETPer-month income vs expense vs net (in base currency) over the range. Optional accountIds CSV (only these accounts). Max 5-year range.
- GETMonth-over-month spend per category (dense, zero-filled series in base currency). Optional accountIds CSV (only these accounts) and categoryIds CSV filters. Max 5-year range.
- GETIncome by source over the range (ADR 0107): unlabelled inflows plus every income category, month by month in the base currency. Optional accountIds CSV. Max 5-year range.
- +5
Rules8 endpoints
Search1 endpoint
Tags4 endpoints
Transaction flags2 endpoints
Transactions20 endpoints
Users3 endpoints
Voice6 endpoints
Guides
Hand-written walkthroughs for the cross-cutting concerns: auth, errors, pagination, idempotency and webhooks.
AuthenticationThe vokse API authenticates every request with a Bearer API key. Keys are scoped, revocable, and never expire silently. You stay in control of exactly what an integration can touch.HouseholdsA household is the tenant: accounts, transactions, budgets, categories, rules and keys all belong to exactly one. Your key belongs to one too, here is what that lets you do, and what it does not.ErrorsEvery error from the vokse API returns a consistent JSON envelope with a stable machine-readable code, a human message, and optional structured details. Build against the code, surface the message.PaginationList endpoints page with an opaque cursor. You never compute offsets. You follow nextCursor until it is null. Cursors are stable under concurrent writes, so you never skip or double-read a row.IdempotencyMutating requests can be made safe to retry by sending an Idempotency-Key. If a request is lost to a timeout, replaying it with the same key returns the original result instead of creating a duplicate.Rate limitsEvery request is counted against a fixed 60-second window. Which counter applies depends on how you authenticate: API keys get the largest budget, signed-in sessions a generous one, anonymous traffic a small one. When the budget is spent the API answers 429 and tells you how long to wait.Receiving webhooksWebhooks push events to you in real time instead of polling. Subscribe a URL, pick the events you care about, and verify each delivery with its HMAC signature.History, undo and redo in the APIvokse keeps a change ledger per household: one row per atomic change with the exact payload to revert it, who made it and when. The API exposes the rows a write produced, lists the history with its performers, and reverts any recorded change, precisely, from any client.MCPvokse ships a remote MCP server: the same audited tools the assistant and the app call, spoken over the Model Context Protocol. One URL, standard OAuth, no binaries, no API keys.
Raw OpenAPI
Prefer an interactive explorer? The full OpenAPI document is served live, rendered with Scalar.
Open the OpenAPI reference