API v1 · agent-friendly docs
BennyBooks API
A structured REST API for AI agents and integrations. Read the ledger freely; write through an approval queue.
Agents: use markdown, not HTML
Fetch /developers/llms.txt first, or send Accept: text/markdown to any docs URL. WebMCP tools on this page search docs and list discovery URLs — they do not read the ledger.
For AI agents
Do not scrape this HTML. Fetch /developers/llms.txt (docs index) or /llms.txt (site map), then follow .md links. Send Accept: text/markdown on any /developers URL to get the twin. Auth: /auth.md · Skill: /skill.md · OpenAPI: /openapi.json.
BennyBooks exposes Streamable HTTP MCP at /api/mcp and a versioned REST API at /api/v1. Agents authenticate with org-scoped bearer tokens (bb_live_…) and operate on the same ledger data as humans — transactions, notes, and receipts. Writes create pending proposals until a human approves them.
MCP
Prefer Streamable HTTP MCP at /api/mcp (Bearer bb_live_). You can also import /openapi.json into AnythingMCP or call REST. See Guides → Connect Streamable HTTP MCP and MCP tool design.
Start here
- GET /developers/llms.txt — curated docs index (this section)
- GET /skill.md — auth, curated tools, workflows
- GET /auth.md — how bb_live_ tokens are issued
- GET /openapi.json — machine-readable contract + x-mcp hints (public)
- GET /api/v1/ontology.jsonld — category codes and counterparties (public)
- Optional: GET /api/v1/ontology.ttl or SPARQL /api/v1/ontology/sparql (static graph only)
- Create a token in Settings → MCP & agents, then connect via /api/mcp or GET /api/v1/transactions?limit=50
curl -sS "https://bennybooks.com/developers" \
-H "Accept: text/markdown"What you can do
| Capability | Endpoint | Scope |
|---|---|---|
| Browse & filter transactions | GET /api/v1/transactions | read |
| Read full context (notes + receipts) | GET /api/v1/transactions/:id | read |
| Discover valid categories | GET /api/v1/categories | read |
| Load ontology (JSON-LD) | GET /api/v1/ontology.jsonld | public |
| Load ontology (Turtle) | GET /api/v1/ontology.ttl | public |
| SPARQL ontology (static) | GET|POST /api/v1/ontology/sparql | public |
| Check connector sync health | GET /api/v1/connectors | read |
| Financial summary & workload | GET /api/v1/dashboard/summary | read |
| Propose categorizations | POST /api/v1/proposals/categorization | propose-write |
| Propose receipt links | POST /api/v1/proposals/receipt-link | propose-write |
| Attach notes | POST /api/v1/notes | propose-write |
Hard rules
- Prefer stable categoryCode (e.g. 5100) over display names
- Never auto-post journal entries — propose via POST /api/v1/proposals/journal-entry
- Include confidence, reason, and optional evidence[] on categorizations (humans see them in Approvals and Log)
- Every ledger row is scoped to the token's organization — never send org_id
- Do not scrape /ledger or /log — use REST for data; Log has no agent read API in v1
Design principles
- Structured over clever — explicit fields, stable UUIDs, category codes, predictable enums
- Read freely, write carefully — proposals land in an approval queue
- Explainability — confidence, reason, and evidence for human review
- Tenant isolation — every row is scoped to the token's organization
- Ontology — stable meaning via JSON-LD; see Reference → Ontology
WebMCP (browser agents)
On /developers, browser agents that support WebMCP can call in-page tools (list_discovery_urls, search_docs, list_doc_pages, open_path). Tools are discovery and navigation only — not ledger reads. Chrome origin trial / chrome://flags/#enable-webmcp-testing. Details: Guides → Connect as an AI agent.
Base URL
https://bennybooks.com/api/v1Authorization: Bearer bb_live_<token>