API reference

REST endpoints.

Four primary surfaces. Auth is always a workspace-scoped bearer token. Writes accept Idempotency-Key for retry safety.

Authentication

Send your token as Authorization: Bearer bctx_live_.... Tokens are workspace-scoped: a token issued for workspace acme can only read/write nodes in acme. Cross-workspace calls return 403 with "token does not grant access to this workspace".

Rate limits

Token-bucket per (workspace, scope-class). Buckets refill continuously; denial returns 429 with a Retry-After header.

read   120 req, refill   2 req/s
write   60 req, refill   1 req/s
chat    30 req, refill 0.5 req/s
embed   10 req, refill 0.1 req/s

Defaults as of v0.1. Self-host can override per workspace.

POST /api/agents/context

The primary read endpoint for agents. Returns the top-k retrieval hits for query plus a projected node tree. Requires scope agents:read.

Request

POST /api/agents/context
Authorization: Bearer bctx_live_...
Content-Type: application/json

{
  "workspace": "acme",
  "query":     "what is blocking the embedding pipeline?",
  "k":         6,
  "fields":    ["id", "title", "kind", "status"],
  "include_counts": true
}

Response

{
  "workspace": "acme",
  "query":     "what is blocking the embedding pipeline?",
  "retrieved": [
    { "node_id": "...", "title": "...", "score": 0.82, "excerpt": "..." }
  ],
  "tree":   [ { "id": "...", "title": "...", "kind": "doc", "status": null } ],
  "counts": { "docs": 14, "tasks": 22, "decisions": 3, "bugs": 5 }
}

POST /api/agents/write

Batch up to 20 ops per call. create inserts a new node; patch partially updates one by id. Include an Idempotency-Key header — replays of the same key return the original response with Idempotent-Replay: true. Requires scope agents:write.

Request

POST /api/agents/write
Authorization: Bearer bctx_live_...
Idempotency-Key: agent-42-batch-7
Content-Type: application/json

{
  "workspace": "acme",
  "ops": [
    { "op": "create", "node": {
        "title": "ADR — switch auth provider",
        "kind": "adr",
        "parent_id": null,
        "content_md": "## Context\n..."
    } },
    { "op": "patch", "id": "node_123", "patch": { "status": "done" } }
  ]
}

Supported node kinds: folder, doc,task, decision, meeting, bug, adr, entity, skill.

POST /api/chat

Streaming chat against your workspace via the configured AI Gateway model. Retrieves citations from RAG, builds a context block, and pipes a Vercel AI SDK streamText response. Requires scope chat:run.

Request

POST /api/chat
Authorization: Bearer bctx_live_...
Content-Type: application/json

{
  "workspace": "acme",
  "activeNodeId": "node_123",
  "messages": [
    { "role": "user", "content": "summarize the open ADRs" }
  ]
}

GET/POST /api/nodes

Direct node CRUD for non-agent clients. GET needs nodes:read; POST needs nodes:write. Individual nodes live at /api/nodes/[id] with PATCH and DELETE.

Request

GET /api/nodes?workspace=acme
Authorization: Bearer bctx_live_...

POST /api/nodes
Authorization: Bearer bctx_live_...
Content-Type: application/json

{
  "workspace": "acme",
  "title":     "Migration plan",
  "kind":      "doc",
  "parent_id": null
}

Errors

All errors return JSON with an error field and an appropriate HTTP status: 400 bad input, 401 missing/invalid token, 403 wrong workspace, 404 workspace or node not found, 429 rate limited.