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

  1. GET /developers/llms.txt — curated docs index (this section)
  2. GET /skill.md — auth, curated tools, workflows
  3. GET /auth.md — how bb_live_ tokens are issued
  4. GET /openapi.json — machine-readable contract + x-mcp hints (public)
  5. GET /api/v1/ontology.jsonld — category codes and counterparties (public)
  6. Optional: GET /api/v1/ontology.ttl or SPARQL /api/v1/ontology/sparql (static graph only)
  7. Create a token in Settings → MCP & agents, then connect via /api/mcp or GET /api/v1/transactions?limit=50
Prefer markdown
curl -sS "https://bennybooks.com/developers" \
  -H "Accept: text/markdown"

What you can do

CapabilityEndpointScope
Browse & filter transactionsGET /api/v1/transactionsread
Read full context (notes + receipts)GET /api/v1/transactions/:idread
Discover valid categoriesGET /api/v1/categoriesread
Load ontology (JSON-LD)GET /api/v1/ontology.jsonldpublic
Load ontology (Turtle)GET /api/v1/ontology.ttlpublic
SPARQL ontology (static)GET|POST /api/v1/ontology/sparqlpublic
Check connector sync healthGET /api/v1/connectorsread
Financial summary & workloadGET /api/v1/dashboard/summaryread
Propose categorizationsPOST /api/v1/proposals/categorizationpropose-write
Propose receipt linksPOST /api/v1/proposals/receipt-linkpropose-write
Attach notesPOST /api/v1/notespropose-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

text
https://bennybooks.com/api/v1
Auth header
Authorization: Bearer bb_live_<token>