---
title: "Recall memories for grounding"
method: POST
path: "/v1/recall"
tags: ["memory"]
---

# Recall memories for grounding

`POST /v1/recall`

## Request

- Base URL: `https://api.contextdb.ai`
- URL: `https://api.contextdb.ai/v1/recall`
- Auth: HTTP bearer

## Request body

- RecallRequest
  - `user_id` string, required: End-user memory partition key. Not an identity assertion.
  - `query` string, required
  - `top_k` integer
  - `as_of` string, date-time
  - `max_context_tokens` integer
  - `entity` string
  - `min_confidence` number
  - `min_memory_version` integer: Monotonic consistency version within one organization/project.
  - `min_primary_wal_lsn` string: Minimum primary WAL position the read must include.
  - `read_consistency` 'default' | 'primary' | 'replica_fallback': `default` routes token-bearing reads to primary and tokenless reads to the read pool. `primary` always uses primary. `replica_fallback` waits briefly on the read pool, then retries against primary.

## Response `200`

Rendered context plus the memories behind it

- RecallResponse
  - `context` string, required: Injection-guarded rendered context for prompting
  - `memories` Memory[], required
    - `id` string, required
    - `content` string, required: Stored content with PII redacted as `[TYPE]` placeholders
    - `user_id` string, nullable, required
    - `epistemic_source` 'user_stated' | 'agent_inferred' | 'third_party', required: Who vouches for the claim. Required on writes.
    - `confidence` number, required
    - `corroboration_count` integer, required
    - `action_relevant` boolean, required
    - `requires_confirmation` boolean, required
    - `confirmed` boolean, required
    - `independent_corroboration` integer, required
    - `injection_suspect` boolean, required
    - `entity_key` string, nullable, required
    - `attribute_key` string, nullable, required
    - `valid_until` string, date-time, nullable, required
    - `superseded_by` string, nullable, required

## Other responses

- `400`: Malformed request or failed validation
- `401`: Missing, malformed, unknown, or revoked API key
- `403`: Authenticated but not allowed (entitlement or billing state)
- `429`: The client IP/project exceeded its request rate, or the project's idempotency retention capacity is full until older keys expire.
- `503`: Memory or metadata store unreachable

---

[API](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api.md) · [All operations](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api/revisions/9e441d2e21a7?raw)