ceadr

API reference · brain v1

One contract any agent can pin against

ceadr publishes JSON Schema for every brain response. Validate payloads, generate types, or wire your agent through MCP. The schemas are the source of truth. This page is the readable map.

GET /schemas/brain-v1/index.jsonSchema version: brain-v1

Authentication

Bearer token in the path and header

Every brain endpoint requires the workspace bearer token. The token appears in the URL path AND the Authorization header. Both must match. Mint a key on the deploy page for your workspace.

Required

  • Authorization: Bearer ceadr_xxx

    The workspace bearer token.

  • Path: /api/brain/{token}/...

    Same token interpolated into the URL.

Optional agent identity

  • X-Agent-ID: my-support-bot

    Tags every query with this id. Per-agent stats appear on the feedback page.

  • X-Agent-Name: Support Bot

    Display name shown alongside the id.

Endpoints

REST, MCP, and a streaming feed

REST for one-shot queries, MCP for native agent integration via the mcp-remote shim, SSE for push notifications when your brain changes.

MethodPathPurpose
GET/api/brain/{token}/healthWorkspace health score, entity count, last activity
GET/api/brain/{token}/query?q=Ranked search hits with provenance
GET/api/brain/{token}/factsKnown facts as typed entities
GET/api/brain/{token}/policiesPolicy entities
GET/api/brain/{token}/playbooksPlaybook entities
GET/api/brain/{token}/gapsCoverage gaps and weak spots
GET/api/brain/{token}/historyRecent ontology changes
POST/api/brain/{token}/feedbackRecord an agent feedback signal
GET/api/brain/{token}/dashboardAggregated workspace dashboard payload
GET/api/brain/{token}/streamServer Sent Events stream of drift and contradiction events
GET/api/brain/{token}/.well-known/schemasWorkspace scoped schema discovery manifest
GET/mcp/{token}Model Context Protocol surface for Claude Desktop, Cursor, and other MCP hosts

Examples

Three ways to talk to your brain

Replace <TOKEN> with the bearer you minted on your workspace deploy page.

REST via curl

curl 'https://api.ceadr.ai/api/brain/<TOKEN>/query?q=what+is+the+pricing' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'X-Agent-ID: my-support-bot'

MCP for Claude Desktop

{
  "mcpServers": {
    "ceadr-brain": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.ceadr.ai/mcp/<TOKEN>",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <TOKEN>"
      }
    }
  }
}

Goes in claude_desktop_config.json. Works with the mcp-remote shim per the May 2026 MCP spec.

SSE drift stream

# Python (httpx-sse)
import httpx
from httpx_sse import connect_sse

with httpx.Client(timeout=None) as client:
    headers = {"Authorization": "Bearer <TOKEN>"}
    with connect_sse(client, "GET",
                     "https://api.ceadr.ai/api/brain/<TOKEN>/stream",
                     headers=headers) as events:
        for ev in events.iter_sse():
            print(ev.data)

Schema reference

Every response, typed

One section per published schema. Click the URL to fetch the raw JSON Schema and validate against it directly.