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 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 the header doesn’t match YYYY-MM-DD, or names a version we don’t recognize (typo, future date, a version never released), the request is rejected with 400 and the error body names every version we do support. There is no silent fallback to a nearby version — an unrecognized X-Mnemom-Version fails loudly rather than serving you a version you didn’t ask for.

​
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). No version is deprecated as of this writing — X-Mnemom-Version currently accepts 2026-04-13, 2026-04-15, and the current 2026-08-17, none of which are on a sunset path.

​
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 resolution rule (missing header → latest; unrecognized value → 400 naming the supported set) 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.