---
title: "Load Pinned"
method: POST
path: "/api/v1/memory/pinned"
tags: ["memory"]
---

# Load Pinned

`POST /api/v1/memory/pinned`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/memory/pinned`
- Auth: none declared

Deterministically load a context's always-delivery memories (Issue #886).

The deterministic counterpart to ``/recall``: returns the complete,
unranked, ordered ``delivery_mode='always'`` set for the given context —
no semantic ranking, no rerank. Items carry L1 + L2 only (summary +
context_summary); fetch full content via ``/reference``. Bounded by
``settings.pinned_load_cap`` (or the request ``cap``); when the pinned set
exceeds the cap, ``truncated`` is true and ``total_available`` reports the
real count — never a silent truncation.

Request:
    {"context_id": "<context-uuid>", "cap": 100}

Example:
    POST /api/v1/memory/pinned
    Authorization: Bearer <session_token>

## Headers

- `authorization` string, nullable

## Request body

- LoadPinnedRequest: Request for the deterministic always-load read path (Issue #886). ``context_id`` selects which context's always-load set to return (the set is per-context). ``cap`` optionally overrides ``settings.pinned_load_cap``.
  - `context_id` string, nullable: Context UUID whose pinned memories to load
  - `cap` integer, nullable: Optional override for the max returned (bounded)

## Response `200`

Successful Response

- LoadPinnedResponse: Response for the deterministic always-load read path (Issue #886). ``memories`` is the complete, unranked, ordered set up to ``cap``. When the context holds more pinned memories than ``cap``, ``truncated`` is true and ``total_available`` reports the real count — the set is never silently cut.
  - `status` string
  - `memories` PinnedMemoryItem[], required
    - `memory_id` unknown, required
    - `summary` unknown, required
    - `context_summary` unknown, required
    - `type` unknown, required
    - `importance` unknown, required
    - `delivery_mode` unknown, required
    - `created_at` unknown, required
  - `total_available` integer, required
  - `truncated` boolean, required
  - `cap` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)