---
title: "Trusted, action-relevant memory only"
method: POST
path: "/v1/recall_for_action"
tags: ["decisions"]
---

# Trusted, action-relevant memory only

`POST /v1/recall_for_action`

## Request

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

An advisory pre-action evaluation. Records and returns a durable
`decision_id`, explicit `act` / `ask` / `abstain` outcome, trusted
memories, and pending confirmation IDs. The host uses the decision ID
to report its terminal outcome through `/v1/receipts`, and must enforce
the result itself. Confirmation is one policy signal, not the only path
to `act`, and it does not prove objective truth.

## Request body

- RecallForActionRequest: Pass the entity and attribute the action needs, for example user and email, so only current memory in that slot can yield act or ask. Without them, any trusted memory the query retrieves yields act, whether or not it answers the request. entity and attribute must be set together (400 otherwise).
  - `user_id` string, required: End-user memory partition key. Not an identity assertion.
  - `query` string, required
  - `top_k` integer
  - `entity` string
  - `attribute` string

## Response `200`

Durable action decision and its receipt target

- RecallForActionResponse
  - `decision_id` string, uuid, required: Durable receipt target for this action evaluation
  - `outcome` 'act' | 'ask' | 'abstain', required
  - `memories` Memory[], required: Trusted memories; populated only for an act outcome
    - `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
  - `pending_confirmation_ids` string[], required: Memories that caused an ask outcome

## 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)