Mnemom Agent Containment API
Containment policies and quarantine controls.
Containment policies and quarantine controls.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/mnemom-ai:mnemom-ai-agent-containment-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Mnemom Agent Containment 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: Agent Containment
description: Containment policies and quarantine controls.
paths:
/orgs/{org_id}/agents/{agent_id}/containment:
get:
operationId: getAgentContainment
summary: Get agent containment status
description: Returns the current containment status and recent audit log entries. Any org role.
tags:
- Agent Containment
parameters:
- name: org_id
in: path
required: true
schema:
type: string
- name: agent_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Containment status
content:
application/json:
schema:
type: object
properties:
agent_id:
type: string
status:
type: string
enum:
- active
- paused
- killed
contained_at:
type:
- string
- 'null'
format: date-time
contained_by:
type:
- string
- 'null'
containment_reason:
type:
- string
- 'null'
auto_containment_threshold:
type:
- integer
- 'null'
log:
type: array
items:
type: object
properties:
id:
type: string
action:
type: string
actor:
type: string
reason:
type:
- string
- 'null'
previous_status:
type: string
new_status:
type: string
created_at:
type: string
format: date-time
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
/orgs/{org_id}/agents/{agent_id}/containment-policy:
put:
operationId: updateContainmentPolicy
summary: Update auto-containment policy
description: 'Set or disable the auto-containment threshold. When set, the agent will be automatically paused after N consecutive boundary violations. Requires owner or admin role. Authorization: the caller must be an owner/admin of the organization named by `org_id`, and `agent_id` is validated to belong to that organization (queried together), so an agent that is not in the caller''s org returns 404 and no other tenant''s policy can be changed.'
tags:
- Agent Containment
parameters:
- name: org_id
in: path
required: true
schema:
type: string
- name: agent_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- auto_containment_threshold
properties:
auto_containment_threshold:
type:
- integer
- 'null'
minimum: 2
description: Number of consecutive boundary violations before auto-pause. Set to null to disable.
responses:
'200':
description: Policy updated
content:
application/json:
schema:
type: object
properties:
agent_id:
type: string
auto_containment_threshold:
type:
- integer
- 'null'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
/orgs/{org_id}/agents/{agent_id}/kill:
post:
operationId: killAgent
summary: Kill an agent
description: 'Permanently stop an agent. Requires explicit reactivation to restore. Owner only. Authorization: the caller must be an owner of the organization named by `org_id`, and `agent_id` is validated to belong to that organization (queried together), so an agent that is not in the caller''s org returns 404 and no other tenant''s agent can be killed.'
tags:
- Agent Containment
parameters:
- name: org_id
in: path
required: true
schema:
type: string
- name: agent_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: Reason for killing the agent
responses:
'200':
description: Agent killed successfully
content:
application/json:
schema:
type: object
properties:
agent_id:
type: string
containment_status:
type: string
enum:
- killed
contained_at:
type: string
format: date-time
contained_by:
type: string
containment_reason:
type:
- string
- 'null'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
/orgs/{org_id}/agents/{agent_id}/pause:
post:
operationId: pauseAgent
summary: Pause an agent
description: 'Temporarily stop an agent from making API requests. Requires owner or admin role. Authorization: the caller must be an owner/admin of the organization named by `org_id`, and `agent_id` is validated to belong to that organization (queried together), so an agent that is not in the caller''s org returns 404 and no other tenant''s agent can be paused.'
tags:
- Agent Containment
parameters:
- name: org_id
in: path
required: true
schema:
type: string
- name: agent_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: Reason for pausing the agent
responses:
'200':
description: Agent paused successfully
content:
application/json:
schema:
type: object
properties:
agent_id:
type: string
containment_status:
type: string
enum:
- paused
contained_at:
type: string
format: date-time
contained_by:
type: string
containment_reason:
type:
- string
- 'null'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
/orgs/{org_id}/agents/{agent_id}/reactivate:
post:
operationId: reactivateAgent
summary: Reactivate a killed agent
description: 'Restore a killed agent back to active state. Owner only. Authorization: the caller must be an owner of the organization named by `org_id`, and `agent_id` is validated to belong to that organization (queried together), so an agent that is not in the caller''s org returns 404 and no other tenant''s agent can be reactivated.'
tags:
- Agent Containment
parameters:
- name: org_id
in: path
required: true
schema:
type: string
- name: agent_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Agent reactivated successfully
content:
application/json:
schema:
type: object
properties:
agent_id:
type: string
containment_status:
type: string
enum:
- active
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
/orgs/{org_id}/agents/{agent_id}/resume:
post:
operationId: resumeAgent
summary: Resume a paused agent
description: 'Resume a paused agent back to active state. Only works on paused agents. Requires owner or admin role. Authorization: the caller must be an owner/admin of the organization named by `org_id`, and `agent_id` is validated to belong to that organization (queried together), so an agent that is not in the caller''s org returns 404 and no other tenant''s agent can be resumed.'
tags:
- Agent Containment
parameters:
- name: org_id
in: path
required: true
schema:
type: string
- name: agent_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Agent resumed successfully
content:
application/json:
schema:
type: object
properties:
agent_id:
type: string
containment_status:
type: string
enum:
- active
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
components:
responses:
Unauthorized:
description: Authentication required
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'
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'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
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`.'
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)
ServiceRole:
type: http
scheme: bearer
bearerFormat: JWT
description: Supabase service role bearer JWT. Used by /blog admin operations that talk directly to Supabase. NOT used by /internal/* or /v1/arena/internal/* — those use the custom-header schemes below.
InternalKeyAuth:
type: apiKey
in: header
name: X-Internal-Key
description: Internal service-to-service shared secret, timing-safe compared against INTERNAL_API_KEY. Used by /internal/* gateway routes (compose, agents, webhooks emit).
ServiceKeyAuth:
type: apiKey
in: header
name: X-Service-Key
description: Service-to-service shared secret, timing-safe compared against MNEMOM_SERVICE_KEY. Used by /v1/arena/internal/*, /v1/on-chain/*, and the /v1/internal/* readers consumed by the reputation cron.
CoherenceTokenAuth:
type: http
scheme: bearer
description: Per-cell coherence bearer token. Provisioned in 1Password vault `mnemom-coherence` (one item per receiver). Value compared against COHERENCE_<NAME>_SERVICE_TOKEN_EXPECTED. Used by /v1/internal/coherence/* and /v1/internal/governance/dispatch.
ArenaCandidateTokenAuth:
type: http
scheme: bearer
description: Dedicated arena writer token (ADR-004 §"Arena dedicated writer token"). Compared against ARENA_RECIPE_CANDIDATE_TOKEN. The token's only capability is writing recipe candidates with writer_identity='arena-bypass' (stamped server-side). Used by POST /v1/internal/recipe-candidates.
CustomerVoiceTokenAuth:
type: http
scheme: bearer
description: Customer Voice API bearer token. Timing-safe compared against CUSTOMER_VOICE_API_TOKEN. Grants access to all /v1/internal/feedback/* endpoints (MNE-1876). No customer-facing or reporter-read capability.
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"`.'
LicenseJwtAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: License JWT (HS256, HMAC-signed with LICENSE_SIGNING_SECRET). Used by self-hosted deployment instances to authenticate `/v1/deployments/heartbeat`. Not interchangeable with the Supabase user JWT.
AgentAuth:
type: apiKey
in: header
name: X-Mnemom-Agent-Proof
description: 'Agent possession proof: the full SHA-256 hex digest of `${apiKey}|${agentName}` (or `${apiKey}` for an unnamed singleton agent) — the same `hash_proof` primitive used by POST /v1/agents claim, link-agent, and verify-binding. The server resolves the agent by `agent_hash = proof[:16]`. The agent''s *own* identity (ADR-API-001 third auth class) — distinct from ApiKeyAuth (`X-Mnemom-Api-Key`, which resolves a user/account, not an agent).'