> ## 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 Versioning

> How to pin your integration to a specific API version and manage upgrades safely.

mnemom-api uses **date-based header versioning** alongside the `/v1/` URL prefix. This gives you fine-grained control over which API behavior your integration uses, independent of when you deploy.

## How it works

Send the `X-Mnemom-Version` header with every request:

```http theme={null}
GET /v1/alignment/agent/mnm-550e8400-e29b-41d4-a716-446655440000
X-Mnemom-Api-Key: your-api-key
X-Mnemom-Version: 2026-08-17
```

Every response echoes the version used:

```http theme={null}
HTTP/2 200
X-Mnemom-Version: 2026-08-17
Content-Type: application/json
```

If you don't send the header, the **latest** behavior is used. For production systems — including AI agents — always pin to a specific date.

## Current version

The current stable version is **`2026-08-17`**. This is the version to pin to for new integrations.

```bash theme={null}
curl https://api.mnemom.ai/v1/alignment/agent/$AGENT_ID \
  -H "X-Mnemom-Api-Key: $API_KEY" \
  -H "X-Mnemom-Version: 2026-08-17"
```

## SDK defaults

The TypeScript SDK (`@mnemom/sdk`) does not currently expose a version-pinning option — every request goes through with no `X-Mnemom-Version` header, so it always gets the latest behavior:

```typescript theme={null}
import { Mnemom } from '@mnemom/sdk';

const client = new Mnemom({ apiKey: process.env.MNEMOM_API_KEY });
```

If your integration needs to pin to a specific date, set the header yourself on raw HTTP calls to the API rather than relying on an SDK option.

## Support window

| Change type | Support window |
| - | - |
| Standard breaking change | **18 months** from new version date |
| Security vulnerability | 30 days minimum |
| Enterprise contract | Per contract terms |

The 18-month standard window is longer than most APIs. This reflects mnemom's service to the agentic internet: AI agents that call our API may be embedded in contexts that cannot self-update in response to deprecation notices.

## Deprecation signals

When a version you are using is deprecated, responses carry ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)):

```http theme={null}
Deprecation: true
Sunset: Mon, 13 Oct 2027 00:00:00 GMT
Link: <https://docs.mnemom.ai/guides/api-versioning>; rel="deprecation"
```

No version is currently deprecated — every supported version date is fully live. When a version does enter its sunset window, these headers appear on every response made with that version pinned.

## Breaking vs. non-breaking changes

**Breaking changes** always get a new version date:

* Removing or renaming response fields
* Changing field types
* Removing endpoints
* Making optional parameters required
* Changing default behavior

**Non-breaking changes** (no new version date needed):

* New endpoints
* New optional fields in responses
* New optional request parameters

<Warning>
  **Additive changes are still risky for AI agents.** An AI agent with a hardcoded response schema may fail if unexpected fields appear. Use lenient JSON parsing — always ignore unknown fields — and your integration will be safe across non-breaking changes.
</Warning>

## URL versioning (`/v1/` vs `/v2/`)

The `/v1/` URL prefix represents the current API generation. A `/v2/` would only be introduced for a complete API redesign — not for individual breaking changes. URL version increments are expected to happen at most once every several years.

Date header versioning handles all evolution within `/v1/`.

## Version history

| Version date | What changed |
| - | - |
| `2026-04-13` | Initial baseline |
| `2026-04-15` | Unified card schema — alignment and protection card responses moved to a single schema identity (`unified/2026-04-15`) across all card endpoints |
| `2026-08-17` | `POST /v1/alignment/agent/{agent_id}/explain` now rejects a request that names no tool with `400 missing_tool_name`, instead of returning a `pass` verdict for a check that evaluated nothing. Callers pinned to an earlier date keep the old response shape, but a toolless request on that shape now reports the empty tool list explicitly in `reasoning` rather than silently passing |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.