> ## 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. # API Reference Overview > Authentication, base URL, error handling, and rate limits for the Mnemom API ## 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. ```bash theme={null} curl https://api.mnemom.ai/v1/agents \ -H "X-Mnemom-Api-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](/policy/versioning) for the canonical commitment (what we'll and won't change, deprecation cadence, the support-window contract), or the [API Versioning guide](/guides/api-versioning) 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](/guides/authentication). Passkeys are the default dashboard sign-in method — see [Passkeys](/guides/passkeys) for browser support and enrollment. ### Session cookie (dashboard / SPA) 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. ```bash theme={null} # 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":"you@example.com","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](/guides/authentication#aal2-step-up) 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 ` 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. ```bash theme={null} curl https://api.mnemom.ai/v1/agents \ -H "Authorization: Bearer " ``` **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: ```bash theme={null} curl https://api.mnemom.ai/v1/agents \ -H "X-Mnemom-Api-Key: " ``` **How to get an API key**: Generate one from the [Mnemom Dashboard](https://mnemom.ai/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](/guides/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`: ```json theme={null} { "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](/api-reference/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 | ```json theme={null} { "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](/api-reference/reputation-overview) | Trust scores, public pages, badges, verification | | Risk | [Risk API](/api-reference/risk-overview) | Risk assessment and scoring | | Policy | [Policy API](/api-reference/policy-overview) | Policy CRUD, evaluation, resolved policies | | Reclassification | [Reclassification API](/api-reference/reclassification-overview) | Violation reclassification, score recomputation, compliance export | | Intelligence | [Intelligence API](/api-reference/intelligence-overview) | Fault lines, risk forecasting, policy recommendations, transactions | | On-Chain | [On-Chain API](/api-reference/on-chain-overview) | Merkle root anchoring, score publishing, on-chain verification | | Containment | Containment endpoints | Pause, kill, resume agents — kill-switch for rogue agents | | Teams | [Teams API](/api-reference/team-overview) | Team management, team reputation, team cards | The Policy, Reclassification, Intelligence, and On-Chain APIs form the **[CLPI governance layer](/concepts/clpi)** — 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.