# 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

Use an API key with the AugentaKey authorization scheme. See [Authentication](https://augenta.pages.dev/docs/authentication.md).

## Request example

```bash
curl --fail-with-body -X POST "https://api.augenta.ai/v1/recall" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "query": "How do we deploy the checkout service?"
}'
```

## Parameters

<a id="request-parameters-mode"></a>

### `request.parameters.mode`

`string` · optional

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 values: `"context"`, `"answer"`.

Default: `"context"`.

<a id="request-parameters-retrieval"></a>

### `request.parameters.retrieval`

`string` · optional

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 values: `"pool"`, `"constraint"`.

<a id="request-parameters-idempotency-key"></a>

### `request.parameters.Idempotency-Key`

`string` · optional

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: `1`. Max length: `256`.

<a id="request-parameters-x-augenta-content"></a>

### `request.parameters.X-Augenta-Content`

`string` · optional

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 values: `"content-v3"`, `"content-v2"`.

Default: `"content-v2"`.

<a id="request-parameters-accept"></a>

### `request.parameters.Accept`

`string` · optional

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

<a id="request-body-record"></a>

### `request.body.record`

`boolean` · optional

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

Default: `true`.

<a id="request-body-query"></a>

### `request.body.query`

`string` · required

The question, in plain language.

Min length: `1`. Max length: `4096`.

<a id="request-body-workspace"></a>

### `request.body.workspace`

`string` · optional

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.

<a id="request-body-origin"></a>

### `request.body.origin`

`string` · optional

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 values: `"manual"`, `"auto"`.

Default: `"manual"`.

<a id="request-body-budget_tokens"></a>

### `request.body.budget_tokens`

`integer` · optional

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

<a id="request-body-timezone"></a>

### `request.body.timezone`

`string` · optional

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

Default: `"UTC"`.

Max length: `64`.

## Response 200

The matched memory.  answer mode adds one `answer` block first.

Content-Type: `application/json`

```json
{
  "workspace": "ws-platform",
  "mode": "answer",
  "reference_date": "2026-10-02",
  "claim_count": 14,
  "claims_truncated": false,
  "noMatch": false,
  "content": [
    {
      "type": "answer",
      "text": "Checkout deploys through the Helm chart: merge to main, CI builds the image, and the release workflow rolls it to dev."
    },
    {
      "type": "engram",
      "text": "Checkout service deploys via the Helm chart from a main merge.",
      "engram_id": "e042",
      "memory_class": "procedural",
      "born_t": "2026-09-14T10:22:31Z",
      "contradiction": false,
      "quality_verdict": "unscored"
    },
    {
      "type": "claim",
      "text": "Merging to main triggers the release workflow, which deploys checkout to dev.",
      "timestamp": "2026-10-02T16:05:11Z",
      "question": false,
      "frame": {},
      "metadata": {
        "src": "claude-code"
      }
    },
    {
      "type": "lineage",
      "text": "BORN (0->3 members)",
      "t": "2026-09-14T10:22:31Z",
      "kind": "born",
      "members_before": 0,
      "members_after": 3
    }
  ]
}
```

<a id="response-200-billing"></a>

### `response.200.billing`

`object` · conditional

Present when billing is enabled. USD amount is exact. Receipt references settle only on successful server delivery; retries reuse the original debit.

<a id="response-200-billing-operationid"></a>

### `response.200.billing.operationId`

`string` · always present

<a id="response-200-billing-priceversion"></a>

### `response.200.billing.priceVersion`

`string` · always present

<a id="response-200-billing-sourcetokens"></a>

### `response.200.billing.sourceTokens`

`integer` · always present

Minimum: `0`.

<a id="response-200-billing-memorytokens"></a>

### `response.200.billing.memoryTokens`

`integer` · always present

Minimum: `0`.

<a id="response-200-billing-measuredmemorytokens"></a>

### `response.200.billing.measuredMemoryTokens`

`integer` · always present

Minimum: `0`.

<a id="response-200-billing-replayed"></a>

### `response.200.billing.replayed`

`boolean` · always present

<a id="response-200-billing-complimentary"></a>

### `response.200.billing.complimentary`

`boolean` · conditional

<a id="response-200-billing-ratedamount"></a>

### `response.200.billing.ratedAmount`

`string` · conditional

<a id="response-200-billing-amount"></a>

### `response.200.billing.amount`

`string` · always present

<a id="response-200-billing-receiptids"></a>

### `response.200.billing.receiptIds`

`array<string>` · always present

<a id="response-200-nomatch"></a>

### `response.200.noMatch`

`boolean` · always present

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

<a id="response-200-score"></a>

### `response.200.score`

`object` · conditional

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.

<a id="response-200-score-method"></a>

### `response.200.score.method`

`string` · always present

<a id="response-200-score-value"></a>

### `response.200.score.value`

`number` · always present

<a id="response-200-score-parameters"></a>

### `response.200.score.parameters`

`object` · conditional

<a id="response-200-score-components"></a>

### `response.200.score.components`

`array<object>` · conditional

<a id="response-200-score-components-method"></a>

### `response.200.score.components.method`

`string` · always present

<a id="response-200-score-components-value"></a>

### `response.200.score.components.value`

`number` · always present

<a id="response-200-score-components-rank"></a>

### `response.200.score.components.rank`

`integer` · always present

<a id="response-200-workspace"></a>

### `response.200.workspace`

`string` · always present

The authorized Workspace this recall read.

<a id="response-200-mode"></a>

### `response.200.mode`

`string` · always present

Which mode produced this response.

Allowed values: `"answer"`, `"context"`.

<a id="response-200-reference_date"></a>

### `response.200.reference_date`

`string | null` · always present

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

<a id="response-200-claim_count"></a>

### `response.200.claim_count`

`integer` · always present

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

<a id="response-200-claims_truncated"></a>

### `response.200.claims_truncated`

`boolean` · always present

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

<a id="response-200-window"></a>

### `response.200.window`

`object` · conditional

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.

<a id="response-200-window-from"></a>

### `response.200.window.from`

`string` · always present

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

<a id="response-200-window-to"></a>

### `response.200.window.to`

`string` · always present

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

<a id="response-200-window-timezone"></a>

### `response.200.window.timezone`

`string` · always present

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

<a id="response-200-window-claim_count"></a>

### `response.200.window.claim_count`

`integer` · always present

How many claims were recorded in the window.

<a id="response-200-window-session_count"></a>

### `response.200.window.session_count`

`integer` · always present

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

<a id="response-200-window-document_count"></a>

### `response.200.window.document_count`

`integer` · always present

How many documents those claims come from.

<a id="response-200-window-claims_shown"></a>

### `response.200.window.claims_shown`

`integer` · always present

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

<a id="response-200-window-sessions_shown"></a>

### `response.200.window.sessions_shown`

`integer` · always present

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

<a id="response-200-window-selection"></a>

### `response.200.window.selection`

`string` · always 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 values: `"coverage"`, `"ranked"`.

<a id="response-200-content"></a>

### `response.200.content`

`array<choice>` · always present

Ordered blocks: `answer` (answer mode only), then `engram`, then `claim`s oldest first, then `lineage`. Every block has `type` and `text`. Ignore block types you don't recognize; new ones may be added.

**Option 1**

<a id="response-200-content-option-1-type"></a>

### `response.200.content.option-1.type`

`string` · always present

Allowed values: `"answer"`.

<a id="response-200-content-option-1-text"></a>

### `response.200.content.option-1.text`

`string` · always present

The written answer.

**Option 2**

<a id="response-200-content-option-2-type"></a>

### `response.200.content.option-2.type`

`string` · always present

Allowed values: `"engram"`.

<a id="response-200-content-option-2-text"></a>

### `response.200.content.option-2.text`

`string` · always present

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

<a id="response-200-content-option-2-engram_id"></a>

### `response.200.content.option-2.engram_id`

`string` · always present

A stable handle for this engram.

<a id="response-200-content-option-2-memory_class"></a>

### `response.200.content.option-2.memory_class`

`string | null` · always present

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

<a id="response-200-content-option-2-born_t"></a>

### `response.200.content.option-2.born_t`

`string | null` · always present

When the engram formed.

<a id="response-200-content-option-2-contradiction"></a>

### `response.200.content.option-2.contradiction`

`boolean` · always present

`true` when its claims disagree with each other.

<a id="response-200-content-option-2-quality_verdict"></a>

### `response.200.content.option-2.quality_verdict`

`string` · always present

Quality assessment, or `unscored`.

**Option 3**

<a id="response-200-content-option-3-type"></a>

### `response.200.content.option-3.type`

`string` · always present

Allowed values: `"claim"`.

<a id="response-200-content-option-3-text"></a>

### `response.200.content.option-3.text`

`string` · always 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.

<a id="response-200-content-option-3-timestamp"></a>

### `response.200.content.option-3.timestamp`

`string | null` · always present

When it was observed, as the producer wrote it.

<a id="response-200-content-option-3-question"></a>

### `response.200.content.option-3.question`

`boolean` · always present

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

<a id="response-200-content-option-3-frame"></a>

### `response.200.content.option-3.frame`

`object` · always present

Structured fields extracted with the claim. May be empty.

<a id="response-200-content-option-3-metadata"></a>

### `response.200.content.option-3.metadata`

`object` · always present

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

**Option 4**

<a id="response-200-content-option-4-type"></a>

### `response.200.content.option-4.type`

`string` · always present

Allowed values: `"lineage"`.

<a id="response-200-content-option-4-text"></a>

### `response.200.content.option-4.text`

`string` · always present

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

<a id="response-200-content-option-4-t"></a>

### `response.200.content.option-4.t`

`string` · always present

When it happened.

<a id="response-200-content-option-4-kind"></a>

### `response.200.content.option-4.kind`

`string` · always present

The event kind, e.g. `born`.

<a id="response-200-content-option-4-members_before"></a>

### `response.200.content.option-4.members_before`

`integer | null` · always present

<a id="response-200-content-option-4-members_after"></a>

### `response.200.content.option-4.members_after`

`integer | null` · always present

Content-Type: `text/event-stream`

```json
"event: evidence\ndata: {\"workspace\":\"ws-platform\",\"mode\":\"answer\",\"claim_count\":14,\"claims_truncated\":false,\"noMatch\":false,\"content\":[…]}\n\nevent: status\ndata: {\"phase\":\"thinking\"}\n\n: keepalive\n\nevent: status\ndata: {\"phase\":\"answering\"}\n\nevent: delta\ndata: {\"text\":\"Checkout deploys through\"}\n\nevent: delta\ndata: {\"text\":\" the Helm chart.\"}\n\nevent: done\ndata: {\"workspace\":\"ws-platform\",\"mode\":\"answer\",\"content\":[{\"type\":\"answer\",\"text\":\"Checkout deploys through the Helm chart.\"},…]}\n\n"
```

Answer mode with `Accept: text/event-stream`. Events, in order: `evidence`: the recall body without the answer, sent as soon as retrieval finishes; `status`: `{"phase":"thinking"}` when the model starts reasoning, then `{"phase":"answering"}` at its first text; `delta`: `{"text":"…"}`, answer text in order; then exactly one of `done` (the same body the JSON response would have, answer block first) or `error` (the error envelope plus `status`, the HTTP status the same failure would have had as a response). A `: keepalive` comment arrives whenever 5 seconds pass with nothing else. Failures before the answer starts (authentication, validation, `idempotency_conflict`, `at_capacity`, an unavailable answerer) are ordinary HTTP errors, not events.

## Response 400

`invalid_request`: the request is malformed: a missing `Idempotency-Key`, an empty or over-long `query`, a bad `mode` / `origin` / `budget_tokens` / `timezone`, a body that sends `scope` or `weight`, a body that sends unsupported state/snapshot fields, or (with a user token) a missing `workspace`.

Content-Type: `application/json`

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Idempotency-Key is required",
    "retryable": false
  },
  "requestId": "req_7f9c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10"
}
```

<a id="response-400-error"></a>

### `response.400.error`

`object` · always present

<a id="response-400-error-code"></a>

### `response.400.error.code`

`string` · always present

Stable. The Errors page lists every code.

<a id="response-400-error-message"></a>

### `response.400.error.message`

`string` · always present

Human-readable. May change; don't parse it.

<a id="response-400-error-retryable"></a>

### `response.400.error.retryable`

`boolean` · always present

<a id="response-400-error-retryafterseconds"></a>

### `response.400.error.retryAfterSeconds`

`integer` · conditional

Capacity retry interval, also present as Retry-After before stream headers commit. SSE error events retain this field after HTTP 200 is committed.

Minimum: `1`.

<a id="response-400-error-billingurl"></a>

### `response.400.error.billingUrl`

`string` · conditional

Top-up action when error.code is insufficient_balance (HTTP 402).

<a id="response-400-requestid"></a>

### `response.400.requestId`

`string` · always present

The request's id, as in the `X-Request-Id` response header.

## Response 401

`unauthenticated`: missing, invalid or revoked credential.

Content-Type: `application/json`

```json
{
  "error": {
    "code": "unauthenticated",
    "message": "invalid or revoked Augenta key",
    "retryable": false
  },
  "requestId": "req_7f9c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10"
}
```

Response fields use the same schema as Response 400.

## Response 402

insufficient_balance: add credits and explicitly retry with the same Idempotency-Key. Streaming errors retain status 402.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 403

`forbidden`: the credential cannot read this Workspace: the key belongs to a different Workspace, or the Workspace is unavailable. `connector_inactive`: the key's Connector is disabled.

Content-Type: `application/json`

```json
{
  "error": {
    "code": "connector_inactive",
    "message": "active Connector required",
    "retryable": false
  },
  "requestId": "req_7f9c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10"
}
```

Response fields use the same schema as Response 400.

## Response 404

`workspace_not_found`: no Workspace with that id in your organization. An existing empty Workspace returns 200 with noMatch=true.

Content-Type: `application/json`

```json
{
  "error": {
    "code": "workspace_not_found",
    "message": "Workspace does not exist",
    "retryable": false
  },
  "requestId": "req_7f9c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10"
}
```

Response fields use the same schema as Response 400.

## Response 406

`unsupported_content`: `X-Augenta-Content` named a response version that isn't served. Send `content-v3`.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 409

`idempotency_conflict`: the `Idempotency-Key` was already used with a different query. `embedder_mismatch`: a server-side configuration problem. `workspace_archived`: the Workspace is archived.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 415

`unsupported_media_type`: the body was not sent as `application/json`.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 422

`empty_query`: the query had nothing to search on. `evidence_over_budget`: `budget_tokens` is too small to hold even the matched claim.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 429

`rate_limited` (retryable): wait the number of seconds in `Retry-After`. `at_capacity` (retryable): Recall is at its embedding or answer concurrency limit; wait the same way.

Content-Type: `application/json`

```json
{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded",
    "retryable": true
  },
  "requestId": "req_7f9c2b1e-6d0a-4b7e-9a51-2f0c8e7d4a10"
}
```

Response fields use the same schema as Response 400.

## Response 500

`store_misconfigured`: a server configuration problem. Contact support. `internal_error`: an unexpected failure; quote the `requestId`.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 502

`answer_failed` (retryable), `recall_unavailable` (retryable), `cognition_failed` (retryable) or `recall_forward_rejected`.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 503

`engram_vanished` (retryable), `workos_unavailable` (retryable), or `cognition_unavailable` (retryable): a required service is unavailable. `consent_required`: external model consent is missing. `answerer_unavailable`: this deployment cannot write answers; `mode=context` remains available when embedding is configured and consented.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 504

`recall_timeout` (retryable): no answer within 15 seconds (context) or 60 seconds (answer).

Content-Type: `application/json`

Response fields use the same schema as Response 400.
