How versions work
Versions live in the path, per endpoint./v1/nql/execute, /v2/access-rules. The base URL carries no version.
An unversioned path is v1. /datasets is the v1 of that endpoint, and it will never be re-pointed at a newer version. Where an endpoint also publishes a /v1/ path — /v1/nql/execute, for example — the two spellings are the same endpoint and stay interchangeable for as long as it exists. We are adding explicit /v1/ aliases across the remaining unversioned paths; until an endpoint’s alias ships, the unversioned path is the one to call.
An unversioned path never floats to a newer version. If we ship /v2/datasets, /datasets keeps behaving exactly as it does today.
A version number describes one endpoint, not the API. /v2/access-rules is not “version 2 of the Narrative API.” Most endpoints are at v1, a few are at v2, and their next breaking change takes them to v3. Version numbers are not comparable between endpoints.
The version field in the OpenAPI document is the version of the document. It has no relationship to path prefixes.
When we add a version
A breaking change ships as the next version of that endpoint, or as a deprecation naming whatever replaces it. The replacement is not always a new version:POST /nql/run was replaced by POST /nql/execute, a new name at the same version, not a /v2/. Either way what you are already calling is marked deprecated and keeps its current behavior for at least 30 days from the announcement, then stops answering.
Shipping a new version does not deprecate the one before it. Deprecation is a separate decision, announced on its own — if we ship /v2/datasets, /datasets is not deprecated by that alone.
We do not deprecate a version without publishing a migration guide first.
What we don’t version
Non-breaking changes, bug fixes that align behavior with the documentation, performance and infrastructure work, and anything not described in the API reference.What to do in your integration
1
Use the versioned path where one exists
Where an endpoint publishes a
/v1/ path, prefer it: the explicit form makes your integration’s expectations legible in your own code and in support conversations. An unversioned path is the v1 of that endpoint and will not change under you, so there is no deadline to move.2
Check the reference for each endpoint's current version
Because versions are per endpoint, an integration touching several resources will legitimately call more than one prefix. That is expected, not a mistake.
3
Stay on your version until you choose to move
We will never move you. When a newer version exists, migrating is your decision, within the support window.
4
Write a tolerant client
Ignore response fields you don’t recognize, accept unfamiliar enum values, don’t depend on field order, and match on error codes rather than message text. See what your client must do.
5
Watch for deprecation signals
Deprecated endpoints are flagged in the API reference and announced in the changelog, and each one gets a deprecation page naming its replacement.
Learn more
API Breaking Change Policy
What counts as breaking, and what we do when we make one
API Reference
Endpoints, parameters, and the current version of each