Sfoglia il riferimento
Documentazione per sviluppatori
L'API di vokse
In vokse tutto è a una chiamata API di distanza. L'app web, i client esterni e la nostra IA usano tutti la stessa API REST, e puoi usarla anche tu. Autenticati con una chiave Bearer, dalle esattamente gli scope che ti servono e integri in pochi minuti.
Autenticazione
Ogni richiesta porta un token Bearer nell'header Authorization. Crea una chiave API in Impostazioni → Chiavi API, scegli i suoi scope e puoi partire.
URL di base
https://api.vokse.aiLa prima richiesta
bash
curl -H "Authorization: Bearer vokse_sk_…" \ https://api.vokse.ai/households/current/accountsRisorse
188 endpoint in 28 risorse. Scegli una risorsa per vedere ogni operazione, il suo scope, i parametri e un esempio da copiare e incollare.
Conti14 endpoint
Assistente IA12 endpoint
- 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
Analisi IA2 endpoint
Collegamenti bancari15 endpoint
- 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
Budget9 endpoint
Categorie7 endpoint
Gruppi di categorie4 endpoint
Tassi di cambio2 endpoint
Previsioni1 endpoint
Obiettivi4 endpoint
Cronologia (annulla / ripeti)3 endpoint
- 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)
Nuclei familiari2 endpoint
Membri1 endpoint
Notifiche6 endpoint
Beneficiari13 endpoint
Scontrini (OCR)16 endpoint
- 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
Ricorrenze13 endpoint
Report9 endpoint
- 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
Regole8 endpoint
Ricerca1 endpoint
Tag4 endpoint
Contrassegni delle transazioni2 endpoint
Transazioni20 endpoint
Importazione transazioni1 endpoint
Utenti3 endpoint
Voce6 endpoint
Guide
Guide scritte a mano per i temi trasversali: autenticazione, errori, paginazione, idempotenza e webhook.
AutenticazioneL'API di vokse autentica ogni richiesta con una chiave API Bearer. Le chiavi hanno scope, si revocano e non scadono mai in silenzio. Decidi tu esattamente cosa può toccare un'integrazione.FamiglieLa famiglia è il tenant: conti, movimenti, budget, categorie, regole e chiavi appartengono tutti a una sola. Anche la tua chiave: ecco cosa ti permette di fare, e cosa no.ErroriOgni errore dell'API di vokse arriva in un formato JSON coerente, con un codice stabile leggibile da una macchina, un messaggio per le persone e dettagli strutturati facoltativi. Programma sul codice, mostra il messaggio.PaginazioneGli endpoint di lista paginano con un cursore opaco. Non calcoli mai un offset: segui nextCursor finché non diventa null. I cursori restano stabili anche con scritture in corso, quindi non salti né rileggi mai una riga.IdempotenzaLe richieste che modificano dati diventano sicure da ripetere se mandi un'Idempotency-Key. Se una richiesta si perde per un timeout, ripeterla con la stessa chiave restituisce il risultato originale invece di creare un duplicato.Limiti di frequenzaOgni richiesta viene contata su una finestra fissa di 60 secondi. Quale contatore si applica dipende da come ti autentichi: le chiavi API hanno il budget più alto, le sessioni autenticate uno generoso, il traffico anonimo uno piccolo. Quando il budget è finito, l'API risponde 429 e ti dice quanto aspettare.Ricevere i webhookI webhook ti mandano gli eventi in tempo reale, senza doverli chiedere di continuo. Iscrivi un URL, scegli gli eventi che ti interessano e verifica ogni consegna con la sua firma HMAC.Cronologia, annulla e ripeti nell'APIvokse tiene un registro delle modifiche per nucleo: una riga per ogni modifica atomica con il payload esatto per invertirla, chi l’ha fatta e quando. L’API espone le righe prodotte da una scrittura, elenca la cronologia con gli autori e inverte qualsiasi modifica registrata, con precisione, da qualsiasi client.MCPvokse ha un server MCP remoto: gli stessi strumenti verificati usati dall'assistente e dall'app, esposti tramite il Model Context Protocol. Un URL, OAuth standard, nessun binario e nessuna chiave API.
Documento OpenAPI
Preferisci un'interfaccia interattiva? Il documento OpenAPI completo è pubblicato in tempo reale, con Scalar.
Apri il riferimento OpenAPI