API Endpoints
Complete HTTP REST endpoint reference for the Cerememory Protocol.
Base URL
http://localhost:8420All API endpoints are prefixed with /v1/. Health and metrics endpoints are at the root level.
Authentication
When auth.enabled = true, all /v1/* endpoints require a Bearer token in the Authorization header:
Authorization: Bearer sk-cerememory-prod-abc123Health endpoints (/health, /readiness) bypass authentication and rate limiting. The /metrics endpoint is disabled by default and, when enabled, follows the configured auth and rate-limit policy.
Endpoint Reference
Health & Metrics
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health | No | Liveness probe -- returns {"status": "ok"} |
| GET | /readiness | No | Readiness probe -- verifies the engine can answer an internal stats request |
| GET | /metrics | Depends | Prometheus metrics (text format). Only present when http.metrics_enabled = true |
Encode
| Method | Path | Auth | Request Body | Response |
|---|---|---|---|---|
| POST | /v1/encode | Yes | EncodeStoreRequest | EncodeStoreResponse (200) |
| POST | /v1/encode/batch | Yes | EncodeBatchRequest | EncodeBatchResponse (200) |
| PATCH | /v1/encode/:record_id | Yes | EncodeUpdateRequest | 204 No Content |
| POST | /v1/encode/raw | Yes | EncodeStoreRawRequest | EncodeStoreRawResponse (200) |
| POST | /v1/encode/raw/batch | Yes | EncodeBatchStoreRawRequest | EncodeBatchStoreRawResponse (200) |
Recall
| Method | Path | Auth | Request Body | Response |
|---|---|---|---|---|
| POST | /v1/recall/query | Yes | RecallQueryRequest | RecallQueryResponse (200) |
| POST | /v1/recall/associate/:record_id | Yes | RecallAssociateRequest | RecallAssociateResponse (200) |
| POST | /v1/recall/timeline | Yes | RecallTimelineRequest | RecallTimelineResponse (200) |
| POST | /v1/recall/graph | Yes | RecallGraphRequest | RecallGraphResponse (200) |
| POST | /v1/recall/raw | Yes | RecallRawQueryRequest | RecallRawQueryResponse (200) |
Lifecycle
| Method | Path | Auth | Request Body | Response |
|---|---|---|---|---|
| POST | /v1/lifecycle/consolidate | Yes | ConsolidateRequest | ConsolidateResponse (200) |
| POST | /v1/lifecycle/decay-tick | Yes | DecayTickRequest | DecayTickResponse (200) |
| POST | /v1/lifecycle/dream-tick | Yes | DreamTickRequest | DreamTickResponse (200) |
| PUT | /v1/lifecycle/mode | Yes | SetModeRequest | 204 No Content |
| DELETE | /v1/lifecycle/forget | Yes | ForgetRequest | {"records_deleted": N} (200) |
| POST | /v1/lifecycle/export | Yes | ExportRequest | ExportResponse (200) |
| POST | /v1/lifecycle/import | Yes | ImportRequest | ImportResponse (200) |
Introspect
| Method | Path | Auth | Request Body | Response |
|---|---|---|---|---|
| GET | /v1/introspect/stats | Yes | -- | StatsResponse (200) |
| GET | /v1/introspect/record/:record_id | Yes | -- | MemoryRecord (200) |
| POST | /v1/introspect/decay-forecast | Yes | DecayForecastRequest | DecayForecastResponse (200) |
| GET | /v1/introspect/evolution | Yes | -- | EvolutionMetrics (200) |
Error Responses
All errors return a CMPError JSON envelope:
{
"code": "RECORD_NOT_FOUND",
"message": "Record not found: 01916e3a-...",
"details": null,
"retry_after": null
}HTTP Status Code Mapping
| CMP Error Code | HTTP Status | Description |
|---|---|---|
RECORD_NOT_FOUND | 404 | Record does not exist |
STORE_INVALID | 400 | Unknown store name |
CONTENT_TOO_LARGE | 413 | Exceeds modality size limit |
VALIDATION_ERROR | 400 | Malformed request or invalid values |
MODALITY_UNSUPPORTED | 400 | Provider does not support this modality |
WORKING_MEMORY_FULL | 503 | Working memory capacity exceeded |
DECAY_ENGINE_BUSY | 503 | Decay tick already in progress |
CONSOLIDATION_IN_PROGRESS | 503 | Consolidation already running |
EXPORT_FAILED | 500 | Archive export failed |
IMPORT_CONFLICT | 409 | Import conflict detected |
FORGET_UNCONFIRMED | 400 | Missing confirm: true |
VERSION_MISMATCH | 400 | Optimistic concurrency conflict |
UNAUTHORIZED | 401 | Missing or invalid API key |
RATE_LIMITED | 429 | Rate limit exceeded (includes Retry-After header) |
INTERNAL_ERROR | 500 | Unexpected server error |
Rate Limiting
API endpoints are rate-limited using a token bucket algorithm. When the limit is exceeded, the server returns:
- HTTP status
429 Too Many Requests Retry-Afterheader with the number of seconds to wait- CMPError body with
code: "RATE_LIMITED"andretry_afterfield
Default limits: 100 requests/second with a burst of 50.
Request Size Limits
HTTP API routes under /v1/* are capped at 64 MB request bodies (large enough for archive imports). This is separate from modality-level limits enforced by the engine itself.
CORS
CORS is configured via http.cors_origins.
- When the list is empty, Cerememory emits no CORS headers
- When origins are specified, only those origins receive CORS headers
- Use an explicit
"*"entry only if you intentionally want browser-wide access
Request Tracing
Every request receives an X-Request-Id header (UUID). This ID is propagated through all logging and can be used to correlate requests with server-side logs.
Next Steps
Complete CLI command reference
Protocol specification details