Skip to Content
Recall
REST API

REST API

Base URL, authentication, errors, pagination and the list of /v1 routes.

Base URL

https://recall.zakiego.com

The API lives at /v1/*. The MCP server is at /mcp and the health check at /health, both at the root too.

Authentication

Every /v1 route needs an API key in the Authorization header:

curl https://recall.zakiego.com/v1/containers \
  -H "Authorization: Bearer $RECALL_KEY"
  • Keys start with rcl_. Create them in the dashboard under Settings, API keys (owners and admins), or with the admin CLI. A key is shown once.
  • A key belongs to one workspace. Every request made with it reads and writes only that workspace. The body never picks the workspace.
  • An X-API-Key: rcl_... header works too when there's no Authorization header.
  • A missing, unknown or revoked key gets 401.

See Auth for how keys are created, stored and revoked.

Requests and responses

  • Request bodies are JSON (Content-Type: application/json), except file uploads, which are multipart/form-data.
  • Responses are JSON with Cache-Control: no-store.
  • Timestamps (createdAt, validFrom, validTo, updatedAt, lastActivity) are Unix milliseconds.
  • Ids are prefixed: mem_ for memories, doc_ for documents, chk_ for chunks.
  • container is optional everywhere. Leave it out (or send an empty string) to use the server's default container. It's 1 to 128 characters after trimming.

Errors

Errors share one shape:

{
  "error": {
    "type": "unauthorized",
    "message": "missing or invalid API key"
  }
}
StatustypeWhen
400invalid_jsonThe body isn't JSON.
400invalid_requestA field fails validation. message lists what's wrong.
401unauthorizedMissing or invalid API key.
404not_foundNo such memory or document in this workspace.
409not_currentYou tried to edit or resolve a memory that was superseded or deleted.
413too_largeThe uploaded file is over 20 MB.
500internalAnything unexpected. message has the error text.
502gateway_error, bad_answer, gateway_unreachableAsk only: the LLM gateway failed, its reply couldn't be read, or it couldn't be reached.
503jobs_disabledAsk only: the job loop is turned off on this server.
504timeoutAsk only: no answer within 90 s.

Pagination

Only GET /v1/memories pages. It returns nextCursor. Pass it back as ?cursor= to get the next page. nextCursor is null on the last page. The cursor is opaque. Pages are ordered newest first.

Rate limits

There are no rate limits on /v1 or /mcp. The sign-in and invite endpoints have their own limits, listed in Auth.

Routes

MethodPathWhat
POST/v1/memoriesAdd text, a chat, a URL or a file
GET/v1/memoriesList facts
GET/v1/memories/:idOne fact and its version chain
PATCH/v1/memories/:idEdit a fact or resolve its review flag
DELETE/v1/memories/:idSoft-delete a fact
POST/v1/searchHybrid search over facts and chunks
GET/v1/profileThe container's summary and top facts
POST/v1/askA cited answer from stored facts
GET/v1/documents/:idA document's processing status
DELETE/v1/documents/:idDelete a document and its chunks
GET/v1/containersContainers in this workspace
GET/healthHealth check, no auth

On this page