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

# Versioning

> How the Modem API is versioned and how changes are rolled out.

The Modem API is versioned in the URL path. The current version is **`v1`**, served at
`https://api.modem.dev/v1`.

## What counts as a breaking change

We treat these as breaking, and they will **not** happen within a version:

* Removing an endpoint, or removing a field from a response.
* Renaming a field, or changing its type.
* Adding a new required request parameter.
* Changing authentication or error semantics in a way that breaks existing clients.

## What can change without a new version

These are **backward-compatible** and may ship at any time, so build your integration
to tolerate them:

* Adding new endpoints.
* Adding new **optional** request parameters.
* Adding new fields to a response.
* Adding new values to an existing enum where the response already documents that the
  set may grow.

<Tip>
  Ignore unrecognized response fields rather than failing on them, and don't assume an enum is exhaustive unless the docs say so. This
  keeps your integration working across additive changes.
</Tip>

## Deprecation policy

When we need to make a breaking change, we introduce a new version (for example `v2`)
and run it alongside `v1`. We will:

1. Announce the change and publish migration notes in the [changelog](#changelog).
2. Keep the previous version available for a **minimum of 6 months** after the successor
   is generally available.
3. Mark deprecated endpoints in this reference and, where possible, return a
   `Deprecation` header on responses from the deprecated version.

We will not remove or break `v1` without this notice period.

## Changelog

Notable API changes are recorded here. During the initial rollout the surface may expand
additively (new endpoints and fields) under `v1`.

| Date | Change                |
| ---- | --------------------- |
| —    | Initial `v1` release. |