Skip to Content
Recall
REST API

Memories

Add content, list facts, read a version chain, edit, resolve and delete.

POST /v1/memories

Adds one piece of content. Recall stores it as a document and extracts facts in the background. Send JSON for text, a chat or a URL, or multipart/form-data for a file.

JSON body

Send exactly one of content, messages or url.

NameTypeRequiredDefaultLimits
containerstringnoserver default1 to 128 characters
contentstringone of threeup to 1,000,000 characters, not blank
messagesarray of { role, content }one of three1 to 2,000 messages. role 1 to 40 characters, content up to 1,000,000
urlstringone of threehttp or https URL
type"text", "chat" or "url"noinferredOnly "chat" changes anything: it stores content as a chat document
titlestringnofirst line of content (up to 80 characters), or the page title for a URLup to 300 characters
metadataobjectnoany JSON object
source_idstringno1 to 200 characters. See dedupe
document_datestringnothe day it's addedYYYY-MM-DD (a time part is ignored). The day the content was written. Relative dates in it resolve against this. See dates
waitbooleannofalseSee waiting
wait_timeoutnumber (seconds)no600 to 120
curl -X POST https://recall.zakiego.com/v1/memories \
  -H "Authorization: Bearer $RECALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"container":"alice","content":"I switched to Puma running shoes."}'

A chat:

curl -X POST https://recall.zakiego.com/v1/memories \
  -H "Authorization: Bearer $RECALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"container":"alice","messages":[{"role":"user","content":"I moved to Banjarbaru last month."},{"role":"assistant","content":"Noted."}]}'

A URL (HTML or PDF):

curl -X POST https://recall.zakiego.com/v1/memories \
  -H "Authorization: Bearer $RECALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"container":"alice","url":"https://example.com/post"}'

Multipart body

For PDF, HTML, Markdown and other text files, up to 20 MB.

FieldTypeRequiredDefaultLimits
filefileyesup to 20 MB. PDF, HTML, or a text-like type
containerstringnoserver default1 to 128 characters
titlestringnothe file name
metadatastringnoa JSON object, as text
source_idstringno1 to 200 characters
document_datestringnothe day it's addedYYYY-MM-DD
waitstringno1, 0, true or false
wait_timeoutstring (seconds)no600 to 120
curl -X POST https://recall.zakiego.com/v1/memories \
  -H "Authorization: Bearer $RECALL_KEY" \
  -F file=@notes.pdf \
  -F container=alice

An unsupported file type is accepted here and fails later in the ingest job. The document then ends up failed with unsupported file type: ....

Query parameters

NameTypeDefaultLimits
waitstring1, 0, true or false
wait_timeoutnumber (seconds)600 to 120

A value in the body (JSON field or form field) wins over the query string.

Response

Without wait, a new document returns 202:

{
  "id": "doc_...",
  "container": "alice",
  "status": "queued",
  "sourceId": null,
  "duplicate": false
}

Poll GET /v1/documents/:id for the status, or use wait.

Waiting for facts

Add ?wait=1 (or "wait": true in the JSON body, or a wait form field) and the request is held until the document is done or failed. It then returns 200 with the facts it wrote:

curl -X POST "https://recall.zakiego.com/v1/memories?wait=1" \
  -H "Authorization: Bearer $RECALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"container":"alice","content":"I switched to Puma running shoes."}'
{
  "id": "doc_...",
  "container": "alice",
  "status": "done",
  "sourceId": null,
  "duplicate": false,
  "settled": true,
  "error": null,
  "added": [],
  "updated": [
    {
      "id": "mem_...",
      "fact": "Prefers Puma running shoes",
      "keywords": "shoes sneakers running footwear sepatu lari merek brand puma",
      "kind": "dynamic",
      "supersedesId": "mem_...",
      "reviewNote": null
    }
  ],
  "invalidated": 0
}
  • added: new facts.
  • updated: new versions of older facts. supersedesId is the version it replaced.
  • invalidated: how many facts the document closed without a replacement.
  • A fact with a reviewNote conflicts with another one and is flagged for review.
  • A failed document also returns 200, with "status": "failed" and error set.

The default wait is 60 s. Set wait_timeout (seconds, up to 120) to change it. On timeout you get 202 with "settled": false and no fact lists:

{
  "id": "doc_...",
  "container": "alice",
  "status": "processing",
  "sourceId": null,
  "duplicate": false,
  "settled": false
}

Waiting queues behind other work

Extraction still runs in the single job loop, so a wait sits behind whatever is already queued. Behind a proxy with a shorter read timeout (Cloudflare's is 100 s), keep wait_timeout under it. If the client disconnects, the wait stops, and the document keeps processing.

Deduping with source_id

source_id is your own id for the source, like gmail:<message id> or a file path. It's unique per container in a workspace.

  • The first add creates the document and returns 202 with "duplicate": false.
  • A second add with the same source_id in the same container creates nothing and returns 200 with the existing document and "duplicate": true, whatever its status. With wait, it waits on that existing document instead.
  • The same source_id in another container is a separate document.
  • To ingest a source again, delete its document first.
curl -X POST https://recall.zakiego.com/v1/memories \
  -H "Authorization: Bearer $RECALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"container":"alice","content":"...","source_id":"gmail:18c2f0a9e1d4b7c3"}'
{
  "id": "doc_...",
  "container": "alice",
  "status": "done",
  "sourceId": "gmail:18c2f0a9e1d4b7c3",
  "duplicate": true
}

Status codes

StatusWhen
202New document queued (or a wait timed out)
200Duplicate source_id, or a wait that settled
400Invalid JSON, not exactly one of content/messages/url, a bad wait value, a missing file field, or bad metadata
413File over 20 MB

GET /v1/memories

Lists facts in a container, newest first.

NameTypeRequiredDefaultLimits
containerstringnoserver default1 to 128 characters
limitintegerno501 to 200
cursorstringnonextCursor from the previous page
history1, 0, true, falsenofalseInclude superseded and deleted versions
review1, 0, true, falsenofalseOnly current facts with a reviewNote. Ignores history
kindstatic or dynamicnoboth
curl "https://recall.zakiego.com/v1/memories?container=alice&limit=2" \
  -H "Authorization: Bearer $RECALL_KEY"
{
  "memories": [
    {
      "id": "mem_...",
      "workspaceId": "ws_...",
      "container": "alice",
      "fact": "Prefers Puma running shoes",
      "keywords": "shoes sneakers running footwear sepatu lari merek brand puma",
      "kind": "dynamic",
      "sourceDocumentId": "doc_...",
      "supersedesId": "mem_...",
      "validFrom": 1762675200000,
      "validTo": null,
      "createdAt": 1762675200000,
      "reviewNote": null,
      "eventDate": null,
      "eventPrecision": null,
      "dueDate": null,
      "duePrecision": null,
      "versions": 2
    },
    {
      "id": "mem_...",
      "workspaceId": "ws_...",
      "container": "alice",
      "fact": "Lives in Banjarbaru",
      "keywords": "city home lives kota tinggal domisili",
      "kind": "static",
      "sourceDocumentId": "doc_...",
      "supersedesId": null,
      "validFrom": 1762588800000,
      "validTo": null,
      "createdAt": 1762588800000,
      "reviewNote": null,
      "versions": 1
    }
  ],
  "nextCursor": "MTc2MjU4ODgwMDAwMDptZW1fLi4u"
}

versions counts this row plus every older version behind it. eventDate and dueDate are ISO dates (a month or year date is the first day of its period) with eventPrecision and duePrecision set to day, month or year, or all null when the fact has no date. See dates. Only flagged facts:

curl "https://recall.zakiego.com/v1/memories?container=alice&review=1" \
  -H "Authorization: Bearer $RECALL_KEY"

GET /v1/memories/:id

One memory and its whole version chain, oldest first. Works for any version in the chain, current or not.

curl https://recall.zakiego.com/v1/memories/mem_... \
  -H "Authorization: Bearer $RECALL_KEY"
{
  "memory": {
    "id": "mem_new...",
    "workspaceId": "ws_...",
    "container": "alice",
    "fact": "Prefers Puma running shoes",
    "keywords": "shoes sneakers running footwear sepatu lari merek brand puma",
    "kind": "dynamic",
    "sourceDocumentId": "doc_...",
    "supersedesId": "mem_old...",
    "validFrom": 1762675200000,
    "validTo": null,
    "createdAt": 1762675200000,
    "reviewNote": null
  },
  "history": [
    {
      "id": "mem_old...",
      "workspaceId": "ws_...",
      "container": "alice",
      "fact": "Prefers Adidas running shoes",
      "keywords": "shoes sneakers running sepatu lari adidas",
      "kind": "dynamic",
      "sourceDocumentId": "doc_...",
      "supersedesId": null,
      "validFrom": 1762588800000,
      "validTo": 1762675200000,
      "createdAt": 1762588800000,
      "reviewNote": null
    },
    {
      "id": "mem_new...",
      "workspaceId": "ws_...",
      "container": "alice",
      "fact": "Prefers Puma running shoes",
      "keywords": "shoes sneakers running footwear sepatu lari merek brand puma",
      "kind": "dynamic",
      "sourceDocumentId": "doc_...",
      "supersedesId": "mem_old...",
      "validFrom": 1762675200000,
      "validTo": null,
      "createdAt": 1762675200000,
      "reviewNote": null
    }
  ]
}

Returns 404 with not_found when the id doesn't exist in this workspace.

PATCH /v1/memories/:id

Edits a current fact, or clears its review flag. Send at least one field.

NameTypeRequiredLimits
factstringno1 to 500 characters
keywordsstringnoup to 500 characters
kindstatic or dynamicno
event_datestring or nullnoYYYY-MM-DD, YYYY-MM or YYYY. When it happened. null clears it
due_datestring or nullnoSame format. When it ends or is due. null clears it
resolvetruenoClears reviewNote without writing a new version
  • Changing fact, keywords, kind, event_date or due_date writes a new version: a new row with a new id and supersedesId set to the old one, which gets a validTo. The new version starts without a review note, so an edit also resolves a flag, on this fact and on the one its conflictsWithId points at. A profile rebuild is queued.
  • {"resolve": true} alone clears the note on the current row and on the other side of its conflict. No new version.
  • Sending the same values the fact already has writes nothing (it only clears a review note if there is one).
curl -X PATCH https://recall.zakiego.com/v1/memories/mem_... \
  -H "Authorization: Bearer $RECALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fact":"Prefers Puma running shoes for trail runs"}'
{
  "memory": {
    "id": "mem_...",
    "workspaceId": "ws_...",
    "container": "alice",
    "fact": "Prefers Puma running shoes for trail runs",
    "keywords": "shoes sneakers running footwear sepatu lari merek brand puma",
    "kind": "dynamic",
    "sourceDocumentId": "doc_...",
    "supersedesId": "mem_...",
    "validFrom": 1762761600000,
    "validTo": null,
    "createdAt": 1762761600000,
    "reviewNote": null
  }
}

Resolve a flag:

curl -X PATCH https://recall.zakiego.com/v1/memories/mem_... \
  -H "Authorization: Bearer $RECALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resolve":true}'
StatusWhen
200Edited or resolved. memory is the row as it is now
400No field to change ({"resolve": false} counts as none), or a field fails validation
404No such memory in this workspace
409not_current: the memory was superseded or deleted. Edit the current version instead

DELETE /v1/memories/:id

Soft-deletes a fact: sets validTo on it and drops it from search. The row stays in the version chain. If it was one side of a conflict, the other side's review note is cleared. A profile rebuild is queued.

curl -X DELETE https://recall.zakiego.com/v1/memories/mem_... \
  -H "Authorization: Bearer $RECALL_KEY"
{
  "memory": {
    "id": "mem_...",
    "workspaceId": "ws_...",
    "container": "alice",
    "fact": "Prefers Puma running shoes",
    "keywords": "shoes sneakers running footwear sepatu lari merek brand puma",
    "kind": "dynamic",
    "sourceDocumentId": "doc_...",
    "supersedesId": "mem_...",
    "validFrom": 1762675200000,
    "validTo": 1762761600000,
    "createdAt": 1762675200000,
    "reviewNote": null
  }
}

Deleting a memory that's already closed returns 200 with the row unchanged. An unknown id returns 404.

On this page