Skip to main content
This page is Mnemom’s canonical commitment for how the API evolves. It is the contract we expect every customer integration to be able to rely on. For how-to detail, see the API Versioning guide.

​
The two version axes

Mnemom versions the API at two independent levels: Both axes are independent. A new X-Mnemom-Version date never moves the URL; a new URL generation does not invalidate active date-pinned integrations. This dual model mirrors Stripe-Version and GitHub’s X-GitHub-Api-Version. X-Mnemom-Version is the 7th Mnemom-namespaced header and is permanent contract.

​
How clients pin a version

Production integrations must pin by sending the X-Mnemom-Version header on every request:
If the header is omitted, the latest stable version is served. This is fine for exploratory calls; it is not safe for production systems — and especially not for AI agents, whose embedded environments rarely self-update in response to version-cutover messages. The response always echoes the version that was applied:
If you request a version we don’t recognize (typo, future date, retired version), we serve the closest valid predecessor and the response header tells you which one was applied. We never 4xx on an unrecognized version — silent fallback to the predecessor is the supported failure mode.

​
Support window

After the window closes, calls to the retired version receive a 410 Gone with a Sunset header and a link to the migration guide. There is no silent re-mapping past retirement — the surface is final.

​
What counts as a breaking change

A change is breaking (requires a new version date) if any of:
  • A response field is removed or renamed.
  • A response field’s type changes.
  • A previously optional request field becomes required.
  • An enum loses a value, or an enum’s set of valid values is constrained.
  • An endpoint is removed.
  • A default behavior changes in a way client code could observe.
A change is non-breaking (no new version date) if any of:
  • A new endpoint is added.
  • A new optional response field is added.
  • A new optional request parameter is added.
  • An enum gains a new value.
  • A new response header is introduced.
For non-breaking changes, clients are expected to follow the Tolerant Reader discipline — ignore unknown fields, treat unknown enum values as the documented fallback (we always document the fallback), and never assume a fixed set of headers. This is the same discipline protobuf / Stripe-Version-style ecosystems require. Tooling that fails closed on additive evolution is brittle.

​
Deprecation signals

When a version is deprecated, calls to that version surface:
The headers conform to RFC 8594 (Sunset) and draft-ietf-httpapi-deprecation-header (Deprecation). In parallel, we send email notifications to the org owner and to any integration contacts on file at:
  • T+0 — deprecation announcement.
  • T+12 months — half-window mark.
  • T+16 months — 60-day warning.
  • T+17 months — 30-day final warning.

​
What we will not do

  • We will not break date-pinned production behavior within /v1/ without bumping the date.
  • We will not retire a version before the published Sunset date.
  • We will not silently change X-Mnemom-Version resolution behavior. The fallback rule (closest valid predecessor) is part of the contract.
  • We will not introduce a /v2/ URL generation for individual breaking changes. URL increments are reserved for resource-model overhauls.