# BennyBooks API

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

BennyBooks exposes a versioned REST API at /api/v1. Agents authenticate with org-scoped bearer tokens and operate on the same ledger data as humans — transactions, notes, and receipts.

> **MCP without a custom server.** Connect via AnythingMCP using our curated OpenAPI tool set (see MCP tool design), or call REST directly. Machine-readable map: /llms.txt (no login).

## What you can do

| Capability | Endpoints | Scope |
| --- | --- | --- |
| Browse & filter transactions | GET /transactions | read |
| Read full context (notes + receipts) | GET /transactions/:id | read |
| Discover valid categories | GET /categories | read |
| Load ontology (JSON-LD) | GET /ontology.jsonld | public |
| Check connector sync health | GET /connectors | read |
| Financial summary & workload | GET /dashboard/summary | read |
| Propose categorizations | POST /proposals/categorization | propose-write |
| Propose receipt links | POST /proposals/receipt-link | propose-write |
| Attach notes | POST or PUT /notes | propose-write |

## Design principles

- Structured over clever — explicit fields, stable UUIDs, category codes, predictable enums
- Read freely, write carefully — proposals land in an approval queue
- Explainability — categorizations include confidence, reason, and optional evidence (shown in Approvals and Log)
- Tenant isolation — every row is scoped to the token's organization
- Ontology — stable meaning via JSON-LD; see Reference → Ontology

## Base URL

```text
https://bennybooks.com/api/v1
```