> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning Policy

> How the Narrative API is versioned, what an unversioned path means, and what to put in your own code

We version an endpoint only when we make a breaking change to it. New endpoints, new optional parameters, and new response fields ship in place, with no version change.

## 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](/reference/api-policies/breaking-changes) 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/reference/api-policies/breaking-changes#what-your-client-must-do).
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Learn more

<CardGroup cols={2}>
  <Card title="API Breaking Change Policy" icon="triangle-exclamation" href="/reference/api-policies/breaking-changes">
    What counts as breaking, and what we do when we make one
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Endpoints, parameters, and the current version of each
  </Card>
</CardGroup>