Versioning

The promise: once a version is published, calls written against it keep working. You upgrade when you choose to, not when we release.

How it works

The version is the first part of the path: /v19/nsn/.... The first public version is 19.
When a change would break existing callers, it goes into a new version (/v20). /v19 stays online, unchanged, next to it.
GET /versions lists every version and its status. No key needed.
Every response carries X-Api-Version.

{
  "latest": 19,
  "versions": [
    { "version": 19, "path": "/v19", "status": "current", "released": "2026-11-14" }
  ]
}

Status	Meaning
`current`	The newest version. New features land here
`supported`	An older version. Fully working, no new features
`deprecated`	Still working, but has a `sunset` date. Plan your move

What can change inside a version

Safe, additive changes can appear in a published version without notice:

a new endpoint
a new optional query parameter
a new property in a response
a new include section
a new error code for a new situation

Write your client to ignore properties it does not know.

What never changes inside a version

a property being renamed or removed
a property changing type (text to number, value to list)
a change in the meaning of an existing property
a required parameter being added
a status code changing for the same situation

Each published version has an automated contract test that compares today's responses with the responses recorded on its release day. A release cannot be published while that test fails.

Retiring a version

The version is marked deprecated and given a sunset date at least 12 months away.
From then on its responses carry Deprecation: true, a Sunset date header and a Link header pointing to the newest version.
After the sunset date the version may be switched off.

MCP tools

MCP tools follow the same promise. A published tool keeps its name, its parameters and its result shape. A changed behaviour is released as a new tool beside the old one.