Releases overview

Releases group shipped work and carry a changelog.

The routes on this page serve workspace releases only, so project_id is always null here. A release that belongs to a project is a project release. It has the same fields, but you manage it under /api/v2/workspaces/{slug}/projects/{project_id}/releases/, and its id returns 404 on these routes.

The release object

Attributes

• created_at string (date-time)

  When the release was created.

• updated_at string (date-time)

  When the release was last updated.

• created_by_id string (uuid)

  The user who created the release.

• updated_by_id string (uuid) or null

  The user who last updated the release. null until someone updates it.

• description_html string

  The release description as HTML. List rows leave it out unless you request it with ?fields=.

• description_id string (uuid)

  The id of the description record that holds the release body.

• external_id string or null

  Your system's identifier for this release, for sync and import correlation. null unless you set it.

• external_source string or null

  The system external_id came from, for example github or jira. null unless you set it.

• id string (uuid)

  Unique identifier.

• is_latest boolean

  Whether the release is marked as the latest one. Plane doesn't limit the flag to one release, so setting it doesn't clear it on other releases.

• is_prerelease boolean

  Whether the release is marked as a pre-release.

• label_ids array of string (uuid)

  The release labels applied to the release. Change them with Add or remove release labels.

• lead_id string (uuid) or null

  The user who leads the release. Must be an active member of the workspace. null when the release has no lead.

• name string

  Display name. Maximum 255 characters. Names are unique across the whole workspace, so a workspace release can't reuse the name of a project release.

• project_id string (uuid) or null

  The project a release belongs to. Always null on a workspace release. Set only on a project release, and read-only on both.

• release_date string (date) or null

  The date the release shipped, as YYYY-MM-DD. null until you set it.

• status string

  Where the release is in its lifecycle. One of unreleased (the default), released, or cancelled.

• tag_id string (uuid) or null

  The version tag, from the release tag catalog. null when the release has no tag.

• target_date string (date) or null

  The planned ship date, as YYYY-MM-DD. null until you set it.

Response200

{
  "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
  "name": "Example name",
  "project_id": null,
  "description_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
  "description_html": "<p>Details go here.</p>",
  "status": "unreleased",
  "target_date": "2026-01-20",
  "release_date": "2026-01-20",
  "lead_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
  "tag_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
  "is_latest": false,
  "is_prerelease": false,
  "external_id": null,
  "external_source": null,
  "label_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-01-14T09:22:41.478363Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by_id": null
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/releases/	List releases
GET	/api/v2/workspaces/{slug}/releases/{pk}/changelog/	Get a release changelog
GET	/api/v2/workspaces/{slug}/releases/{pk}/	Get a release
POST	/api/v2/workspaces/{slug}/releases/	Create a release
PATCH	/api/v2/workspaces/{slug}/releases/{pk}/changelog/	Update a release changelog
PATCH	/api/v2/workspaces/{slug}/releases/{pk}/	Update a release
DELETE	/api/v2/workspaces/{slug}/releases/{pk}/	Delete a release
GET	/api/v2/workspaces/{slug}/releases/{pk}/labels/	List a release's labels
POST	/api/v2/workspaces/{slug}/releases/{pk}/labels/	Add or remove release labels
GET	/api/v2/workspaces/{slug}/releases/{pk}/work-items/	List a release's work items
POST	/api/v2/workspaces/{slug}/releases/{pk}/work-items/	Add or remove release work items

Response shaping

Every release read accepts ?fields= for sparse responses. See Sparse fields. Errors follow the shared problem+json contract.