> ## 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. # Publish or replace the protection manifest > Accepts YAML (text/yaml, application/yaml) or JSON. ## OpenAPI ````yaml PUT /protection/agent/{agent_id} openapi: 3.1.0 info: title: Mnemom API description: >- Trust infrastructure for AI agents. Transparent alignment verification, behavioral drift detection, and accountability primitives. version: 1.0.0 contact: name: Mnemom url: https://mnemom.ai email: support@mnemom.ai license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://api.mnemom.ai/v1 description: Production security: - BearerAuth: [] - ApiKeyAuth: [] tags: - name: A2A description: >- Public A2A AgentCard projection of the canonical alignment card, with embedded AAP attestation extension (cards-as-primitive Phase 5). - name: Agents description: Agent registration, lifecycle, and metadata. - name: Agent Containment description: Containment policies and quarantine controls. - name: Agent Groups description: >- Lightweight logical tags for bucketing an org's agents — the unscored counterpart to the scored Teams primitive. No cards, coherence, reputation, or feature gate. - name: Alignment description: >- Alignment manifest CRUD — canonical `/v1/alignment//` surface across platform / org / team / agent (cards-as-primitive Phase 4). - name: Analyze description: Behavioral analysis endpoints. - name: Aletheia Support description: >- In-product Aletheia assistant MVP (issue #2195) — chat + voice adapters over one shared answer core. Gated behind ALETHEIA_SUPPORT_MVP_ENABLED + the ALETHEIA_SUPPORT_ALLOWLIST identity allowlist (whose default is the whole @mnemom.ai domain, and which may be set to "*" to admit every authenticated identity), fail-closed 404 for every non-allowed caller. Dark by default; whether it is customer-facing depends on that env var per deployment. - name: Attestation description: >- AAP attestation token JWKS surface and platform-admin signing-key rotation (cards-as-primitive Phase 5). - name: Auth description: Authentication, sessions, and access management. - name: Billing description: Subscription, usage, and invoicing. - name: Blog description: Public blog content. - name: Card Templates description: Org-level alignment and protection card templates. - name: Catalog description: >- Discovery surface for the 25-entry Mnemom value catalog v1 (cards-as-primitive Phase 4). - name: Checkpoints description: Integrity checkpoints and proof artifacts. - name: Conscience Values description: Org-level conscience-value configuration. - name: Consent description: >- GDPR Art. 7(1) append-only consent audit log (MNE-477). Public write (banner POSTs each decision); admin-only read/export. Stores a pseudonymous subject id + truncated IP only — in addition to client-side enforcement. - name: Domains description: >- Domain ownership claims (DNS-TXT verified) + the public no-PII claim-status projection. - name: MCP Servers description: >- MCP-server ownership claims (DNS-TXT verified on the origin domain) + the public no-PII claim-status projection for the IITR MCP-readiness rubric. - name: Dojo description: >- Dojo demo shared contracts (MNE-517): SimEvent SSE narrative feed + ephemeral compute-key issuance. Internal/demo surface, not customer-facing. - name: Invite Message Template description: >- Admin-only (mnemom_staff) CRUD over the invite composer's saved, reusable invite copy (MNE-7094, 5/8 of the RG invite-permission-product epic MNE-7089). Internal/staff surface, not customer-facing. - name: Code description: >- Mnemom Agent — the governed agent launcher (`mnemom agent`). The per-org feature gate the CLI checks at startup; invites and access reuse the product-invite surface with product `code`. - name: Invites description: >- Invitee-facing product-invite redemption (MNE-7166, 6/8 of the RG invite-permission-product epic MNE-7089). Accepting a `pinv_…` token grants product access and forwards a server-owned starter grant; the grant amount is admin-only and never surfaced. - name: Coherence description: >- Coherence report-claim round-trip (MNE-1379): single-use claim-intent tickets that carry a report claim across the sign-up/email-confirm/return round-trip so no session token rides the URL — only the opaque `mci_…` ticket. - name: Drift description: Drift detection and resolution. - name: Enforcement description: Enforcement-mode configuration and queries. - name: Governance description: Operator-actionable governance signals (ADR-048). - name: Integrity description: AIP integrity checkpoints and verdicts. - name: Intelligence description: Intelligence reports and queries. - name: Licensing description: License management. - name: Network description: >- Protection Network L4 thermometer read surface. Public-aggregate disclosure: any authenticated principal may read; rows carry no per-tenant identifiers. - name: OAuth description: >- OAuth 2.1 authorization-code + PKCE flow for MCP clients (MNE-328). Identity delegated to Supabase GoTrue; mnemom-api mints its own short-lived MCP-scoped tokens. Includes RFC 7591 dynamic client registration and RFC 7009 revocation. - name: On-Chain description: On-chain verification and proofs. - name: Onboarding description: >- Onboarding guidance generation (MNE-5508) — LLM-driven step guidance + bounded action suggestions for customers completing onboarding checklists. - name: Organizations description: Org-level resources and management. - name: Policy description: Policy evaluation and configuration. - name: Postures description: Trust posture management (ADR-045). - name: Protection description: >- Protection manifest CRUD — canonical `/v1/protection//` surface across platform / org / team / agent (cards-as-primitive Phase 4). - name: Recipes description: >- Customer-facing detection-recipe surface — FN/FP reports. Distinct from the Admin recipe-promotion surface and the Internal seeding surface. - name: Reclassification description: Reclassification workflows. - name: Reputation description: Per-agent reputation scores. - name: Risk description: Risk assessment endpoints. - name: Safe House description: Safe House threat detection and quarantine. - name: Sideband description: Sideband detection queries (legacy; sunsetting). - name: Team Reputation description: Team-level reputation aggregates. - name: Teams description: Team-scope resources. - name: Tools description: >- Mnemom-side tools registry — per-tool class+domain+schema metadata (cards-as-primitive Phase 4). - name: Telemetry description: >- Public browser-RUM ingest (Core Web Vitals). Anon-eligible by design, rate-limited, closed-enum dimensions only — emits spans, persists nothing. - name: Traces description: AP-Trace artifacts and queries. - name: Transparency description: >- Append-only public log of every canonical card identity ever composed. Signed Merkle root + per-row inclusion proofs (cards-as-primitive Phase 5). - name: Trust description: >- Protection Network L5 public-trust surface — security advisories, IoC feed (STIX 2.1), and platform-admin CMS for both. - name: Mu description: >- mu-engine ledger proxy — thin pass-through to the mnemom-mu Worker (balances, budgets, staff reads). api owns auth/RBAC/org-context; the ledger lives in mnemom-mu (issue #2357). - name: Verification description: Trace verification endpoints. - name: Webhook Notifications description: Webhook event subscription management. - name: Webhooks description: Webhook delivery and lifecycle. - name: Misc description: >- Miscellaneous operator-facing endpoints (contact, enterprise inquiries, compliance). - name: Feedback description: >- Authenticated in-product feedback ingest (Aletheia Customer Voice). Redacted + consent-gated + idempotent. - name: Notifications description: >- Reactive notification channels — SSE stream + signed-webhook subscriptions for canonical card changes (cards-as-primitive Phase 5). - name: Presentations description: >- Investor/data-room presentations + per-viewer grants (MNE-1428, "Inside Mnemom"). Admin create/invite/revoke; authed-user read scoped to active grants. Internal/demo surface, not customer-facing. - name: Aletheia description: >- Aletheia grounded Q&A answer core (MNE-1937). Internal/preview surface, not customer-facing. - name: AletheiaVoice description: >- In-product Aletheia voice register (MNE-1944), the customer/anon sibling of the Presentations deck voice register. DARK: feature-flag + allowlist gated, zero customer exposure until promoted; cookie/bearer-authed like any other customer route. paths: /protection/agent/{agent_id}: put: tags: - Protection summary: Publish or replace the protection manifest description: >- Accepts YAML (`text/yaml`, `application/yaml`) or JSON. Body is the full `UnifiedProtectionCard`; server-side composition merges it across the platform → org → team → agent cascade and writes the canonical composed card. Requires `Idempotency-Key`. Honors an optional `If-Match` for optimistic concurrency (stale → 412). Body cap 128 KiB. See ADR-008 and ADR-023. operationId: putProtectionByAgent parameters: - $ref: '#/components/parameters/AgentId' - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 description: >- Client-supplied idempotency token. Replays within 24 hours return the stored result. See ADR-023. - name: If-Match in: header required: false schema: type: string pattern: ^"sha256:[0-9a-f]{64}"$ description: >- Optional optimistic-concurrency token. Pass the `ETag` from a recent `GET` (`"sha256:"` shape) to make the write conditional: a stale ETag returns `412 Precondition Failed`, a malformed one `400`. Omit it to publish unconditionally. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UnifiedProtectionCard' application/yaml: schema: $ref: '#/components/schemas/UnifiedProtectionCard' text/yaml: schema: $ref: '#/components/schemas/UnifiedProtectionCard' responses: '200': description: Composed canonical card after the write. headers: ETag: description: '`"sha256:"` of the new canonical body.' schema: type: string X-Card-Version: description: Bumped monotonically on every PUT that changes content_hash. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/UnifiedProtectionCard' text/yaml: schema: $ref: '#/components/schemas/UnifiedProtectionCard' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '412': $ref: '#/components/responses/PreconditionFailed' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] - ApiKeyAuth: [] - CookieAuth: [] components: parameters: AgentId: name: agent_id in: path required: true schema: type: string description: Agent identifier (e.g. smolt-abc123) schemas: UnifiedProtectionCard: type: object description: >- 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. required: - card_version - agent_id - mode - thresholds - screen_surfaces - trusted_sources properties: card_version: type: string card_id: type: string agent_id: type: string issued_at: type: string format: date-time expires_at: type: - string - 'null' format: date-time mode: type: string enum: - 'off' - observe - nudge - enforce description: 'Strictest-wins composition: enforce > nudge > observe > off.' thresholds: type: object description: >- Score bands. Must satisfy warn <= quarantine <= block; each value in [0, 1]. required: - warn - quarantine - block properties: warn: type: number minimum: 0 maximum: 1 quarantine: type: number minimum: 0 maximum: 1 block: type: number minimum: 0 maximum: 1 screen_surfaces: type: object description: >- Which request surfaces Safe House inspects. Composed across scopes by OR-per-field (any scope requiring inspection wins). required: - incoming - outgoing - tool_calls - tool_responses properties: incoming: type: boolean description: The user/principal prompt entering the agent. outgoing: type: boolean description: The agent's response leaving the agent. tool_calls: type: boolean description: Tool-use invocations the agent makes. tool_responses: type: boolean description: Responses to tool calls returning to the agent. trusted_sources: type: object description: >- 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. required: - domains - agent_ids - ip_ranges properties: domains: type: array items: type: string description: DNS names or host:port entries. agent_ids: type: array items: type: string description: Mnemom agent IDs (mnm-* / smolt-* prefixed). ip_ranges: type: array items: type: string description: IPv4 or IPv6 CIDR ranges. protected_surface: type: object description: >- 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. properties: assets: type: array description: >- Protected assets. Intrinsic identity = `${kind}:${selector}` (normalized). Composer merges by identity, keeping the strictest entry per scope. items: type: object required: - kind - selector properties: kind: type: string description: Asset kind (e.g. `row`, `field`, `resource`, `table`). selector: type: string description: >- Asset selector (e.g. `customer:critical-0000`, `replica_dsn`). label: type: string description: Human-facing display label (optional). reason: type: string description: Why this asset is protected (optional). source_scope: type: string description: >- Composer-assigned provenance (`platform`, `org:`, `team:`, `agent:`). Server-assigned — do not send on a PUT. forbidden_operations: type: array description: >- Operations that are unconditionally forbidden. Intrinsic identity = normalized `pattern`. Composer unions across scopes; on identity collision, severity → max. items: type: object required: - pattern properties: pattern: type: string description: >- Operation pattern (e.g. `TRUNCATE`, `unscoped UPDATE/DELETE`, `exfiltrate:pii`). applies_to: type: array items: type: string description: >- Asset identities (`${kind}:${selector}`) this operation applies to. Empty/absent means GLOBAL. severity: type: string enum: - low - medium - high - critical description: >- Severity level. Composer merges to strictest across scopes. reason: type: string description: Why this operation is forbidden (optional). source_scope: type: string description: >- Composer-assigned provenance. Server-assigned — do not send on a PUT. escalation_required: type: array description: >- Operations that require escalation before proceeding. Same intrinsic-identity + union rules as forbidden_operations (minus severity). items: type: object required: - pattern properties: pattern: type: string description: Operation pattern requiring escalation. applies_to: type: array items: type: string description: >- Asset identities this escalation applies to. Empty/absent = GLOBAL. reason: type: string description: Why escalation is required (optional). source_scope: type: string description: >- Composer-assigned provenance. Server-assigned — do not send on a PUT. review: type: object description: >- 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. required: - enabled properties: enabled: type: boolean gate_on: type: object properties: incoming: type: string enum: - 'off' - warn - quarantine - block outgoing: type: string enum: - 'off' - warn - quarantine - block tool_calls: type: string enum: - 'off' - warn - quarantine - block tool_responses: type: string enum: - 'off' - warn - quarantine - block integrity: type: string enum: - 'off' - review_needed - boundary_violation sla_seconds: type: number minimum: 1 on_timeout: type: string enum: - reject - release notify: type: object properties: sse: type: boolean webhooks: type: boolean reviewer: type: object required: - kind properties: kind: type: string enum: - builtin_opus - endpoint endpoint_url: type: string format: uri quarantine_notice: type: string maxLength: 2000 extensions: type: object additionalProperties: true description: >- 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: $ref: '#/components/schemas/CompositionMetadata' content_hash: type: string description: >- Response-only: content hash of the composed card (`sha256:`), injected by the GET/PUT response. Server-assigned — do not send on a PUT. version: type: integer description: >- Response-only: monotonic card version, injected by the GET/PUT response. Server-assigned — do not send on a PUT. CompositionMetadata: type: object description: >- System-managed block describing which scope sources merged into the canonical card. Only returned when `?include_composition=true`. properties: canonical_id: type: string composed_at: type: string format: date-time scopes_applied: type: array items: type: object properties: scope: type: string description: '`platform`, `org:`, or `agent:`.' version: type: integer template_version: type: integer card_id: type: string exemptions_applied: type: array items: type: string source_card_id: type: string source_policy_id: type: string Error: type: object description: >- Canonical error envelope (ADR-API-001 conv 1). `error` is always an object — never a bare string. Every 4xx/5xx response across the API conforms to this shape; the runtime helper is `src/http-errors.ts::buildErrorBody`. required: - error properties: error: type: object required: - code - message properties: code: type: string pattern: ^[a-z][a-z0-9_]*$ description: >- Stable, machine-matchable failure identifier (lowercase snake_case). Clients may branch on this; the string is part of the contract. **Status-class defaults** — emitted when no caller code is supplied (`errorCodeForStatus(status)`): `bad_request` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `conflict` (409), `gone` (410), `precondition_failed` (412), `payload_too_large` (413), `unsupported_media_type` (415), `unprocessable_entity` (422), `precondition_required` (428), `rate_limited` (429), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). Fallback `error` for unmapped statuses. **Caller-supplied codes** — handlers may pass an explicit `code` for a specific failure class. Examples: `agent_not_found`, `invalid_hash_proof`, `already_linked`, `idempotency_conflict`, `feature_gated`, `schema_validation_failed`, `no_token`, `bad_canonical_payload`. **Care-framed sub-resource codes** — the cards-as-primitive surface passes its stable care code-string straight through as `error.code`. Examples: `if_match_absent`, `if_match_stale`, `if_match_malformed`, `primitive_validation_failed`. message: type: string description: Human-readable, care-framed explanation of the failure. details: description: >- Optional structured context for the failure (any JSON value: object, array, or primitive). Common shapes: validation findings list, idempotency-conflict diff, `{presented_etag, current_etag}` on a stale `If-Match`, etc. Mirrors the helper's `details?: unknown`. responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- Resource conflict — the request cannot proceed because of a current state conflict (e.g., resource already exists, version mismatch, in-flight idempotency key with a different body). content: application/json: schema: $ref: '#/components/schemas/Error' PreconditionFailed: description: >- The `If-Match` header carried a stale ETag (the spec was updated since the caller read it). Run `GET` to fetch the current ETag, splice your changes onto the latest state, and retry the write. Cards-as-primitive Phase 4 W3.1. content: application/json: schema: $ref: '#/components/schemas/Error' RequestEntityTooLarge: description: >- Request body exceeded the per-endpoint size cap. Cards-as-primitive sub-resource verbs cap each primitive body at 64 KiB; full-card PUTs cap at 128 KiB (alignment) / 64 KiB (protection). content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: >- Request was well-formed but semantically invalid (e.g., business-rule validation failure, malformed YAML inside a JSON payload). content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: >- 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. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 X-RateLimit-Limit: description: Requests permitted per window. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window (0 on a 429). schema: type: integer minimum: 0 X-RateLimit-Reset: description: Unix epoch seconds at which the current window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: >- 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. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Supabase JWT token in Authorization: Bearer header' ApiKeyAuth: type: apiKey in: header name: X-Mnemom-Api-Key description: Mnemom API key (mnm_... format) CookieAuth: type: apiKey in: cookie name: mnemom_session description: >- HttpOnly, Secure, SameSite=Lax cookie issued by /v1/auth/sign-in (or the SSO / email-callback flows). The value is an AES-256-GCM-encrypted blob of {access_token, refresh_token, issued_at, auth_method}. Browser clients include this automatically with `credentials: "include"`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.