Skip to main content
Every mutation against the unified card surface is bound by four guarantees. These apply uniformly to alignment-card, protection-card, org-template, and exemption endpoints.

​
1. Schema identity on every response

Every response includes: 
X-Mnemom-Schema: unified/2026-04-15
The value changes when the card surface version changes. A compliance auditor can point at any request/response pair and determine the exact schema that served it without replaying the endpoint.

​
2. Idempotency-Key required on mutations

PUT, POST, and DELETE endpoints require an Idempotency-Key header: 
Idempotency-Key: <opaque 24h-unique string>
Behavior:
  • First request with key K — the mutation executes. The response body, status, and content type are cached for 24 hours keyed by (user, K).
  • Retry with same K, same body — the cached response is returned verbatim; the mutation is NOT re-executed. The replay carries Idempotent-Replay: true.
  • Retry with same K, different body — returns 422 Unprocessable Content with an “Idempotency-Key reused with different inputs” error. Use a new key for a new mutation.
  • Expiry — keys older than 24 hours are pruned by a scheduled job.

​
3. Synchronous governance audit log

Every successful mutation writes exactly one row to governance_audit_log in the same request lifecycle as the mutation itself. The audit row includes:
  • actor_user_id, actor_auth_method, actor_api_key_id?, actor_org_id?
  • action (e.g. alignment_card.put, exemption.granted)
  • target_type + target_id
  • request_id (Cloudflare ray)
  • idempotency_key
  • before_json — canonical state before the mutation (nullable)
  • after_json — canonical state after (nullable on delete)
  • metadata — including the X-Mnemom-Schema value at write time
If the audit write fails, the response returns 500 and the mutation is NOT considered durable. This is by design — we never ship a card change without its audit trail. This log is distinct from the HTTP-request-level api_audit_log (which records every authenticated write). governance_audit_log is the domain-level record used for SOC 2 Article 12 / HIPAA BAA compliance.

​
4. Webhook events on every mutation

Each mutation emits exactly one webhook event via the existing DLQ-backed dispatcher:
ActionEvent type
PUT /v1/alignment/agent/:idalignment_card.updated
PUT /v1/protection/agent/:idprotection_card.updated
PUT /v1/alignment/org/:idorg_alignment_template.updated
DELETE /v1/alignment/org/:idorg_alignment_template.deleted
PUT /v1/protection/org/:idorg_protection_template.updated
DELETE /v1/protection/org/:idorg_protection_template.deleted
POST /v1/agents/:id/exemptionsagent.exemption.granted
DELETE /v1/agents/:id/exemptions/:eidagent.exemption.revoked
Webhook emission is fail-open: if the dispatcher is unavailable, the mutation still succeeds. The governance_audit_log row is the permanent record; the webhook is the notification layer.

​
Exemption grant constraints

Exemptions relax an org-level floor for a specific agent. They are intentionally hard to create:
  • Auth — org owner or admin only, of the agent’s org. Agents without an org cannot have exemptions (no floor to exempt from; their own card is the source of truth).
  • reason — required, minimum 20 characters. Describe why this agent needs to bypass the org floor.
  • expires_at — defaults to now() + 90 days if omitted. Permanent exemptions require explicit opt-in (expires_at: null in the body).
  • Revocation is hard-delete — the governance_audit_log row is the permanent record that an exemption was granted and revoked.

​
API version header

X-Mnemom-Version: 2026-04-15
Present on every response. At current install base we run a single supported version; older version dates are no longer deprecated through this header because the legacy endpoints were deleted rather than deprecated. See API versioning for the deprecation doctrine that applies once there is a non-zero external install base.