Skip to content
AugentaDocsOpen console ↗
Recall

Documentation

API reference
View Markdown

Recall

POST/v1/recall

Recall 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

modestringoptional

query 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"

retrievalstringoptional

query 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-Keystringoptional

header 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-Contentstringoptional

header 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"

Acceptstringoptional

header 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

recordbooleanoptional

Whether to record a reuse activation. false performs no activation lookup or write and needs no Idempotency-Key.

Default: true

querystringrequired

The question, in plain language.

Min length: 1Max length: 4096

workspacestringoptional

One 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.

originstringoptional

Who 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_tokensintegeroptional

Context 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

timezonestringoptional

The 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.

billingobjectconditional

Present 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 present
priceVersionstringalways present
sourceTokensintegeralways present

Minimum: 0

memoryTokensintegeralways present

Minimum: 0

measuredMemoryTokensintegeralways present

Minimum: 0

replayedbooleanalways present
complimentarybooleanconditional
ratedAmountstringconditional
amountstringalways present
receiptIdsarrayalways present
Show item fields
noMatchbooleanalways present

true when a valid recall has no candidates. Returns 200 with empty content and no model call; service failures remain errors.

scoreobjectconditional

Actual 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 present
valuenumberalways present
parametersobjectconditional
componentsarrayconditional
Show item fields
methodstringalways present
valuenumberalways present
rankintegeralways present
workspacestringalways present

The authorized Workspace this recall read.

modestringalways present

Which mode produced this response.

Allowed: "answer""context"

reference_datestring | nullalways present

The latest date (YYYY-MM-DD) any returned claim was observed, or null. Resolve "recently" against this.

claim_countintegeralways present

How many claims retrieval selected, before response limits. Not a count of every claim in the Workspace.

claims_truncatedbooleanalways present

true when content holds fewer claims than claim_count (at most 100 are returned, fewer if the token budget runs out first).

windowobjectconditional

Present 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 present

Start of the window, an ISO 8601 instant (inclusive).

tostringalways present

End of the window, an ISO 8601 instant (exclusive).

timezonestringalways present

The zone the window's days were taken in: the request's timezone, or UTC.

claim_countintegeralways present

How many claims were recorded in the window.

session_countintegeralways present

How many sessions those claims come from. A subagent counts with its parent.

document_countintegeralways present

How many documents those claims come from.

claims_shownintegeralways present

How many of the window's claims this response's evidence holds.

sessions_shownintegeralways present

How many of the window's sessions those claims come from.

selectionstringalways present

coverage: 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 present

Ordered 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
Answer
typestringalways present

Allowed: "answer"

textstringalways present

The written answer.

Engram
typestringalways present

Allowed: "engram"

textstringalways present

The engram's summary: what the Workspace has consolidated on this topic.

engram_idstringalways present

A stable handle for this engram.

memory_classstring | nullalways present

The kind of memory, e.g. procedural or semantic.

born_tstring | nullalways present

When the engram formed.

contradictionbooleanalways present

true when its claims disagree with each other.

quality_verdictstringalways present

Quality assessment, or unscored.

Claim
typestringalways present

Allowed: "claim"

textstringalways present

One 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 present

When it was observed, as the producer wrote it.

questionbooleanalways present

true when the claim records a question rather than a statement.

frameobjectalways present

Structured fields extracted with the claim. May be empty.

metadataobjectalways present

Where the observation came from, e.g. src. May be empty.

Lineage
typestringalways present

Allowed: "lineage"

textstringalways present

One event in the engram's history, e.g. BORN (0->3 members).

tstringalways present

When it happened.

kindstringalways present

The event kind, e.g. born.

members_beforeinteger | nullalways present
members_afterinteger | nullalways present