REST API
REST API
Base URL, authentication, errors, pagination and the list of /v1 routes.
Base URL
https://recall.zakiego.comThe 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 noAuthorizationheader. - 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 aremultipart/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. containeris 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"
}
}| Status | type | When |
|---|---|---|
| 400 | invalid_json | The body isn't JSON. |
| 400 | invalid_request | A field fails validation. message lists what's wrong. |
| 401 | unauthorized | Missing or invalid API key. |
| 404 | not_found | No such memory or document in this workspace. |
| 409 | not_current | You tried to edit or resolve a memory that was superseded or deleted. |
| 413 | too_large | The uploaded file is over 20 MB. |
| 500 | internal | Anything unexpected. message has the error text. |
| 502 | gateway_error, bad_answer, gateway_unreachable | Ask only: the LLM gateway failed, its reply couldn't be read, or it couldn't be reached. |
| 503 | jobs_disabled | Ask only: the job loop is turned off on this server. |
| 504 | timeout | Ask 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
| Method | Path | What |
|---|---|---|
POST | /v1/memories | Add text, a chat, a URL or a file |
GET | /v1/memories | List facts |
GET | /v1/memories/:id | One fact and its version chain |
PATCH | /v1/memories/:id | Edit a fact or resolve its review flag |
DELETE | /v1/memories/:id | Soft-delete a fact |
POST | /v1/search | Hybrid search over facts and chunks |
GET | /v1/profile | The container's summary and top facts |
POST | /v1/ask | A cited answer from stored facts |
GET | /v1/documents/:id | A document's processing status |
DELETE | /v1/documents/:id | Delete a document and its chunks |
GET | /v1/containers | Containers in this workspace |
GET | /health | Health check, no auth |