# BennyBooks Developers

> REST API v1 for AI agents. Read the ledger; write through proposals. Prefer markdown over HTML.

This file is the **documentation index** for `/developers`. Site-wide map: [https://bennybooks.com/llms.txt](https://bennybooks.com/llms.txt).

## How to consume these docs

1. Prefer `.md` twins (e.g. [https://bennybooks.com/developers/quickstart.md](https://bennybooks.com/developers/quickstart.md)) or `Accept: text/markdown` on the HTML URL
2. Do not scrape HTML navigation, sidebars, or scripts
3. Follow only the links below when you need detail
4. Authenticate with `Authorization: Bearer bb_live_<token>` — details in [https://bennybooks.com/auth.md](https://bennybooks.com/auth.md)

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

## Start here

- [Agent skill](https://bennybooks.com/skill.md): Auth, curated MCP tools, workflows
- [Auth](https://bennybooks.com/auth.md): How `bb_live_` tokens are issued
- [Quickstart](https://bennybooks.com/developers/quickstart.md): First API calls
- [Connect as an AI agent](https://bennybooks.com/developers/guides/agents.md): Discovery, markdown, WebMCP
- [MCP tool design](https://bennybooks.com/developers/guides/mcp-design.md): Curated ~12 tools
- [OpenAPI](https://bennybooks.com/openapi.json): REST contract + `x-mcp` (public)
- [Ontology JSON-LD](https://bennybooks.com/api/v1/ontology.jsonld): Category codes (public)
- [Ontology Turtle](https://bennybooks.com/api/v1/ontology.ttl)
- [Ontology SPARQL](https://bennybooks.com/api/v1/ontology/sparql): Static graph only

## Rules

- Prefer `categoryCode` over display names
- Writes create proposals until a human approves — never auto-post journals
- Default list `limit=50`
- Prefer Streamable HTTP MCP at `/api/mcp` — CLI for shell/CI; OpenAPI bridge or REST also work
- Do not scrape `/ledger` or `/log`

## Docs

- [Introduction](https://bennybooks.com/developers.md): A structured REST API for AI agents and integrations. Read the ledger freely; write through an approval queue.
- [Quickstart](https://bennybooks.com/developers/quickstart.md): Make your first API call in under two minutes.
- [Authentication](https://bennybooks.com/developers/authentication.md): Bearer tokens, scopes, and security model.
- [Errors & responses](https://bennybooks.com/developers/errors.md): Response envelopes, error codes, and HTTP status mapping.
- [Connect Streamable HTTP MCP](https://bennybooks.com/developers/guides/mcp-server.md): Point Cursor, Claude, or any MCP host at BennyBooks /api/mcp with a bb_live_ bearer token.
- [CLI for agents & shell](https://bennybooks.com/developers/guides/cli.md): Use @bennybooks/cli to wire Streamable HTTP MCP and run curated ledger commands from the terminal.
- [Connect with AnythingMCP](https://bennybooks.com/developers/guides/anythingmcp.md): Optional OpenAPI bridge: turn the curated BennyBooks OpenAPI surface into MCP tools when you cannot use native /api/mcp.
- [MCP tool design](https://bennybooks.com/developers/guides/mcp-design.md): How BennyBooks shapes MCP tools for clean, token-efficient agent use.
- [Connect as an AI agent](https://bennybooks.com/developers/guides/agents.md): Discovery files, markdown docs, OpenAPI, WebMCP, and how to call the ledger API.
- [Audit Log](https://bennybooks.com/developers/guides/audit-log.md): How agent writes and human approve/reject decisions are recorded for review in Log.
- [Categorize transactions](https://bennybooks.com/developers/guides/categorize.md): Recommended agent workflow using stable category codes, counterparties, and evidence.
- [Investigate a transaction](https://bennybooks.com/developers/guides/investigate.md): Gather full context before proposing changes.
- [Month-end checklist](https://bennybooks.com/developers/guides/month-end.md): Flag anomalies and workload items using dashboard summary.
- [Overview](https://bennybooks.com/developers/api.md): All v1 endpoints at a glance.
- [Transactions](https://bennybooks.com/developers/api/transactions.md): List, filter, and retrieve ledger transactions with related data.
- [Categories](https://bennybooks.com/developers/api/categories.md): Chart of accounts for categorization proposals.
- [Connectors](https://bennybooks.com/developers/api/connectors.md): Data source sync status and lineage.
- [Dashboard](https://bennybooks.com/developers/api/dashboard.md): Financial aggregates and agent workload indicators.
- [Proposals](https://bennybooks.com/developers/api/proposals.md): Approval-gated agent write operations.
- [Notes](https://bennybooks.com/developers/api/notes.md): Free-text context attached to transactions.
- [Receipts](https://bennybooks.com/developers/api/receipts.md): Search and retrieve receipt metadata.
- [OpenAPI spec](https://bennybooks.com/developers/reference/openapi.md): Machine-readable API contract with agent instructions and x-mcp annotations.
- [Data model](https://bennybooks.com/developers/reference/data-model.md): Core ledger types and relationships.
- [Ontology](https://bennybooks.com/developers/reference/ontology.md): Semantic model, stable category codes, counterparties, and agent categorization rules.

## Specs & discovery

- [OpenAPI](https://bennybooks.com/openapi.json)
- [Ontology](https://bennybooks.com/api/v1/ontology.jsonld)
- [Ontology Turtle](https://bennybooks.com/api/v1/ontology.ttl)
- [Ontology SPARQL](https://bennybooks.com/api/v1/ontology/sparql)
- [Agent skill](https://bennybooks.com/skill.md)
- [Auth](https://bennybooks.com/auth.md)
- [CLI](https://bennybooks.com/developers/guides/cli.md)
- [agents.txt](https://bennybooks.com/agents.txt)
- [agents.json](https://bennybooks.com/agents.json)
- [API catalog](https://bennybooks.com/.well-known/api-catalog)
- [ARD manifest](https://bennybooks.com/.well-known/ard.json)
- [Agent Skills index](https://bennybooks.com/.well-known/agent-skills/index.json)
- [MCP server card](https://bennybooks.com/.well-known/mcp/server-card.json)