---
title: BennyBooks API
description: A structured REST API for AI agents and integrations. Read the ledger freely; write through an approval queue.
canonical: https://bennybooks.com/developers
markdown: https://bennybooks.com/developers.md
---
# BennyBooks API

A structured REST API for AI agents and integrations. Read the ledger freely; write through an approval queue.

> **Documentation index.** Fetch [https://bennybooks.com/developers/llms.txt](https://bennybooks.com/developers/llms.txt) before browsing further. Prefer markdown (this file or `Accept: text/markdown`). Site-wide map: [https://bennybooks.com/llms.txt](https://bennybooks.com/llms.txt).

> **For AI agents.** Do not scrape this HTML. Fetch https://bennybooks.com/developers/llms.txt (docs index) or https://bennybooks.com/llms.txt (site map), then follow .md links. Send Accept: text/markdown on any https://bennybooks.com/developers URL to get the twin. Auth: https://bennybooks.com/auth.md · Skill: https://bennybooks.com/skill.md · OpenAPI: https://bennybooks.com/openapi.json.

BennyBooks exposes Streamable HTTP MCP at /api/mcp and a versioned REST API at https://bennybooks.com/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 https://bennybooks.com/openapi.json into AnythingMCP or call REST. See Guides → Connect Streamable HTTP MCP and MCP tool design.

## Start here

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

```bash Prefer markdown
curl -sS "https://bennybooks.com/developers" \
  -H "Accept: text/markdown"
```

## What you can do

| Capability | Endpoint | Scope |
| --- | --- | --- |
| Browse & filter transactions | GET https://bennybooks.com/api/v1/transactions | read |
| Read full context (notes + receipts) | GET https://bennybooks.com/api/v1/transactions/:id | read |
| Discover valid categories | GET https://bennybooks.com/api/v1/categories | read |
| Load ontology (JSON-LD) | GET https://bennybooks.com/api/v1/ontology.jsonld | public |
| Load ontology (Turtle) | GET https://bennybooks.com/api/v1/ontology.ttl | public |
| SPARQL ontology (static) | GET|POST https://bennybooks.com/api/v1/ontology/sparql | public |
| Check connector sync health | GET https://bennybooks.com/api/v1/connectors | read |
| Financial summary & workload | GET https://bennybooks.com/api/v1/dashboard/summary | read |
| Propose categorizations | POST https://bennybooks.com/api/v1/proposals/categorization | propose-write |
| Propose receipt links | POST https://bennybooks.com/api/v1/proposals/receipt-link | propose-write |
| Attach notes | POST https://bennybooks.com/api/v1/notes | propose-write |

## Hard rules

- Prefer stable categoryCode (e.g. 5100) over display names
- Never auto-post journal entries — propose via POST https://bennybooks.com/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 https://bennybooks.com/ledger or https://bennybooks.com/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 https://bennybooks.com/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
```

```http Auth header
Authorization: Bearer bb_live_<token>
```

---

## Machine-readable

- HTML: https://bennybooks.com/developers
- Markdown: https://bennybooks.com/developers.md
- Docs index: https://bennybooks.com/developers/llms.txt
- OpenAPI: https://bennybooks.com/openapi.json
- Skill: https://bennybooks.com/skill.md
- Auth: https://bennybooks.com/auth.md

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "BennyBooks API",
  "description": "A structured REST API for AI agents and integrations. Read the ledger freely; write through an approval queue.",
  "url": "https://bennybooks.com/developers",
  "inLanguage": "en",
  "encodingFormat": [
    "text/html",
    "text/markdown"
  ],
  "isAccessibleForFree": true,
  "publisher": {
    "@type": "Organization",
    "name": "BennyBooks",
    "url": "https://bennybooks.com",
    "logo": {
      "@type": "ImageObject",
      "url": "https://bennybooks.com/apple-icon.png"
    }
  },
  "mainEntityOfPage": "https://bennybooks.com/developers",
  "image": "https://bennybooks.com/opengraph-image",
  "workExample": {
    "@type": "CreativeWork",
    "url": "https://bennybooks.com/developers.md",
    "encodingFormat": "text/markdown",
    "name": "BennyBooks API (Markdown)"
  },
  "about": {
    "@type": "WebAPI",
    "name": "BennyBooks Agent API",
    "url": "https://bennybooks.com/api/v1",
    "documentation": "https://bennybooks.com/developers"
  }
}
```
