API v1 · agent-friendly docs
Connect as an AI agent
Discovery files, markdown docs, OpenAPI, WebMCP, and how to call the ledger API.
Documentation index
Start with GET /developers/llms.txt (this section) or GET /llms.txt (site-wide). Follow markdown links — do not scrape HTML.
Prefer Streamable HTTP MCP at /api/mcp with a bb_live_ token (see Connect Streamable HTTP MCP). Use @bennybooks/cli for agent setup and shell/CI (see CLI for agents & shell). OpenAPI + AnythingMCP and direct REST remain supported. Use the curated tool set described in MCP tool design.
Markdown for agents
- Every HTML docs page has a .md twin (e.g. /developers/quickstart.md)
- rel=alternate Link header points at the twin; describedby → /llms.txt and /developers/llms.txt
- Send Accept: text/markdown (without preferring text/html) to receive markdown with YAML frontmatter
- Responses include X-Markdown-Tokens for rough context budgeting
- Content-Signal: search=yes, ai-input=yes, ai-train=yes on public agent surfaces
curl -sS "https://bennybooks.com/developers/guides/agents" \
-H "Accept: text/markdown"Discovery URLs
| URL | What it is |
|---|---|
| /llms.txt | Site-wide curated markdown map (llmstxt.org) |
| /developers/llms.txt | Docs index for this /developers tree |
| /llms-full.txt | Full docs corpus for RAG |
| /index.md | Product overview in markdown |
| /auth.md | Agent authentication (bb_live_ tokens) |
| /skill.md | Agent playbook: auth, curated tools, workflows |
| /developers/guides/audit-log.md | How writes appear in Log for humans |
| /agents.txt | Capability announcement (skills + WebMCP pages) |
| /agents.json | Structured companion to agents.txt |
| /.well-known/api-catalog | RFC 9727 API catalog (OpenAPI + ontology) |
| /.well-known/ard.json | ARD manifest (agentic resource discovery) |
| /.well-known/agent-skills/index.json | Agent Skills index with digests |
| /.well-known/mcp/server-card.json | MCP Server Card (Streamable HTTP at /api/mcp) |
| /api/mcp | Streamable HTTP MCP endpoint (Bearer bb_live_) |
| /.well-known/oauth-protected-resource | RFC 9728 protected resource metadata |
| /openapi.json | OpenAPI 3 spec with x-mcp annotations (public) |
| /api/v1/ontology.jsonld | JSON-LD ontology (public) |
| /api/v1/ontology.ttl | Turtle ontology (public) |
| /api/v1/ontology/sparql | SPARQL over static ontology (public, query-only) |
Call the API
Authorization: Bearer bb_live_<token>- Create a token in Settings → MCP & agents (see /auth.md)
- read lists ledger data; propose-write creates approval-queue items (audit-logged in Log)
- Prefer categoryCode (5100) over display names
- Use limit≤50 on list calls
- Never auto-post journal entries — POST /api/v1/proposals/journal-entry
- Write clear reason/confidence/evidence — humans see them in Approvals and Log
WebMCP
Browser agents that support WebMCP can call in-page tools on /, /developers, /dashboard, /ledger, and /log. Tools are read-only discovery and same-origin navigation. They do not return ledger or audit rows — use the REST API for data; do not scrape Log.
| Tool | Where | Purpose |
|---|---|---|
| list_discovery_urls | all WebMCP pages | llms.txt, OpenAPI, skill, auth, docs |
| describe_current_page | all WebMCP pages | What an agent should do here |
| open_path | all WebMCP pages | Same-origin navigation |
| search_docs | /developers | Find docs by title; returns .md URLs |
| list_doc_pages | /developers | Full docs tree with HTML + markdown |
| get_docs_index | /developers | Pointer to /developers/llms.txt + start steps |
Agent readiness (isitagentready.com)
Public docs set Content-Signal (search/ai-input/ai-train), AI bot rules in robots.txt, Markdown Accept negotiation, auth.md, OAuth protected-resource metadata, MCP Server Card (Streamable HTTP at /api/mcp), Agent Skills index, ARD, and WebMCP. We do not publish an A2A Agent Card, Web Bot Auth signing keys, or agentic commerce protocols. DNS-AID records are configured at the DNS provider — see docs/DEPLOY.md.
WebMCP is a Chrome origin trial (149–156) via document.modelContext.registerTool. Verified in Chrome 152 with chrome://flags/#enable-webmcp-testing (or --enable-features=WebMCPTesting). Cursor's embedded browser does not ship it — tools no-op when modelContext is missing. This page shows live registration status when the API is present. Permissions-Policy: tools=(self) allows same-origin WebMCP.