Recall
/v1/recallRecall from an authorized Workspace. Searches retained claims, including those not yet in an engram. Returns memory and an answer when mode=answer. Recall records activation unless record=false. A valid empty recall is 200 with noMatch=true. Neither stores the question or answer.
Authentication
Send your API key with the AugentaKey authorization scheme. Workspace requests must target a Workspace assigned to the key. See authentication and permissions.
Request
Parameters
modestringoptionalquery parameter. context (the default) skips the model and returns only the memory, for your own model to read. answer runs a model and puts a written answer first.
Allowed: "context""answer"
Default: "context"
retrievalstringoptionalquery parameter. Which claims are searched for. Omit this parameter to use the deployment's configured retrieval. pool searches every retained claim by meaning and by keyword. constraint keeps the claims your question's own phrases, terms, identifiers, times and quantities point to, ordered by how much each narrows, and returns noMatch when the question matches none of them.
Allowed: "pool""constraint"
Idempotency-Keystringoptionalheader parameter. Required unless record=false. Any string up to 256 characters, such as a new UUID per question. Retries with the same key record one activation, not two. Reusing a key with a different query returns 409 idempotency_conflict.
Min length: 1Max length: 256
X-Augenta-Contentstringoptionalheader parameter. The response format. Send content-v3: claim blocks, claim_count and claims_truncated, as documented below. Without it you get content-v2, which is deprecated and calls each claim a note (note blocks, note_count, notes_truncated); the default will become content-v3. Any other value returns 406 unsupported_content.
Allowed: "content-v3""content-v2"
Default: "content-v2"
Acceptstringoptionalheader parameter. Send text/event-stream to receive an answer-mode Workspace recall as server-sent events (see the 200 response). Any other value, including */*, returns JSON. Context mode always returns JSON.
Body fields
recordbooleanoptionalWhether to record a reuse activation. false performs no activation lookup or write and needs no Idempotency-Key.
Default: true
workspacestringoptionalOne Workspace assigned to the key. Required for multiple assignments, inferred for one. A Workspace outside the assignments returns 403; a key with no assignments cannot use Recall.
originstringoptionalWho asked. manual (a person asked) records a full-weight activation. auto (your code asks on every request, unprompted) records a quarter-weight one, so frequent automatic calls don't drown out deliberate reuse.
Allowed: "manual""auto"
Default: "manual"
budget_tokensintegeroptionalContext mode only: about how many tokens of claim and summary text you want back. Clamped to 100–8000. Defaults to 6000 for manual and 1500 for auto. Ignored in answer mode.
Minimum: 1
timezonestringoptionalThe asker's IANA time zone. A time in the question ("on October 13", "yesterday", "last week") selects the claims recorded in that span of the asker's calendar, and reference_date is the asker's date. Send the zone the person asking is in; the browser's is Intl.DateTimeFormat().resolvedOptions().timeZone.
Max length: 64
Default: "UTC"
Responses
The matched memory. answer mode adds one answer block first.
billingobjectconditionalPresent when billing is enabled. USD amount is exact. Receipt references settle only on successful server delivery; retries reuse the original debit.
Show nested fields
operationIdstringalways presentpriceVersionstringalways presentsourceTokensintegeralways presentMinimum: 0
memoryTokensintegeralways presentMinimum: 0
measuredMemoryTokensintegeralways presentMinimum: 0
replayedbooleanalways presentcomplimentarybooleanconditionalratedAmountstringconditionalamountstringalways presentreceiptIdsarrayalways presentShow item fields
noMatchbooleanalways presenttrue when a valid recall has no candidates. Returns 200 with empty content and no model call; service failures remain errors.
scoreobjectconditionalActual retrieval ranking score, with its method and contributing channels. Raw reciprocal-rank-fusion, inner-product and BM25 values are not confidence probabilities and are not comparable across queries or Workspaces. Absent for noMatch.
Show nested fields
methodstringalways presentvaluenumberalways presentparametersobjectconditionalcomponentsarrayconditionalworkspacestringalways presentThe authorized Workspace this recall read.
reference_datestring | nullalways presentThe latest date (YYYY-MM-DD) any returned claim was observed, or null. Resolve "recently" against this.
claim_countintegeralways presentHow many claims retrieval selected, before response limits. Not a count of every claim in the Workspace.
claims_truncatedbooleanalways presenttrue when content holds fewer claims than claim_count (at most 100 are returned, fewer if the token budget runs out first).
windowobjectconditionalPresent when the question named a time that claims were recorded in ("what was done on October 13?"): which span was read, how much memory was recorded in it, and how much of that this response holds. Absent otherwise. A time selects claims by when they were recorded, never by a date their text mentions.
Show nested fields
fromstringalways presentStart of the window, an ISO 8601 instant (inclusive).
tostringalways presentEnd of the window, an ISO 8601 instant (exclusive).
timezonestringalways presentThe zone the window's days were taken in: the request's timezone, or UTC.
claim_countintegeralways presentHow many claims were recorded in the window.
session_countintegeralways presentHow many sessions those claims come from. A subagent counts with its parent.
document_countintegeralways presentHow many documents those claims come from.
claims_shownintegeralways presentHow many of the window's claims this response's evidence holds.
sessions_shownintegeralways presentHow many of the window's sessions those claims come from.
selectionstringalways presentcoverage: the question asked what happened in the window, so the claims are spread across every session and every active stretch of it. ranked: the question named a topic too, so they are the window's claims that best match it.
Allowed: "coverage""ranked"
contentarrayalways presentOrdered blocks: answer (answer mode only), then engram, then claims oldest first, then lineage. Every block has type and text. Ignore block types you don't recognize; new ones may be added.
Show item fields
Engram
typestringalways presentAllowed: "engram"
textstringalways presentThe engram's summary: what the Workspace has consolidated on this topic.
engram_idstringalways presentA stable handle for this engram.
memory_classstring | nullalways presentThe kind of memory, e.g. procedural or semantic.
born_tstring | nullalways presentWhen the engram formed.
contradictionbooleanalways presenttrue when its claims disagree with each other.
quality_verdictstringalways presentQuality assessment, or unscored.
Claim
typestringalways presentAllowed: "claim"
textstringalways presentOne statement the engram was built from. A model wrote it from captured experience, such as an agent's session, so it describes what happened rather than quoting anyone.
timestampstring | nullalways presentWhen it was observed, as the producer wrote it.
questionbooleanalways presenttrue when the claim records a question rather than a statement.
frameobjectalways presentStructured fields extracted with the claim. May be empty.
metadataobjectalways presentWhere the observation came from, e.g. src. May be empty.
Lineage
typestringalways presentAllowed: "lineage"
textstringalways presentOne event in the engram's history, e.g. BORN (0->3 members).
tstringalways presentWhen it happened.
kindstringalways presentThe event kind, e.g. born.
members_beforeinteger | nullalways presentmembers_afterinteger | nullalways present