API v1

Quickstart

Make your first API call in under two minutes.

1. Create a token

In BennyBooks, go to Settings → MCP access and create a token. Choose read for queries or propose-write for agent actions. Copy the bb_live_… value — it is shown only once.

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

See the Connect as an AI agent guide for llms.txt, markdown docs, and WebMCP. See Connect with AnythingMCP to turn these endpoints into MCP tools for Cursor or Claude Desktop.