API Reference Overview

Base URL

All API requests are made to:

https://api.mnemom.ai/v1

The API is versioned at two levels:

URL (/v1/) — the API generation. Changes only for complete redesigns (infrequent).
X-Mnemom-Version: YYYY-MM-DD header — controls behavior within /v1/. Pin this for production stability.

curl https://api.mnemom.ai/v1/agents \
  -H "X-Mnemom-Api-Key: <key>" \
  -H "X-Mnemom-Version: 2026-08-17"

If you omit X-Mnemom-Version, the latest behavior is used — fine for new integrations, but production systems (including AI agents) should pin to a specific date. Every response echoes the version used:

X-Mnemom-Version: 2026-08-17

Current version: 2026-08-17. Support window: 18 months per version. See the Versioning Policy for the canonical commitment (what we’ll and won’t change, deprecation cadence, the support-window contract), or the API Versioning guide for integration how-to.

Authentication

The Mnemom API resolves the calling principal from one of three sources, checked in this order: the session cookie, then an Authorization: Bearer token, then an API key. Pick the one that matches the caller, not the endpoint. For end-user sign-in (passkey, password + MFA, SSO), session lifecycle, and API-key rotation, see the Authentication guide. Passkeys are the default dashboard sign-in method — see Passkeys for browser support and enrollment. Browser sessions at mnemom.ai (and www.mnemom.ai) authenticate via an HttpOnly, Secure, SameSite=Lax cookie — __Host-mnemom_session on the live site (host-locked; the bare mnemom_session name is used only on http://localhost in local development) — issued on sign-in by the API itself. The cookie is opaque to JavaScript — it holds an encrypted blob of the underlying session tokens, never a raw access token.

# Browser flow — the SPA does this transparently; you rarely call it directly.
curl -X POST https://api.mnemom.ai/v1/auth/sign-in \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.mnemom.ai" \
  --cookie-jar cookies.txt \
  -d '{"email":"[email protected]","password":"..."}'

# Subsequent authenticated requests attach the cookie.
curl https://api.mnemom.ai/v1/agents \
  --cookie cookies.txt

The gateway auto-refreshes an expired access token server-side and rotates the cookie in the response. Passkey (WebAuthn / FIDO2) sign-in endpoints live at /v1/auth/passkey/* and return the same session cookie; MFA step-up is carried through /v1/auth/mfa/* and enterprise SSO through /v1/auth/oidc/*. Sensitive operations require AAL2 step-up — a fresh user-verification gesture within the current session; see the Authentication guide for the list of protected actions. This is the only auth pattern where Access-Control-Allow-Credentials: true matters — fetch() calls from the SPA must include credentials: "include".

Bearer token (CLI and OAuth/MCP clients)

The Mnemom CLI and anything mimicking it use the classic Authorization: Bearer <token> header. mnemom login authenticates against Mnemom’s own OAuth 2.1 authorization server — an authorization-code + PKCE flow via a local loopback redirect by default, or the device-authorization grant with --no-browser — and stores the resulting scoped access token (prefixed mcp_at_…) and refresh token at ~/.mnemom/auth.json; the CLI refreshes it automatically as it nears expiry. This is the same OAuth 2.1 server (and the same token shape) that issues access tokens to MCP clients — see Connect over MCP.

curl https://api.mnemom.ai/v1/agents \
  -H "Authorization: Bearer <token>"

How to get a Bearer token outside the CLI: run mnemom login and read ~/.mnemom/auth.json. Generating your own Bearer tokens from scratch is not supported — use an API key (below) for programmatic access. For a scripted client that wants a session without going through OAuth, POST /v1/auth/login accepts email + password and returns a bearer token pair directly in the JSON body (no cookie involved) — or, if you have a TOTP factor enrolled, { mfa_required: true, factor_id, mfa_token }, which you complete with POST /v1/auth/login/mfa. POST /v1/auth/refresh exchanges the refresh token for a new pair. The API distinguishes an OAuth access token from this token type by its shape, so Authorization: Bearer accepts either without a separate header.

API key

For server-to-server and enterprise fleet management, authenticate with an API key:

curl https://api.mnemom.ai/v1/agents \
  -H "X-Mnemom-Api-Key: <key>"

How to get an API key: Generate one from the Mnemom Dashboard under Settings > API Keys. API keys are scoped to your user account (or organization) and can be rotated at any time; creating and rotating a key only requires your normal signed-in session — see Authentication — API keys for the rotation procedure. API keys are accepted on the great majority of endpoints — agent management, card and policy operations, integrity, webhooks, enforcement, reviews, teams, and deployments. This lets enterprise customers manage agent fleets programmatically without a user session. Billing management (/v1/billing/*) and account self-service operations (GET /v1/auth/me, DELETE /v1/auth/delete-account) are the notable exceptions: they require an end-user identity (cookie or Bearer) and do not accept an API key.

API keys are hashed on our servers and cannot be retrieved after creation. Store your key securely when it is first displayed.

Error format

All error responses return a JSON body with a structured error object containing a stable code and a human-readable message:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message"
  }
}

Branch on error.code, not error.message — codes are stable contract; messages may evolve. Some errors include an additional details object with structured per-code data. See Errors for the full code taxonomy, retry semantics, and the Safe House verdict-to-status mapping.

Common HTTP status codes

Status Code	Meaning
`400`	Bad Request — The request body is malformed or missing required fields.
`401`	Unauthorized — Missing or invalid authentication credentials.
`403`	Forbidden — Valid credentials but insufficient permissions for the requested resource.
`404`	Not Found — The requested resource does not exist.
`429`	Too Many Requests — Rate limit exceeded. Retry after the duration specified in the `Retry-After` header.
`500`	Internal Server Error — Something went wrong on our end. Contact support if the issue persists.

Rate limits

/v1/* requests are rate-limited per client IP, 100 requests/minute by default, in a 1-minute window. The /v1/auth/* surface (sign-in, passkey, MFA, SSO) is metered on an independent per-IP counter of the same default ceiling, so a burst of unrelated data-endpoint traffic from one IP can never starve that same IP’s ability to authenticate. A small number of LLM-backed endpoints additionally enforce a per-user and per-org hourly budget on top of the per-minute ceiling above; their own documentation calls this out where it applies. Contact support to raise your rate-limit ceiling.

Rate limit response

Every /v1/* response carries X-RateLimit-Limit (the current per-minute ceiling) and X-RateLimit-Reset (Unix timestamp when the window resets). When the ceiling is exceeded, the API returns HTTP 429 with those two headers plus:

Header	Description
`Retry-After`	Seconds to wait before retrying
`X-RateLimit-Remaining`	Always `0` on a 429 (not set on a successful response)

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

Idempotency

Mutation endpoints accept an Idempotency-Key header. Send the same key on a retried request (network timeout, uncertain response, safe automatic retry after a 429/5xx) and, if the original request already completed, you get back the exact same cached response instead of a second execution — the replayed response carries Idempotent-Replay: true.

curl -X POST https://api.mnemom.ai/v1/teams \
  -H "X-Mnemom-Api-Key: <key>" \
  -H "Idempotency-Key: 3d4f7a2c-…" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "org-abc123", "name": "Pipeline Alpha"}'

Reusing a key with a different request body is a conflict, not a replay. A concurrent in-flight request with the same key returns a retryable status rather than double-executing.

Pagination

List endpoints paginate with an opaque cursor query parameter and a limit query parameter (each endpoint documents its own default and maximum). The response includes a next_cursor field — pass it back as cursor to fetch the next page; omit cursor to start from the first page. A null/absent next_cursor means there are no more pages.

curl "https://api.mnemom.ai/v1/teams/{team_id}/roster-history?limit=50" \
  -H "X-Mnemom-Api-Key: <key>"

Endpoint documentation

All endpoint documentation below is auto-generated from our OpenAPI specification. Each endpoint has a “Try It” button for interactive testing.

API surface areas

Domain	Overview	Description
Reputation	Reputation API	Trust scores, public pages, badges, verification
Risk	Risk API	Risk assessment and scoring
Policy	Policy API	Policy CRUD, evaluation, resolved policies
Reclassification	Reclassification API	Violation reclassification, score recomputation, compliance export
Intelligence	Intelligence API	Fault lines, risk forecasting, policy recommendations, transactions
On-Chain	On-Chain API	Merkle root anchoring, score publishing, on-chain verification
Safe House	Safe House API	Threat detection, quarantine management, canary credentials
Unified Cards	Unified Cards	Alignment and protection card CRUD across platform/org/team/agent scope
Governance	Governance guarantees	Audit, idempotency, schema identity, and webhook contracts shared across card mutations
Agent Containment	Containment endpoints	Pause, kill, resume agents — kill-switch for rogue agents
Teams	Teams API	Team management, team reputation, team cards
Webhooks	Webhook event catalog	Every event type your org’s webhook endpoints can subscribe to

The Policy, Reclassification, Intelligence, and On-Chain APIs form the CLPI governance layer — governance-as-code with policy enforcement, trust recovery, risk intelligence, and on-chain reputation anchoring.

Versioning

The API is versioned via the URL path (/v1). When breaking changes are introduced, a new version will be released under a new path (e.g., /v2). Non-breaking changes (new optional fields, new endpoints) are added to the current version without a version bump. We will provide advance notice and a migration guide before deprecating any API version.

​Base URL

​Authentication

​Session cookie (dashboard / SPA)

​Bearer token (CLI and OAuth/MCP clients)

​API key

​Error format

​Common HTTP status codes

​Rate limits

​Rate limit response

​Idempotency

​Pagination

​Endpoint documentation

​API surface areas

​Versioning

Base URL

Authentication

Session cookie (dashboard / SPA)

Bearer token (CLI and OAuth/MCP clients)

API key

Error format

Common HTTP status codes

Rate limits

Rate limit response

Idempotency

Pagination

Endpoint documentation

API surface areas

Versioning