Create a project release

POST/api/v1/workspaces/{workspace_slug}/projects/{project_id}/releases/

Creates a new release scoped to the project. project is set from the URL and any project value in the request body is ignored. name must be unique within the workspace, otherwise the request fails with a 400 RELEASE_NAME_ALREADY_EXISTS error. If tag is provided, it must reference a global release tag or a tag belonging to this project, otherwise the request fails with a 400 {"tag": "RELEASE_TAG_OUT_OF_SCOPE"} error.

Path parameters

workspace_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 unique identifier of the project.

Body parameters

name:requiredstring

Name of the release.

description_html:optionalstring

HTML description of the release.

description_json:optionalobject

JSON description of the release.

status:optionalstring

Status of the release: unreleased, released, or cancelled. Defaults to unreleased.

target_date:optionalstring

Target date of the release in YYYY-MM-DD format.

release_date:optionalstring

Actual release date of the release in YYYY-MM-DD format.

lead:optionalstring

ID of the user who leads the release.

tag:optionalstring

ID of the release tag associated with the release.

is_latest:optionalboolean

Whether this is the latest release. Defaults to false.

is_prerelease:optionalboolean

Whether this release is a prerelease. Defaults to false.

external_id:optionalstring

External ID from an external source.

external_source:optionalstring

External source identifier.

Scopes

releases:write

Create a project release

curl -X POST \
  "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/releases/" \
  -H "X-API-Key: $PLANE_API_KEY" \
  # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "v2.4.0",
  "description_html": "<p>Spring feature release.</p>",
  "status": "unreleased",
  "target_date": "2025-03-31",
  "lead": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "tag": "9f8e7d6c-5b4a-3210-fedc-ba0987654321",
  "is_latest": false,
  "is_prerelease": false
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/releases/",
    headers={"X-API-Key": "your-api-key"},
    json={
  'name': 'v2.4.0',
  'description_html': '<p>Spring feature release.</p>',
  'status': 'unreleased',
  'target_date': '2025-03-31',
  'lead': '16c61a3a-512a-48ac-b0be-b6b46fe6f430',
  'tag': '9f8e7d6c-5b4a-3210-fedc-ba0987654321',
  'is_latest': False,
  'is_prerelease': False
}
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v1/workspaces/my-workspace/projects/project-uuid/releases/",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "v2.4.0",
      description_html: "<p>Spring feature release.</p>",
      status: "unreleased",
      target_date: "2025-03-31",
      lead: "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
      tag: "9f8e7d6c-5b4a-3210-fedc-ba0987654321",
      is_latest: false,
      is_prerelease: false,
    }),
  },
);
const data = await response.json();

Response201

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-03-01T10:00:00.000000Z",
  "updated_at": "2025-03-05T14:30:00.000000Z",
  "deleted_at": null,
  "name": "v2.4.0",
  "description": {
    "description_html": "<p>Spring feature release.</p>",
    "description_binary": null,
    "description_stripped": "Spring feature release.",
    "description_json": {}
  },
  "status": "unreleased",
  "target_date": "2025-03-31",
  "release_date": null,
  "is_latest": false,
  "is_prerelease": false,
  "external_id": null,
  "external_source": null,
  "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4",
  "lead": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "tag": "9f8e7d6c-5b4a-3210-fedc-ba0987654321",
  "project": "8b2e1c4d-6f3a-4d5e-9c1b-2a3b4c5d6e7f"
}