Update a project release

PATCH/api/v2/workspaces/{slug}/projects/{project_id}/releases/{pk}/

Change a project release's name, status, dates, lead, tag, flags, or description. To ship a release, set status to released and record release_date.

PATCH is partial. Send only the fields you want to change. Anything you omit keeps its current value, and an explicit null clears a nullable field.

The body has no project field, so an update never moves the release to another project. Labels and work items aren't part of this body either. Change them with Add or remove project release labels and Add or remove project release work items.

Path Parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.

project_id:requiredstring

The project the release belongs to. Accepts the project UUID or its bare identifier, for example ENG.

pk:requiredstring (uuid)

The id of the release to update.

Body Parameters

name:optionalstring

New display name, unique across the workspace. Maximum 255 characters.

status:optionalstring

One of unreleased, released, or cancelled.

target_date:optionalstring (date)

The planned ship date, as YYYY-MM-DD. Nullable.

release_date:optionalstring (date)

The date the release shipped, as YYYY-MM-DD. Nullable.

lead_id:optionalstring (uuid)

The user who leads the release. Must be an active member of the workspace. Send null to clear the lead.

tag_id:optionalstring (uuid)

A release tag from the workspace tag catalog. Send null to clear the tag.

is_latest:optionalboolean

Mark or unmark the release as the latest one.

is_prerelease:optionalboolean

Mark or unmark the release as a pre-release.

description_html:optionalstring

The release description as HTML. Replaces the stored HTML.

description_json:optionalobject

The release description in the editor's JSON format. Replaces the stored JSON. Not nullable.

external_id:optionalstring

Your system's identifier for this release. Maximum 255 characters. Nullable.

external_source:optionalstring

The system external_id came from. Maximum 255 characters. Nullable.

Response shaping

fields:optionalstring

Comma-separated list of fields to return. Unrequested keys are omitted from the response, not returned as null, so absent means "not requested" and null means "actually null". id always comes back whether or not you name it.

Pass all for every requestable field. An unknown name is a 400 that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.

Requestable here: created_at, created_by_id, description_html, description_id, external_id, external_source, id, is_latest, is_prerelease, label_ids, lead_id, name, project_id, release_date, status, tag_id, target_date, updated_at, updated_by_id.

See Sparse fields.

expand:optionalstring

Comma-separated relations to embed alongside the ids: lead (the lead user) and tag (the release tag). See Expanding relations.

Scopes

releases:write

Errors

Status	Code	Cause
400	invalid_request	A name already used by another release in the workspace, a status outside the enum, an inactive lead_id, an unknown tag_id, or a null for a field that isn't nullable.
401	unauthorized	Missing or invalid credentials.
402	payment_required	Project releases aren't enabled on your plan.
403	forbidden	Your role in the project can't edit this release, or your token scope doesn't allow this.
404	not_found	No release with this id in this project, or no such workspace or project.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	conflict	Another request took the same name between validation and save.
413	payload_too_large	The request body is over the size limit.
415	unsupported_media_type	The Content-Type isn't one this endpoint accepts.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Update a project release

curl -X PATCH \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/releases/3e8a1f52-7c4b-4d9e-a6f1-0b2c5d8e9f14/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "released",
  "release_date": "2026-02-26",
  "is_latest": true
}'

import requests

response = requests.patch(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/releases/3e8a1f52-7c4b-4d9e-a6f1-0b2c5d8e9f14/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "status": "released",
        "release_date": "2026-02-26",
        "is_latest": True,
    },
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/releases/3e8a1f52-7c4b-4d9e-a6f1-0b2c5d8e9f14/",
  {
    method: "PATCH",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "released",
      release_date: "2026-02-26",
      is_latest: true,
    }),
  },
);
const data = await response.json();

Response200

{
  "id": "3e8a1f52-7c4b-4d9e-a6f1-0b2c5d8e9f14",
  "name": "Mobile 4.2.0",
  "project_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
  "description_id": "5d2b7e91-4a3c-4f68-9e0d-1c7a8b2f6e35",
  "description_html": "<p>Offline mode and the new onboarding flow.</p>",
  "status": "released",
  "target_date": "2026-02-27",
  "release_date": "2026-02-26",
  "lead_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "tag_id": "a41c9e07-2f5d-4b83-8c6e-9d1f0a3b7c52",
  "is_latest": true,
  "is_prerelease": false,
  "external_id": null,
  "external_source": null,
  "label_ids": ["7f3a2c19-8e4d-4b61-a5c7-2d9e0f1b8a46"],
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-02-26T18:03:52.117904Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}