Skip to main content

​
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 CodeMeaning
400Bad Request — The request body is malformed or missing required fields.
401Unauthorized — Missing or invalid authentication credentials.
403Forbidden — Valid credentials but insufficient permissions for the requested resource.
404Not Found — The requested resource does not exist.
429Too Many Requests — Rate limit exceeded. Retry after the duration specified in the Retry-After header.
500Internal 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:
TierScopeDefault LimitConfigurable
Per-IPClient IP address100 requests/minuteNo
Per-agentAgent hash (API key identity)100 requests/minuteYes (per-org)
Per-orgBilling account1,000 requests/minuteYes (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:
HeaderDescription
Retry-AfterSeconds to wait before retrying
X-RateLimit-LimitMaximum requests allowed in the window
X-RateLimit-RemainingRequests remaining (always 0 on a 429)
X-RateLimit-ResetUnix 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

DomainOverviewDescription
ReputationReputation APITrust scores, public pages, badges, verification
RiskRisk APIRisk assessment and scoring
PolicyPolicy APIPolicy CRUD, evaluation, resolved policies
ReclassificationReclassification APIViolation reclassification, score recomputation, compliance export
IntelligenceIntelligence APIFault lines, risk forecasting, policy recommendations, transactions
On-ChainOn-Chain APIMerkle root anchoring, score publishing, on-chain verification
ContainmentContainment endpointsPause, kill, resume agents — kill-switch for rogue agents
TeamsTeams APITeam 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.