API v1 · agent-friendly docs

Authentication

Bearer tokens, scopes, and security model.

Protected routes under /api/mcp (Streamable HTTP MCP) and /api/v1 require a valid BennyBooks API token in the Authorization header. Public discovery (OpenAPI, ontology, /llms.txt, /developers) needs no token.

http
Authorization: Bearer bb_live_<token>

Preferred agent path

Point your MCP host at /api/mcp with this bearer header. Setup: Guides → Connect Streamable HTTP MCP (or npx @bennybooks/cli agent setup).

Token format

  • Prefix: bb_live_
  • Stored as SHA-256 hash — plaintext shown only once at creation
  • Org-scoped — tied to the Clerk organization active when created
  • Revocable from Settings → MCP & agents
  • Same token works for /api/mcp, REST /api/v1, and OpenAPI bridges

Scopes

ScopeAccess
readMCP read tools + authenticated GET under /api/v1
propose-writeMCP write tools + POST/PUT proposal endpoints (includes read)

Public endpoints

GET /openapi.json, GET /api/v1/ontology.jsonld, GET /api/v1/ontology.ttl, GET /api/v1/ontology/context.jsonld, GET|POST /api/v1/ontology/sparql, /llms.txt, /agents.txt, /skill.md, /auth.md, and /developers are public (no token). /api/mcp itself requires a bearer token.

Pro plan

When billing enforcement is enabled (BILLING_ENFORCEMENT=true), propose-write tokens require a Pro subscription.