API v1 · agent-friendly docs

Quickstart

Make your first API call in under two minutes.

1. Create a token

In BennyBooks, go to Settings → MCP & agents and create a token. Choose read for queries or propose-write for agent actions. Copy the bb_live_… value — it is shown only once. Paste MCP config or run npx @bennybooks/cli agent setup.

2. List transactions

curl
curl -s "https://bennybooks.com/api/v1/transactions?status=uncategorized&limit=5" \
  -H "Authorization: Bearer bb_live_YOUR_TOKEN" | jq

3. Propose a categorization

Requires a propose-write token. The change stays pending until a human approves in Ledger → Approvals. The propose action is also recorded in Log (/log).

curl
curl -s -X POST "https://bennybooks.com/api/v1/proposals/categorization" \
  -H "Authorization: Bearer bb_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "YOUR_TX_ID",
    "categoryCode": "5100",
    "confidence": 0.92,
    "reason": "Recurring SaaS charge",
    "evidence": [{ "type": "keyword", "value": "Software" }]
  }' | jq

4. Connect an agent

Prefer markdown docs: GET /developers/llms.txt or Accept: text/markdown. See Connect as an AI agent for discovery, WebMCP, and auth.md. Prefer Connect Streamable HTTP MCP; AnythingMCP remains an OpenAPI bridge option.