API reference

The CognitiveX (iCog) API is a JSON-over-HTTP interface to your memory, chat, agents, reflexes, connectors, and billing. Every product endpoint lives under the unversioned /api prefix. There is no path versioning and no Accept-Version header: the contract evolves additively.

Base URL

https://api.cognitivx.io

All product routes are mounted under /api (for example POST /api/recall). The machine-readable spec reports iCog API version 1.0.0; that is the document version, not a URL path segment.

Authentication

Every product endpoint requires authentication. You authenticate with an icog_-prefixed API key, created at developers.cognitivx.io/keys, or with a short-lived JWT access token. There are two accepted headers:

An icog_ key value is accepted in the Authorization: Bearer header too, so a single header works for both keys and tokens. Missing or invalid credentials return 401 with a WWW-Authenticate: Bearer header.

curl https://api.cognitivx.io/api/recall \
  -H 'X-API-Key: icog_...' \
  -H 'Content-Type: application/json' \
  -d '{"query":"what did we decide about billing","limit":5}'

Reference pages

Each surface has a hand-written contract page with request and response shapes, parameter tables, copy-pasteable examples, and the meaningful failure modes.

Conventions

• JSON everywhere. Request and response bodies are JSON unless a route is explicitly documented otherwise (for example SSE streams and redirects).
• Timestamps are ISO 8601 strings in UTC (created_at, occurred_at, last_used_at).
• IDs are UUID strings (users, sessions, messages, orgs, memories). There are no typed ID prefixes. The only prefix convention is icog_ on API keys.
• Money. Credits are the user-facing unit and are returned as integers (balance_credits). USD floats (*_usd, cost_usd) are the internal billing detail. There is no amount_cents or currency field. See Billing.
• Pagination. The dominant convention is limit / offset query params (offset is zero-based; each route caps limit). A few admin and audit lists use page / page_size instead. List search uses q. List responses are typically { "items": [...], "count": N } or { "<plural>": [...], "count": N } (for example recall returns { "memories": [...], "count": N }).
• Request IDs. Every response carries an X-Request-ID header (a uuid4 hex string). Quote it when reporting an issue.

Errors

Errors use the standard FastAPI shape: a JSON body with a detail field and a 4xx or 5xx status. detail is usually a string, but several gated and quota errors return a structured object (for example { "error": "tier_insufficient", "current_tier": ..., "required_tier": ..., "upgrade_url": ... }).

Validation errors (422) use the array form:

{
  "detail": [
    { "loc": ["body", "query"], "msg": "field required", "type": "missing" }
  ]
}

Uncaught server errors return { "detail": "Internal server error", "path": "<request path>" }.

OpenAPI

The full machine-readable spec is published at:

• api.cognitivx.io/openapi.json — OpenAPI 3.1.0 document.
• api.cognitivx.io/docs — interactive Swagger UI.

A per-endpoint reference, auto-generated from this spec on every deploy, lives under Generated endpoints in the sidebar.