# Versioning

The Layer REST API is **path-versioned**. Every endpoint lives under a version prefix:

```plaintext
https://api.app.layer.ai/api/v1/…
https://api.app.layer.ai/api/v2/…
```

**`v2` is the current version** and the default across these docs. `v1` remains live under `/api/v1` — it was superseded by v2 on 2026-08-26 and will be deprecated as a whole later.

| Version | Status                                                | Docs                |
| ------- | ----------------------------------------------------- | ------------------- |
| v2      | **Current** — use for all new integrations            | </docs/v2/rest-api> |
| v1      | Superseded — still live; migrate on your own schedule | </docs/v1/rest-api> |

v2 extends inference generation with [reference sets](/docs/models) — trained subjects, styles, and characters — and adds the base-model and reference-set catalog endpoints those runs are built from.

v1 sunset

A sunset date for v1 has not been announced yet; v1 will be deprecated as a whole (all endpoints at once), not endpoint-by-endpoint. When a date is set it will appear here, in the [changelog](/docs/changelog), and in the banner on every v1 docs page.

## What changed in v2

Most v1 endpoints are **drop-in** — identical request and response schemas under the new prefix. A small number changed (inference request/response bodies, the Models → Base Models rename) and a few are new. The [v1 → v2 migration guide](/docs/migration) lists exactly which, and only those.

## What counts as breaking

Treat these as **non-breaking** and build tolerantly so they don’t break your integration:

* New endpoints, new optional request fields, and **new fields in responses**.
* New enum values (for example, a new run status or error code).

Treat these as **breaking** (they ship under a new version):

* Removing or renaming an endpoint, field, or enum value.
* Changing a field’s type or a required request field.

Note

Parse responses leniently — ignore unknown fields rather than rejecting them — and handle unknown enum values gracefully.

## Deprecation

Nothing is removed without notice. A deprecated operation returns [Deprecation and Sunset headers](/docs/deprecation) for at least **90 days** before it stops responding, and is marked `deprecated: true` in the [OpenAPI description](https://layer.ai/openapi.json) for the same period.

See [Deprecation policy](/docs/deprecation) for the headers to watch and how to handle them.