---
title: "Runtime composite — alignment + protection + capabilities in one call"
method: GET
path: "/agents/{agent_id}/state"
tags: ["Agents"]
---

# Runtime composite — alignment + protection + capabilities in one call

`GET /agents/{agent_id}/state`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/agents/{agent_id}/state`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Mnemom-Api-Key`
  - API key in cookie `mnemom_session`

Returns the agent's complete operational envelope as a single response: composed alignment card, composed protection card, and a `capabilities[]` array of full tool definitions (from the W1.1 tools registry — `{name, class, domain, description, schema, source_connector, grant_provenance}`, NOT bare name strings). SDK consumers (first-party SDKs, future Tier-1 customers, OSC instances) call this instead of assembling the envelope client-side. ETag-driven 304 short-circuit; `Cache-Control: private, max-age=60`. cards-as-primitive Phase 4 W2.3.

## Path parameters

- `agent_id` string, required

## Response `200`

Runtime state envelope.

- object
  - `alignment` UnifiedAlignmentCard, required: Unified alignment card (ADR-008/ADR-039). Authored in YAML or JSON; composed server-side with platform defaults, org template, and active exemptions before storage. This schema matches the runtime validator at src/composition/validate.ts EXACTLY — a card authored strictly to it passes `PUT /v1/agents/{id}/alignment-card` and the preview-compose endpoint. Output-only fields (card_id, issued_at, expires_at, _composition, content_hash, version) are server-assigned and must NOT be sent on a PUT.
    - `card_version` string, required: Card schema version (required, non-empty). Current canonical value: `unified/2026-04-26`.
    - `content_version` string: Optional. Which default content the card carries, e.g. `mnemom-agent-default/2.1.0` (semver within a lineage). Distinct from `card_version`, the schema version. New agents are born with it; composition carries the agent card's value onto the canonical card.
    - `autonomy_mode` 'off' | 'observe' | 'nudge' | 'enforce', required: ADR-039 master switch for the action-policing pipeline (autonomy constraints). Required at the top level post-cutover; the legacy `enforcement.mode` location is rejected.
    - `integrity_mode` 'off' | 'observe' | 'nudge' | 'enforce', required: ADR-039 master switch for the values/conscience pipeline (integrity constraints). Required at the top level post-cutover; the legacy `integrity.enforcement_mode` location is rejected.
    - `card_id` string: Card row id. Server-assigned on PUT (`ac-{uuid}`).
    - `agent_id` string, required: Target agent id. On PUT, server overwrites to match the URL path.
    - `issued_at` string, date-time
    - `expires_at` string, date-time, nullable
    - `principal` object, required: Required object describing whose authority the agent acts under (ADR-039 Decision 10).
      - `type` 'human' | 'organization' | 'agent' | 'unspecified', required
      - `identifier` string: Required (non-empty) when principal.type is not `unspecified`; identifies the human / organization / agent.
      - `relationship` 'delegated_authority' | 'advisory' | 'autonomous', required
      - `escalation_contact` string
    - `values` object, required
      - `declared` union[], required: Ordered list of declared values. Phase 1 cards-as-primitive: each entry is either a catalog-v1 ID string (e.g. `'accuracy'`) or a parameterized map carrying optional `intensity` / `domain` / `severity_on_violation` / `scope` (e.g. `{id: 'accuracy', domain: 'financial', severity_on_violation: 'critical'}`).
        - union
          - string
          - object
            - `id` string, required
      - `definitions` object
      - `conflicts_with` string[]
      - `hierarchy` 'lexicographic' | 'weighted' | 'contextual'
    - `conscience` object
      - `mode` 'augment' | 'replace', required
      - `values` object[], required
        - `type` 'BOUNDARY' | 'FEAR' | 'COMMITMENT' | 'BELIEF' | 'HOPE', required
        - `content` string, required
        - `id` string
        - `severity` 'advisory' | 'mandatory'
    - `autonomy` object, required
      - `bounded_actions` string[], required
      - `forbidden_actions` string[]
      - `escalation_triggers` object[]
        - `condition` string, required
        - `action` 'escalate' | 'deny' | 'log', required
        - `reason` string, required
      - `max_autonomous_value` object
        - `amount` number
        - `currency` string
    - `capabilities` object
    - `enforcement` object: Optional ADR-039 Decision-3 user-facing knobs for unmapped-tool handling. The legacy `mode`, `unmapped_tool_action` and `fail_open` keys are REJECTED by the validator (mode → top-level autonomy_mode; fail_open → gateway env config).
      - `allow_unmapped_tools` boolean: When true, tools not mapped to a capability are allowed by default.
      - `default_unmapped_severity` 'low' | 'medium' | 'high' | 'critical': Severity assigned to an unmapped tool when allow_unmapped_tools is false.
      - `forbidden_tools` object[]
        - `pattern` string, required
        - `reason` string, required
        - `severity` 'critical' | 'high' | 'medium' | 'low', required
      - `grace_period_hours` integer
    - `audit` object, required
      - `trace_format` string
      - `retention_days` integer, required
      - `queryable` boolean, required
      - `query_endpoint` string: Required when audit.queryable is true.
      - `tamper_evidence` 'append_only' | 'signed' | 'merkle' | 'null', nullable
      - `storage` object
        - `type` 'local' | 'remote' | 'distributed'
        - `location` string
    - `extensions` object
    - `_composition` CompositionMetadata: System-managed block describing which scope sources merged into the canonical card. Only returned when `?include_composition=true`.
      - `canonical_id` string
      - `composed_at` string, date-time
      - `scopes_applied` object[]
        - `scope` string: `platform`, `org:<id>`, or `agent:<id>`.
        - `version` integer
        - `template_version` integer
        - `card_id` string
      - `exemptions_applied` string[]
      - `source_card_id` string
      - `source_policy_id` string
    - `content_hash` string: Response-only: content hash of the composed card (`sha256:<hex>`), injected by the GET/PUT response. Server-assigned — do not send on a PUT.
    - `version` integer: Response-only: monotonic card version, injected by the GET/PUT response. Server-assigned — do not send on a PUT.
  - `protection` UnifiedProtectionCard, required: 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
    - `content_version` string: Optional. Which default content the card carries, e.g. `mnemom-agent-default/2.1.0` (semver within a lineage). Distinct from `card_version`, the schema version. New agents are born with it; composition carries the agent card's value onto the canonical card.
    - `card_id` string
    - `agent_id` string, required
    - `issued_at` string, date-time
    - `expires_at` string, date-time, nullable
    - `mode` 'off' | 'observe' | 'nudge' | 'enforce', required: Strictest-wins composition: enforce > nudge > observe > off.
    - `thresholds` object, required: Score bands. Must satisfy warn <= quarantine <= block; each value in [0, 1].
      - `warn` number, required
      - `quarantine` number, required
      - `block` number, required
    - `screen_surfaces` object, required: Which request surfaces Safe House inspects. Composed across scopes by OR-per-field (any scope requiring inspection wins).
      - `incoming` boolean, required: The user/principal prompt entering the agent.
      - `outgoing` boolean, required: The agent's response leaving the agent.
      - `tool_calls` boolean, required: Tool-use invocations the agent makes.
      - `tool_responses` boolean, required: Responses to tool calls returning to the agent.
    - `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.
      - `domains` string[], required: DNS names or host:port entries.
      - `agent_ids` string[], required: Mnemom agent IDs (mnm-* / smolt-* prefixed).
      - `ip_ranges` string[], required: IPv4 or IPv6 CIDR ranges.
    - `protected_surface` object: Org-declared protected surface policy (MNE-830). Strengthen-only UNION across platform → org → team → agent: each scope may add entries; none may remove. The composer always emits this block; callers omit it to inherit the composed floor. See ADR-037 §protected_surface.
      - `assets` object[]: Protected assets. Intrinsic identity = `${kind}:${selector}` (normalized). Composer merges by identity, keeping the strictest entry per scope.
        - `kind` string, required: Asset kind (e.g. `row`, `field`, `resource`, `table`).
        - `selector` string, required: Asset selector (e.g. `customer:critical-0000`, `replica_dsn`).
        - `label` string: Human-facing display label (optional).
        - `reason` string: Why this asset is protected (optional).
        - `source_scope` string: Composer-assigned provenance (`platform`, `org:<id>`, `team:<id>`, `agent:<id>`). Server-assigned — do not send on a PUT.
      - `forbidden_operations` object[]: Operations that are unconditionally forbidden. Intrinsic identity = normalized `pattern`. Composer unions across scopes; on identity collision, severity → max.
        - `pattern` string, required: Operation pattern (e.g. `TRUNCATE`, `unscoped UPDATE/DELETE`, `exfiltrate:pii`).
        - `applies_to` string[]: Asset identities (`${kind}:${selector}`) this operation applies to. Empty/absent means GLOBAL.
        - `severity` 'low' | 'medium' | 'high' | 'critical': Severity level. Composer merges to strictest across scopes.
        - `reason` string: Why this operation is forbidden (optional).
        - `source_scope` string: Composer-assigned provenance. Server-assigned — do not send on a PUT.
      - `escalation_required` object[]: Operations that require escalation before proceeding. Same intrinsic-identity + union rules as forbidden_operations (minus severity).
        - `pattern` string, required: Operation pattern requiring escalation.
        - `applies_to` string[]: Asset identities this escalation applies to. Empty/absent = GLOBAL.
        - `reason` string: Why escalation is required (optional).
        - `source_scope` string: Composer-assigned provenance. Server-assigned — do not send on a PUT.
    - `review` object: Review-hold policy (Safe House Review, Slice 2a — MNE-920 design). gate_on is the minimum verdict band per surface that escalates to a review-hold. Composition is strictest-wins; on_timeout defaults to 'reject' (fail-closed). reviewer.kind 'endpoint' is designed for MNE-1650 and not consumed yet.
      - `enabled` boolean, required
      - `gate_on` object
        - `incoming` 'off' | 'warn' | 'quarantine' | 'block'
        - `outgoing` 'off' | 'warn' | 'quarantine' | 'block'
        - `tool_calls` 'off' | 'warn' | 'quarantine' | 'block'
        - `tool_responses` 'off' | 'warn' | 'quarantine' | 'block'
        - `integrity` 'off' | 'review_needed' | 'boundary_violation'
      - `sla_seconds` number
      - `on_timeout` 'reject' | 'release'
      - `notify` object
        - `sse` boolean
        - `webhooks` boolean
      - `reviewer` object
        - `kind` 'builtin_opus' | 'endpoint', required
        - `endpoint_url` string, uri
      - `quarantine_notice` string
    - `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` CompositionMetadata: System-managed block describing which scope sources merged into the canonical card. Only returned when `?include_composition=true`.
      - `canonical_id` string
      - `composed_at` string, date-time
      - `scopes_applied` object[]
        - `scope` string: `platform`, `org:<id>`, or `agent:<id>`.
        - `version` integer
        - `template_version` integer
        - `card_id` string
      - `exemptions_applied` string[]
      - `source_card_id` string
      - `source_policy_id` string
    - `content_hash` string: Response-only: content hash of the composed card (`sha256:<hex>`), injected by the GET/PUT response. Server-assigned — do not send on a PUT.
    - `version` integer: Response-only: monotonic card version, injected by the GET/PUT response. Server-assigned — do not send on a PUT.
  - `capabilities` object[], required
    - `name` string, required
    - `display_name` string, nullable
    - `description` string, nullable
    - `class` string, required
    - `domain` string, required
    - `schema` object, nullable
    - `source_connector` string, nullable
    - `grant_provenance` object, required
      - `layer` 'platform' | 'org' | 'team' | 'agent' | 'derived', required
      - `layer_id` string
      - `kind` string
  - `content_hash` string, required
  - `version` integer, required
  - `composed_at` string, date-time, required
  - `expires_at` string, date-time, required

## Other responses

- `304`: Not Modified — the client's `If-None-Match` matches the current combined ETag.
- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Resource not found
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.

---

[API](https://skmtc.dev/mnemom/apis/mnemom-api.md) · [All operations](https://skmtc.dev/mnemom/apis/mnemom-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemom/apis/mnemom-api/revisions/274b7a6ea182?raw)