Skip to Content
Recall
REST API

Ask

A short answer written only from stored facts, with citations mapped to real ids.

POST /v1/ask

Answers a question from the container's top 12 facts (plus 6 document chunks with include_chunks). It's one LLM call, run as an ask job that goes ahead of background work. The request waits up to 90 s. See Ask for how answers are grounded.

NameTypeRequiredDefaultLimits
containerstringnoserver default1 to 128 characters
questionstringyes1 to 2,000 characters after trimming
include_chunksbooleannofalseAlso read the 6 best-matching document chunks
curl -X POST https://recall.zakiego.com/v1/ask \
  -H "Authorization: Bearer $RECALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"container":"alice","question":"What running shoes do I wear?","include_chunks":true}'
{
  "container": "alice",
  "question": "What running shoes do I wear?",
  "answer": "They wear Puma running shoes [1], after switching from Adidas [2].",
  "covered": true,
  "citations": [
    {
      "type": "memory",
      "id": "mem_...",
      "text": "Prefers Puma running shoes",
      "ref": 1
    },
    {
      "type": "chunk",
      "id": "chk_...",
      "text": "I switched from Adidas to Puma running shoes.",
      "documentId": "doc_...",
      "documentTitle": "Running notes",
      "ref": 2
    }
  ],
  "model": "claude-haiku-5-5",
  "people": [],
  "timingMs": 4210
}
FieldMeaning
answerPlain prose in the question's language. [n] refers to the citation with ref n
coveredfalse when memory doesn't answer the question
citationsThe facts and chunks the answer cites, numbered in order of first use. Memory citations carry type, id, text, ref. Chunk citations add documentId and documentTitle
modelThe model that wrote the answer (after any fallback). null when no LLM call was made
peopleThe people named in the question whose facts were sent first, as { id, name }
timingMsTotal time, including the wait for a job slot

When the container has no current facts (and, with include_chunks, no chunks either), Recall answers right away without calling the LLM:

{
  "container": "empty",
  "question": "Where do I work?",
  "answer": "Nothing is stored in this container yet, so there is nothing to answer from.",
  "covered": false,
  "citations": [],
  "model": null,
  "people": [],
  "timingMs": 12
}

Errors

StatustypeWhen
400invalid_requestMissing or empty question
502gateway_errorThe LLM gateway returned an error
502bad_answerThe model's reply couldn't be read, even after one retry
502gateway_unreachableThe gateway couldn't be reached
503jobs_disabledThe job loop is off on this server, so nothing can answer
504timeoutNo answer within 90 s. Recall is busy or the gateway is slow. Try again in a minute
{
  "error": {
    "type": "timeout",
    "message": "No answer within 90 s. The gateway is slow or Recall is busy extracting a large document. Try again in a minute."
  }
}

On a timeout, an ask that hasn't started yet is dropped from the queue, and one that's already running has its LLM call aborted. Asks are never retried.

On this page