Skip to main content
PUT
/
protection
/
agent
/
{agent_id}
Publish or replace the protection manifest
curl --request PUT \
  --url https://api.mnemom.ai/v1/protection/agent/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "card_version": "<string>",
  "agent_id": "<string>",
  "thresholds": {
    "warn": 0.5,
    "quarantine": 0.5,
    "block": 0.5
  },
  "screen_surfaces": {
    "incoming": true,
    "outgoing": true,
    "tool_calls": true,
    "tool_responses": true
  },
  "trusted_sources": {
    "domains": [
      "<string>"
    ],
    "agent_ids": [
      "<string>"
    ],
    "ip_ranges": [
      "<string>"
    ]
  },
  "card_id": "<string>",
  "issued_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "extensions": {},
  "_composition": {
    "canonical_id": "<string>",
    "composed_at": "2023-11-07T05:31:56Z",
    "scopes_applied": [
      {
        "scope": "<string>",
        "version": 123,
        "template_version": 123,
        "card_id": "<string>"
      }
    ],
    "exemptions_applied": [
      "<string>"
    ],
    "source_card_id": "<string>",
    "source_policy_id": "<string>"
  }
}
'
{
  "card_version": "<string>",
  "agent_id": "<string>",
  "thresholds": {
    "warn": 0.5,
    "quarantine": 0.5,
    "block": 0.5
  },
  "screen_surfaces": {
    "incoming": true,
    "outgoing": true,
    "tool_calls": true,
    "tool_responses": true
  },
  "trusted_sources": {
    "domains": [
      "<string>"
    ],
    "agent_ids": [
      "<string>"
    ],
    "ip_ranges": [
      "<string>"
    ]
  },
  "card_id": "<string>",
  "issued_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "extensions": {},
  "_composition": {
    "canonical_id": "<string>",
    "composed_at": "2023-11-07T05:31:56Z",
    "scopes_applied": [
      {
        "scope": "<string>",
        "version": 123,
        "template_version": 123,
        "card_id": "<string>"
      }
    ],
    "exemptions_applied": [
      "<string>"
    ],
    "source_card_id": "<string>",
    "source_policy_id": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Supabase JWT token in Authorization: Bearer header

Headers

​
Idempotency-Key
string
required

Client-supplied idempotency token. Replays within 24 hours return the stored result. See ADR-023.

Required string length: 1 - 128
​
If-Match
string

Optional optimistic-concurrency token. Pass the ETag from a recent GET ("sha256:<hex64>" shape) to make the write conditional: a stale ETag returns 412 Precondition Failed, a malformed one 400. Omit it to publish unconditionally.

Pattern: ^"sha256:[0-9a-f]{64}"$

Path Parameters

​
agent_id
string
required

Agent identifier (e.g. smolt-abc123)

Body

Unified protection card (ADR-037). Safe House thresholds + trusted-source policy for a single agent. Shape matches src/composition/types.ts::UnifiedProtectionCard (canonical) and what the runtime validator at src/composition/validate.ts accepts. The customer-facing docs at /concepts/protection-card and /specifications/protection-card-schema document this same shape.

​
card_version
string
required
​
agent_id
string
required
​
mode
enum<string>
required

Strictest-wins composition: enforce > nudge > observe > off.

Available options:
off,
observe,
nudge,
enforce
​
thresholds
object
required

Score bands. Must satisfy warn <= quarantine <= block; each value in [0, 1].

​
screen_surfaces
object
required

Which request surfaces Safe House inspects. Composed across scopes by OR-per-field (any scope requiring inspection wins).

​
trusted_sources
object
required

Sources for which detectors short-circuit (each match logged in the trace). Composed as platform->agent intersection (compliance ceiling) with org+agent union inside that ceiling — an agent cannot widen trust beyond what the platform allows.

​
card_id
string
​
issued_at
string<date-time>
​
expires_at
string<date-time> | null
​
extensions
object

Free-form extension slot for non-canonical fields. Ignored by the composer; preserved on read for tooling that needs an audit-tail metadata bag.

​
_composition
object

System-managed block describing which scope sources merged into the canonical card. Only returned when ?include_composition=true.

Response

Composed canonical card after the write.

Unified protection card (ADR-037). Safe House thresholds + trusted-source policy for a single agent. Shape matches src/composition/types.ts::UnifiedProtectionCard (canonical) and what the runtime validator at src/composition/validate.ts accepts. The customer-facing docs at /concepts/protection-card and /specifications/protection-card-schema document this same shape.

​
card_version
string
required
​
agent_id
string
required
​
mode
enum<string>
required

Strictest-wins composition: enforce > nudge > observe > off.

Available options:
off,
observe,
nudge,
enforce
​
thresholds
object
required

Score bands. Must satisfy warn <= quarantine <= block; each value in [0, 1].

​
screen_surfaces
object
required

Which request surfaces Safe House inspects. Composed across scopes by OR-per-field (any scope requiring inspection wins).

​
trusted_sources
object
required

Sources for which detectors short-circuit (each match logged in the trace). Composed as platform->agent intersection (compliance ceiling) with org+agent union inside that ceiling — an agent cannot widen trust beyond what the platform allows.

​
card_id
string
​
issued_at
string<date-time>
​
expires_at
string<date-time> | null
​
extensions
object

Free-form extension slot for non-canonical fields. Ignored by the composer; preserved on read for tooling that needs an audit-tail metadata bag.

​
_composition
object

System-managed block describing which scope sources merged into the canonical card. Only returned when ?include_composition=true.