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.
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
| Scope | Access |
|---|---|
| read | MCP read tools + authenticated GET under /api/v1 |
| propose-write | MCP 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.