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-04-13"

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-04-13

Current version: 2026-04-13. 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 supports three authentication patterns. 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 named mnemom_session, issued on sign-in by the API itself. The cookie is opaque to JavaScript — it holds an AES-256-GCM-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 and SSO are carried through /v1/auth/mfa/* and /v1/auth/sso/*. Sensitive operations require AAL2 step-up — a fresh user-verification gesture within the session’s AAL2 window; 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)

The Mnemom CLI and anything mimicking it use the classic Authorization: Bearer <token> header. The CLI obtains its token via a one-time browser → localhost handoff at login time (exchanged through POST /v1/auth/cli-exchange, which requires an already-authenticated session cookie); the raw token never leaves the CLI’s local auth file after that.

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.

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 or rotating a key requires AAL2 step-up; see Authentication — API keys for the rotation procedure. API keys are accepted on all agent management endpoints — agent CRUD, card and policy management, integrity operations, webhooks, enforcement, reviews, and deployments. This lets enterprise customers manage agent fleets programmatically without a user session. The only endpoints that require an end-user identity (cookie or Bearer) are account self-service operations: GET /v1/auth/me, DELETE /v1/auth/delete-account, POST /v1/agents/:id/link, and billing management.

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

API requests are rate-limited across three tiers, evaluated in order:

Tier	Scope	Default Limit	Configurable
Per-IP	Client IP address	100 requests/minute	No
Per-agent	Agent hash (API key identity)	100 requests/minute	Yes (per-org)
Per-org	Billing account	1,000 requests/minute	Yes (per-org)

Enterprise organizations can request custom per-org and per-agent limits via their account settings or by contacting support.

Rate limit response

When any tier is exceeded, the API returns HTTP 429 with these headers:

Header	Description
`Retry-After`	Seconds to wait before retrying
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining (always `0` on a 429)
`X-RateLimit-Reset`	Unix timestamp when the window resets

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

The tier that was hit (ip, agent, or org) and the window details are in the response headers listed above. Rate limit windows are 1 minute.

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
Containment	Containment endpoints	Pause, kill, resume agents — kill-switch for rogue agents
Teams	Teams API	Team management, team reputation, team cards

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)

​API key

​Error format

​Common HTTP status codes

​Rate limits

​Rate limit response

​Endpoint documentation

​API surface areas

​Versioning

Base URL

Authentication

Session cookie (dashboard / SPA)

Bearer token (CLI)

API key

Error format

Common HTTP status codes

Rate limits

Rate limit response

Endpoint documentation

API surface areas

Versioning