API v1 · agent-friendly docs

Proposals

Approval-gated agent write operations.

Proposals are drafts. Humans approve or reject them in Ledger → Approvals. Approved proposals mutate the ledger. Propose and review events are audit-logged in Log (/log) — there is no agent API to read Log in v1.

GET/api/v1/proposalsread

list_pending_proposals

Pending agent proposals awaiting human approval.

Response

json
{
  "data": [ { "id": "…", "type": "categorization", "status": "pending", … } ],
  "meta": { "count": 2 }
}
GET/api/v1/proposals/{id}read

get_proposal

Single proposal by ID.

Parameters

NameTypeDescription
id*uuidProposal ID

Response

json
{ "data": { "id": "…", "type": "categorization", "status": "pending", … } }
POST/api/v1/imports/revolutpropose-write

import_revolut_csv

Ingest a Revolut statement CSV into the ledger. Pass full CSV text in `csv`. Posts completed rows immediately (bank feed ingest). Idempotent on external ids.

Request body

json
{
  "csv": "Type,Product,Started Date,Completed Date,Description,Amount,Fee,Currency,State,Balance\nCard payment,Current,2024-01-15 10:00:00,2024-01-15 10:00:00,Coffee,-4.50,0.00,EUR,COMPLETED,100.00\n"
}

Response

json
{ "data": { "inserted": 12, "skipped": 1, "parsed": 13, "format": "personal", "source": "revolut" } }
POST/api/v1/proposals/categorizationpropose-write

propose_categorization

Suggest a category for a transaction. Prefer categoryCode. Creates a pending proposal — the ledger is not updated until a human approves in Ledger → Approvals.

Request body

json
{
  "transactionId": "uuid",
  "categoryCode": "5300",
  "confidence": 0.91,
  "reason": "Description matches counterparty AWS",
  "evidence": [
    { "type": "counterparty_match", "value": "aws" }
  ]
}

Response

json
{ "data": { "id": "…", "status": "pending", "type": "categorization", … } }
POST/api/v1/proposals/journal-entrypropose-write

propose_journal_entry

Propose a new manual ledger entry. Creates a pending proposal — a transaction is created only after human approval.

Request body

json
{
  "date": "2026-08-28",
  "description": "Office supplies",
  "amount": -42.50,
  "currency": "EUR",
  "categoryCode": "5200",
  "source": "manual_csv",
  "confidence": 0.88,
  "reason": "One-off office purchase"
}

Response

json
{ "data": { "id": "…", "status": "pending", "type": "journal_entry", … } }

import_revolut_csv posts bank rows immediately (ingest). Other write endpoints create pending proposals until approved.

typeOn approval
categorizationSets canonical category + agent metadata; status → matched
journal_entryCreates new transaction (status matched)
receipt_linkLinks receipt to transaction
noteCreates note on transaction