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

# Versioning

> How the Endstate API versions its surface, what changes are safe within a version, and what to expect when a new version ships.

## URL-based versioning

The API version is part of the URL path. The current version is `v1`:

```
https://api2.endstate.io/v1/units
https://api2.endstate.io/v1/collections
```

Service endpoints (`/` and `/health`) have no version prefix — they are always unversioned.

There is no header-based version pinning. The version in the path is the version you get.

<Note>
  The v1 API is in **early access**. While the surface stabilizes, an occasional
  breaking change may still ship in place — each one is recorded in the
  [Changelog](/changelog) with a migration note. The guarantees below describe
  the stability policy that applies in full once v1 is generally available.
</Note>

## What stays stable within a version

Breaking changes never ship in place. When a change would break existing clients, it goes behind a new path prefix (for example, a future `/v2`). Until then, the `/v1` surface is stable: the same request produces the same shape of response.

### Breaking changes — require a new version

These changes would move to a new path prefix before rolling out:

| Category                | Examples                                                                    |
| ----------------------- | --------------------------------------------------------------------------- |
| Field removal or rename | Removing `external_id`; renaming `name` to `title`                          |
| Type or format change   | `string` → `number`; `date` → `datetime`                                    |
| Tightened validation    | Making a previously-optional field required; narrowing accepted values      |
| Removed enum value      | Removing a value clients may already branch on                              |
| HTTP status change      | A condition that returned `409` now returns `422`                           |
| Error code change       | A condition that returned `unit.not_found` now returns `not_found.resource` |
| Semantic change         | A field keeps its shape but its meaning changes                             |
| Auth requirement change | Adding a required scope to an existing endpoint                             |

### Additive changes — safe within the current version

These changes ship under `/v1` without a version bump. Existing clients keep working as long as they ignore unknown fields:

* New endpoints
* New optional request fields or query parameters
* New response fields
* New error codes (on conditions that couldn't be reached before)
* Loosened validation (accepting input previously rejected)
* Bug fixes that bring behavior in line with documented behavior

<Tip>
  Write forward-compatible clients: ignore unknown fields in responses, treat
  unknown `error.code` values as generic errors (fall back to the HTTP status
  class), and avoid exhaustive branching on enum values. Clients that follow
  this pattern are unaffected by additive changes.
</Tip>

## Deprecation and sunset

When a new major version ships, the previous version remains available for **at least 12 months** from the new version's general availability date.

During the deprecation window:

* Every response from the deprecated version includes `Deprecation: true` and `Sunset: <date>` headers. Check for these headers in your integration to get early notice.
* The API key owner email on file receives two notices: one at the deprecation announcement and one at least one month before the sunset date.

At sunset, deprecated endpoints return `410 Gone` with error code `version_sunset`. This state lasts at least 30 days before the endpoints are removed entirely.

The same window applies to individual endpoints or fields deprecated within a major version — at least 12 months for endpoints, at least 6 months for fields.

## Next steps

<CardGroup cols={2}>
  <Card title="Error handling" icon="circle-exclamation" href="/conventions/errors">
    Error envelope shape, stable error codes, and how to branch on them safely.
  </Card>

  <Card title="API reference" icon="book-open" href="/api-reference/introduction">
    Full reference for every endpoint in the current version.
  </Card>
</CardGroup>