Skip to main content
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:
A request without the header runs against your workspace’s API version, the api.version preference. 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 api.version. To follow the latest version, including breaking changes, reset 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.