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

# Versioning

> Choose the API version a request runs against with the Plane-Version header or your workspace's API version.

Every API request runs against a dated API version. A version decides the
parameters a request accepts and the shape of what it returns. The current
version is `2026-11-07`.

## Choosing a version

Send the version in the `Plane-Version` header:

```bash theme={null}
curl https://api.plane.com/v1/workers \
  -H "Authorization: Bearer $PLANE_API_KEY" \
  -H "Plane-Version: 2026-11-07"
```

A request without the header runs against your workspace's API version, the
`api.version` [preference](https://docs.plane.com/reference/preferences/get.md). Creating an API key
sets it to the latest version if it isn't set, so your integrations keep the
behavior they were built against without sending anything.

To move to a newer version, [update](https://docs.plane.com/reference/preferences/update.md)
`api.version`. To follow the latest version, including breaking changes,
[reset](https://docs.plane.com/reference/preferences/reset.md) it; your next new API key sets it again.
A partner key acting in a client's workspace uses its own workspace's version.

Every response names the version it ran against in its `Plane-Version`
header.

## What changes without a new version

Plane adds to the API without creating a version. These changes can reach the
latest version at any time:

* a new endpoint
* a new optional parameter
* a new field in a response
* a new value in a field that lists a fixed set of values, such as a status
* a changed error message
* a changed length or format of an ID, cursor or other opaque string

Build your integration to ignore response fields and values it doesn't
recognize.

Anything else, such as removing or renaming a field, making a parameter
required, or changing what a value means, ships only in a new version. Once a
newer version exists, older versions stop changing: new endpoints, parameters
and fields reach only the latest version. Your workspace's version doesn't
change on its own.

## Unknown versions

A request naming a version that doesn't exist, or a malformed one, fails with
`400 bad_request` and the reason `api_version.unknown`. That response carries
no `Plane-Version` header, because the request didn't run against a version.

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "\"2027-01-01\" is not a Plane API version.",
    "reasons": [
      {
        "code": "api_version.unknown",
        "message": "Send a Plane API version, such as 2026-11-07, the latest."
      }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.