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
curl -sS "https://bennybooks.com/developers/guides/agents" \
  -H "Accept: text/markdown"

Discovery URLs

URLWhat it is
/llms.txtSite-wide curated markdown map (llmstxt.org)
/developers/llms.txtDocs index for this /developers tree
/llms-full.txtFull docs corpus for RAG
/index.mdProduct overview in markdown
/auth.mdAgent authentication (bb_live_ tokens)
/skill.mdAgent playbook: auth, curated tools, workflows
/developers/guides/audit-log.mdHow writes appear in Log for humans
/agents.txtCapability announcement (skills + WebMCP pages)
/agents.jsonStructured companion to agents.txt
/.well-known/api-catalogRFC 9727 API catalog (OpenAPI + ontology)
/.well-known/ard.jsonARD manifest (agentic resource discovery)
/.well-known/agent-skills/index.jsonAgent Skills index with digests
/.well-known/mcp/server-card.jsonMCP Server Card (Streamable HTTP at /api/mcp)
/api/mcpStreamable HTTP MCP endpoint (Bearer bb_live_)
/.well-known/oauth-protected-resourceRFC 9728 protected resource metadata
/openapi.jsonOpenAPI 3 spec with x-mcp annotations (public)
/api/v1/ontology.jsonldJSON-LD ontology (public)
/api/v1/ontology.ttlTurtle ontology (public)
/api/v1/ontology/sparqlSPARQL over static ontology (public, query-only)

Call the API

http
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.

ToolWherePurpose
list_discovery_urlsall WebMCP pagesllms.txt, OpenAPI, skill, auth, docs
describe_current_pageall WebMCP pagesWhat an agent should do here
open_pathall WebMCP pagesSame-origin navigation
search_docs/developersFind docs by title; returns .md URLs
list_doc_pages/developersFull docs tree with HTML + markdown
get_docs_index/developersPointer 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.