API Reference

This reference is generated from the live FastAPI spec served at /api/openapi.json. The committed snapshot at openapi.snapshot.json is the build-time source of truth; CI fails when it drifts.

Regenerate locally with:

API_BASE_URL=https://caura.ai  npm run regen:openapi   # managed
API_BASE_URL=http://localhost:8000 npm run regen:openapi  # self-hosted

Base URL

Managed: https://caura.ai, with every route under /api/v1. Self-hosted: your own gateway origin. The API is served from the apex domain — api.caura.ai and docs.caura.ai do not exist and do not resolve, so a client that assumes the usual api. subdomain fails at DNS rather than returning anything you can read. See Integrations → REST.

Authentication

All endpoints accept X-API-Key. For per-tenant keys (mc_*), also send X-Tenant-ID. See Auth modes.

Errors follow the canonical envelope ({ error: { code, message, details? } }). REST responses also keep a top-level detail for back-compat.

Curated pages

A hand-picked subset rendered with the <APIPage> component. The list is short by design; for everything else, fetch the live OpenAPI directly.

• Write a memory — POST /api/v1/memories
• Recall — POST /api/v1/recall
• Search — POST /api/v1/search, the same ranking without the LLM summary; what the Rail SDK calls
• Stats — GET /api/v1/memories/stats, GET /api/v1/stats
• Keystones — GET / POST / DELETE /api/v1/keystones
• Search documents — POST /api/v1/documents/search
• List collections — GET /api/v1/documents/collections
• Health — GET /api/v1/health

The full surface

For the complete set (admin · agents · audit-log · crystallize · documents · entities · evolve · fleet · graph · ingest · insights · keystones · memories · plugin · recall · search · settings · stats · stm · tenants · whoami), use the live Swagger UI at /api/docs or pull the spec at /api/openapi.json.