---
title: "Load Guardrails"
method: POST
path: "/api/v1/memory/guardrails"
tags: ["memory"]
---

# Load Guardrails

`POST /api/v1/memory/guardrails`

## 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/guardrails`
- Auth: none declared

Deterministically load a context's guardrail set for a client-side hook.

The REST twin of the MCP ``load_guardrails`` tool and ``/pinned``'s
sibling: the trusted-tier pinned set (``delivery_mode='always'``) plus the
memories marked with ``details.tool_trigger``, each list ordered
``importance DESC, created_at ASC, id ASC`` and capped on its own
(``cap`` bounds ``tool_triggered`` only; the pinned list uses
``settings.pinned_load_cap``). Plain SQL — no ranking, no rerank. Items are
L1 (+ L2 on pinned items) and carry the normalized ``tool_trigger`` object
as data; the server never runs the patterns. The response's ``format`` and
``version`` are the shared cache contract documented with the MCP tool.

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

Example:
    POST /api/v1/memory/guardrails
    Authorization: Bearer <api_key>

## Headers

- `authorization` string, nullable

## Request body

- LoadGuardrailsRequest: Request for the deterministic guardrail-set read (``POST /memory/guardrails``). ``cap`` bounds the tool-triggered list only (``settings.guardrail_load_cap`` default); the pinned list is bounded by ``settings.pinned_load_cap`` so a large pinned set can never crowd guardrails out of a capped response.
  - `context_id` string, nullable: Context UUID whose guardrail set to load
  - `cap` integer, nullable: Optional override for the max tool-triggered memories returned (bounded)

## Response `200`

Successful Response

- LoadGuardrailsResponse: Response for the deterministic guardrail-set read (docs/mcp-tools.md § Tool guardrails). Two independently capped lanes: ``pinned`` (``delivery_mode='always'``, trusted tier, ``pinned_load_cap``) and ``tool_triggered`` (``details.tool_trigger`` present, trusted tier, ``cap``). A memory that is both appears in both lists (clients dedupe by ``memory_id``). Each list is in the canonical order ``importance DESC, created_at ASC, id ASC``. ``total_available`` / ``truncated`` / ``cap`` keep the single top-level meaning (sum / either-lane / the tool-triggered cap); the per-lane fields say which protection is incomplete. ``format`` is the shared cache/payload format version (additive fields never bump it); ``version`` is the per-credential hash of the served entries, opaque to clients.
  - `status` string
  - `format` integer, required
  - `version` string, required
  - `pinned` GuardrailItem[], required
    - `memory_id` unknown, required
    - `summary` unknown, required
    - `context_summary` unknown
    - `type` unknown, required
    - `importance` unknown, required
    - `delivery_mode` unknown, required
    - `tool_trigger` unknown
    - `source_type` unknown, required
    - `authored_by_caller` unknown, required
    - `created_at` unknown, required
    - `updated_at` unknown, required
  - `tool_triggered` GuardrailItem[], required
    - `memory_id` unknown, required
    - `summary` unknown, required
    - `context_summary` unknown
    - `type` unknown, required
    - `importance` unknown, required
    - `delivery_mode` unknown, required
    - `tool_trigger` unknown
    - `source_type` unknown, required
    - `authored_by_caller` unknown, required
    - `created_at` unknown, required
    - `updated_at` unknown, required
  - `total_available` integer, required
  - `truncated` boolean, required
  - `cap` integer, required
  - `pinned_cap` integer, required
  - `pinned_total_available` integer, required
  - `pinned_truncated` boolean, required
  - `tool_triggered_total_available` integer, required
  - `tool_triggered_truncated` boolean, 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/aa9df1a21db9?raw)