---
title: "Recall governed memory with exact user-present pass claims"
method: POST
path: "/partner/v1/structured-recall"
---

# Recall governed memory with exact user-present pass claims

`POST /partner/v1/structured-recall`

## Request

- Base URL: `https://passport.ego.ist`
- URL: `https://passport.ego.ist/partner/v1/structured-recall`
- Auth: HTTP bearer

## Request body

- StructuredRecallRequest
  - `categories` string[], required
  - `purpose` 'recall' | 'personalize', required
  - `query` string, nullable
  - `limit` integer: Maximum rows returned independently for each declared category; there is no cross-category budget.
  - `read_id` string, required: Opaque logical-read id. Retries must keep query, category set, purpose, and limit unchanged or receive read_id_conflict; served retries replay only the recorded memory IDs.

## Response `200`

Typed per-category governed recall outcome

- StructuredRecallResponse
  - `outcome` 'ok' | 'approval_required' | 'locked' | 'unavailable' | 'account_unavailable' | 'rate_limited' | 'partial', required
  - `categories` StructuredRecallCategory[], required
    - `category` string, required
    - `outcome` 'results' | 'empty' | 'approval_required' | 'declined' | 'expired' | 'locked' | 'unavailable', required
    - `approval_url` string, uri
    - `approval_expires_at` string, date-time, nullable
    - `rows` StructuredMemoryRow[]
      - `memory_id` string, required
      - `content` string, required
      - `source` string, nullable, required
      - `created_at` string, date-time, nullable, required
      - `occurred_at` string, date-time, nullable, required
      - `category` string, required
      - `client_id` string, nullable, required
      - `evidence_basis` string, nullable, required
      - `record_kind` string, nullable, required
      - `verified_issuer` string, nullable, required
      - `verified_at` string, date-time, nullable, required
  - `request_id` string, uuid
  - `limit_name` string

## Other responses

- `400`: Partner API error. Retry behavior depends on the status and error code.
- `401`: Bearer-token error
- `403`: Partner API error. Retry behavior depends on the status and error code.
- `404`: Partner API error. Retry behavior depends on the status and error code.
- `409`: Partner API error. Retry behavior depends on the status and error code.
- `429`: Structured recall rate limit

---

[API](https://skmtc.dev/ego/apis/ai-passport-partner-api.md) - [All operations](https://skmtc.dev/ego/apis/ai-passport-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ego/apis/ai-passport-partner-api/revisions/d4e46c2809bf?raw)