Skip to main content
PUT
/
agents
/
{agent_id}
/
alignment-card
Publish or replace the agent's alignment card
curl --request PUT \
  --url https://api.mnemom.ai/v1/agents/{agent_id}/alignment-card \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "card_version": "<string>",
  "agent_id": "<string>",
  "values": {
    "declared": [
      "<string>"
    ],
    "definitions": {},
    "conflicts_with": [
      "<string>"
    ],
    "hierarchy": "lexicographic"
  },
  "autonomy": {
    "bounded_actions": [
      "<string>"
    ],
    "escalation_triggers": [
      {
        "condition": "<string>",
        "action": "escalate",
        "reason": "<string>"
      }
    ],
    "forbidden_actions": [
      "<string>"
    ],
    "max_autonomous_value": {
      "amount": 123,
      "currency": "<string>"
    }
  },
  "audit": {
    "retention_days": 123,
    "queryable": true,
    "trace_format": "<string>",
    "query_endpoint": "<string>",
    "tamper_evidence": "append_only",
    "storage": {
      "type": "local",
      "location": "<string>"
    }
  },
  "card_id": "<string>",
  "issued_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "integrity": {
    "enforcement_mode": "observe"
  },
  "capabilities": {},
  "enforcement": {
    "forbidden_tools": [
      {
        "pattern": "<string>",
        "reason": "<string>",
        "severity": "critical"
      }
    ],
    "unmapped_tool_action": "allow",
    "fail_open": true,
    "mode": "off",
    "grace_period_hours": 123
  },
  "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>",
  "values": {
    "declared": [
      "<string>"
    ],
    "definitions": {},
    "conflicts_with": [
      "<string>"
    ],
    "hierarchy": "lexicographic"
  },
  "autonomy": {
    "bounded_actions": [
      "<string>"
    ],
    "escalation_triggers": [
      {
        "condition": "<string>",
        "action": "escalate",
        "reason": "<string>"
      }
    ],
    "forbidden_actions": [
      "<string>"
    ],
    "max_autonomous_value": {
      "amount": 123,
      "currency": "<string>"
    }
  },
  "audit": {
    "retention_days": 123,
    "queryable": true,
    "trace_format": "<string>",
    "query_endpoint": "<string>",
    "tamper_evidence": "append_only",
    "storage": {
      "type": "local",
      "location": "<string>"
    }
  },
  "card_id": "<string>",
  "issued_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "principal": {
    "type": "human",
    "relationship": "delegated_authority",
    "identifier": "<string>",
    "escalation_contact": "<string>"
  },
  "conscience": {
    "mode": "augment",
    "values": [
      {
        "type": "BOUNDARY",
        "content": "<string>",
        "id": "<string>",
        "severity": "advisory"
      }
    ]
  },
  "integrity": {
    "enforcement_mode": "observe"
  },
  "capabilities": {},
  "enforcement": {
    "forbidden_tools": [
      {
        "pattern": "<string>",
        "reason": "<string>",
        "severity": "critical"
      }
    ],
    "unmapped_tool_action": "allow",
    "fail_open": true,
    "mode": "off",
    "grace_period_hours": 123
  },
  "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>"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt

Use this file to discover all available pages before exploring further.

Publishes a new alignment card for an agent. The handler validates the card against the AAP schema, composes it with the Platform and Org scopes, and atomically writes the canonical row. This is the canonical UC-4 endpoint that replaced the legacy PATCH /v1/agents/{id}/card, PUT /v1/agents/{id}/policy, and PUT /v1/agents/{id}/cfd/config endpoints (all removed 2026-04-15 — see Unified cards overview).

Required headers

Idempotency-Key: <opaque 24h-unique string>
The handler runs a two-phase reserve / finalize / release on the key. Replays of the same key with the same request body return the cached response. Replays with a different body return 422 Idempotency-Key conflict.

Body shapes

Content-TypeBody
text/yamlRaw YAML card document
application/yamlRaw YAML card document
application/jsonRaw card object, or { "card_yaml": "<yaml string>" }, or { "card_json": {...} }
The card body must include values, autonomy, and commitments blocks at minimum. See the alignment card schema for full requirements.

Side effects

  • Writes a governance_audit_log row before responding (synchronous; failure aborts).
  • Emits the alignment_card.updated webhook event (see Webhooks guide).
  • Triggers recompose of any teams the agent belongs to.

Body size limit

128 KB. Two-layer check (Content-Length, then body length).

See also

Authorizations

Authorization
string
header
required

Supabase JWT token in Authorization: Bearer header

Headers

Idempotency-Key
string
required

Replay key (24 h window).

Path Parameters

agent_id
string
required

Agent identifier (e.g. smolt-abc123)

Body

UC-4 unified alignment card (ADR-008). Authored in YAML or JSON; composed server-side with platform defaults, org template, and active exemptions before storage.

card_version
string
required

Card schema version (e.g. 0.5.0).

agent_id
string
required

Target agent id. On PUT, server overwrites to match the URL path.

values
object
required
autonomy
object
required
audit
object
required
card_id
string

Card row id. Server-assigned on PUT (ac-{uuid}).

issued_at
string<date-time>
expires_at
string<date-time> | null
principal
object
conscience
object
integrity
object
capabilities
object
enforcement
object
extensions
object
_composition
object

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

Response

Card accepted, composed, and stored. Body is the post-composition canonical card.

UC-4 unified alignment card (ADR-008). Authored in YAML or JSON; composed server-side with platform defaults, org template, and active exemptions before storage.

card_version
string
required

Card schema version (e.g. 0.5.0).

agent_id
string
required

Target agent id. On PUT, server overwrites to match the URL path.

values
object
required
autonomy
object
required
audit
object
required
card_id
string

Card row id. Server-assigned on PUT (ac-{uuid}).

issued_at
string<date-time>
expires_at
string<date-time> | null
principal
object
conscience
object
integrity
object
capabilities
object
enforcement
object
extensions
object
_composition
object

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