From 34754561e5a2fe26077a7dc63d5474a298720e6d Mon Sep 17 00:00:00 2001 From: Surya Prashanth Date: Wed, 9 Sep 2026 20:55:29 +0530 Subject: [PATCH] docs: add Releases API reference Document the v1 Releases API, which had no coverage in the API reference. Adds 39 pages under docs/api-reference/release/ and registers them in the sidebar as eight groups: - Releases (workspace-level CRUD) and Project Releases - Release Work Items (list, add, remove) - Release Labels (catalog CRUD plus attach/detach on a release) - Release Tags (CRUD) - Release Comments (CRUD) - Release Links (CRUD) - Release Changelog (get, update) Paths, fields, scopes, error codes and pagination were taken from the plane-ee v1 views, serializers and models for releases. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01GYqeaJijRPkSgfwsphQusd --- docs/.vitepress/config.mts | 87 +++++++ .../release/add-labels-to-release.md | 137 ++++++++++ .../release/add-project-release.md | 237 ++++++++++++++++++ .../release/add-release-comment.md | 165 ++++++++++++ .../release/add-release-label.md | 150 +++++++++++ .../api-reference/release/add-release-link.md | 158 ++++++++++++ docs/api-reference/release/add-release-tag.md | 165 ++++++++++++ .../release/add-release-work-items.md | 130 ++++++++++ docs/api-reference/release/add-release.md | 231 +++++++++++++++++ .../release/delete-project-release.md | 108 ++++++++ .../release/delete-release-comment.md | 108 ++++++++ .../release/delete-release-label.md | 101 ++++++++ .../release/delete-release-link.md | 108 ++++++++ .../release/delete-release-tag.md | 99 ++++++++ docs/api-reference/release/delete-release.md | 102 ++++++++ .../release/get-project-release-detail.md | 133 ++++++++++ .../release/get-release-changelog.md | 114 +++++++++ .../release/get-release-comment-detail.md | 127 ++++++++++ .../release/get-release-detail.md | 127 ++++++++++ .../release/get-release-label-detail.md | 109 ++++++++ .../release/get-release-link-detail.md | 120 +++++++++ .../release/get-release-tag-detail.md | 112 +++++++++ .../release/list-labels-for-release.md | 142 +++++++++++ .../release/list-project-releases.md | 157 ++++++++++++ .../release/list-release-comments.md | 154 ++++++++++++ .../release/list-release-labels.md | 139 ++++++++++ .../release/list-release-links.md | 147 +++++++++++ .../release/list-release-tags.md | 145 +++++++++++ .../release/list-release-work-items.md | 144 +++++++++++ docs/api-reference/release/list-releases.md | 151 +++++++++++ docs/api-reference/release/overview.md | 214 ++++++++++++++++ .../release/remove-labels-from-release.md | 127 ++++++++++ .../release/remove-release-work-items.md | 127 ++++++++++ .../release/update-project-release-detail.md | 228 +++++++++++++++++ .../release/update-release-changelog.md | 149 +++++++++++ .../release/update-release-comment-detail.md | 177 +++++++++++++ .../release/update-release-detail.md | 222 ++++++++++++++++ .../release/update-release-label-detail.md | 150 +++++++++++ .../release/update-release-link-detail.md | 161 ++++++++++++ .../release/update-release-tag-detail.md | 159 ++++++++++++ 40 files changed, 5821 insertions(+) create mode 100644 docs/api-reference/release/add-labels-to-release.md create mode 100644 docs/api-reference/release/add-project-release.md create mode 100644 docs/api-reference/release/add-release-comment.md create mode 100644 docs/api-reference/release/add-release-label.md create mode 100644 docs/api-reference/release/add-release-link.md create mode 100644 docs/api-reference/release/add-release-tag.md create mode 100644 docs/api-reference/release/add-release-work-items.md create mode 100644 docs/api-reference/release/add-release.md create mode 100644 docs/api-reference/release/delete-project-release.md create mode 100644 docs/api-reference/release/delete-release-comment.md create mode 100644 docs/api-reference/release/delete-release-label.md create mode 100644 docs/api-reference/release/delete-release-link.md create mode 100644 docs/api-reference/release/delete-release-tag.md create mode 100644 docs/api-reference/release/delete-release.md create mode 100644 docs/api-reference/release/get-project-release-detail.md create mode 100644 docs/api-reference/release/get-release-changelog.md create mode 100644 docs/api-reference/release/get-release-comment-detail.md create mode 100644 docs/api-reference/release/get-release-detail.md create mode 100644 docs/api-reference/release/get-release-label-detail.md create mode 100644 docs/api-reference/release/get-release-link-detail.md create mode 100644 docs/api-reference/release/get-release-tag-detail.md create mode 100644 docs/api-reference/release/list-labels-for-release.md create mode 100644 docs/api-reference/release/list-project-releases.md create mode 100644 docs/api-reference/release/list-release-comments.md create mode 100644 docs/api-reference/release/list-release-labels.md create mode 100644 docs/api-reference/release/list-release-links.md create mode 100644 docs/api-reference/release/list-release-tags.md create mode 100644 docs/api-reference/release/list-release-work-items.md create mode 100644 docs/api-reference/release/list-releases.md create mode 100644 docs/api-reference/release/overview.md create mode 100644 docs/api-reference/release/remove-labels-from-release.md create mode 100644 docs/api-reference/release/remove-release-work-items.md create mode 100644 docs/api-reference/release/update-project-release-detail.md create mode 100644 docs/api-reference/release/update-release-changelog.md create mode 100644 docs/api-reference/release/update-release-comment-detail.md create mode 100644 docs/api-reference/release/update-release-detail.md create mode 100644 docs/api-reference/release/update-release-label-detail.md create mode 100644 docs/api-reference/release/update-release-link-detail.md create mode 100644 docs/api-reference/release/update-release-tag-detail.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index d9402339..38268e59 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -899,6 +899,93 @@ export default extendConfig( { text: "Remove Epics", link: "/api-reference/initiative/remove-epics-from-initiative" }, ], }, + { + text: "Releases", + collapsed: true, + items: [ + { text: "Overview", link: "/api-reference/release/overview" }, + { text: "Create Release", link: "/api-reference/release/add-release" }, + { text: "List Releases", link: "/api-reference/release/list-releases" }, + { text: "Get Release", link: "/api-reference/release/get-release-detail" }, + { text: "Update Release", link: "/api-reference/release/update-release-detail" }, + { text: "Delete Release", link: "/api-reference/release/delete-release" }, + ], + }, + { + text: "Project Releases", + collapsed: true, + items: [ + { text: "Create Project Release", link: "/api-reference/release/add-project-release" }, + { text: "List Project Releases", link: "/api-reference/release/list-project-releases" }, + { text: "Get Project Release", link: "/api-reference/release/get-project-release-detail" }, + { text: "Update Project Release", link: "/api-reference/release/update-project-release-detail" }, + { text: "Delete Project Release", link: "/api-reference/release/delete-project-release" }, + ], + }, + { + text: "Release Work Items", + collapsed: true, + items: [ + { text: "Add Work Items", link: "/api-reference/release/add-release-work-items" }, + { text: "List Work Items", link: "/api-reference/release/list-release-work-items" }, + { text: "Remove Work Items", link: "/api-reference/release/remove-release-work-items" }, + ], + }, + { + text: "Release Labels", + collapsed: true, + items: [ + { text: "Create Label", link: "/api-reference/release/add-release-label" }, + { text: "List Labels", link: "/api-reference/release/list-release-labels" }, + { text: "Get Label", link: "/api-reference/release/get-release-label-detail" }, + { text: "Update Label", link: "/api-reference/release/update-release-label-detail" }, + { text: "Delete Label", link: "/api-reference/release/delete-release-label" }, + { text: "Add Labels to Release", link: "/api-reference/release/add-labels-to-release" }, + { text: "List Labels for Release", link: "/api-reference/release/list-labels-for-release" }, + { text: "Remove Labels from Release", link: "/api-reference/release/remove-labels-from-release" }, + ], + }, + { + text: "Release Tags", + collapsed: true, + items: [ + { text: "Create Tag", link: "/api-reference/release/add-release-tag" }, + { text: "List Tags", link: "/api-reference/release/list-release-tags" }, + { text: "Get Tag", link: "/api-reference/release/get-release-tag-detail" }, + { text: "Update Tag", link: "/api-reference/release/update-release-tag-detail" }, + { text: "Delete Tag", link: "/api-reference/release/delete-release-tag" }, + ], + }, + { + text: "Release Comments", + collapsed: true, + items: [ + { text: "Create Comment", link: "/api-reference/release/add-release-comment" }, + { text: "List Comments", link: "/api-reference/release/list-release-comments" }, + { text: "Get Comment", link: "/api-reference/release/get-release-comment-detail" }, + { text: "Update Comment", link: "/api-reference/release/update-release-comment-detail" }, + { text: "Delete Comment", link: "/api-reference/release/delete-release-comment" }, + ], + }, + { + text: "Release Links", + collapsed: true, + items: [ + { text: "Create Link", link: "/api-reference/release/add-release-link" }, + { text: "List Links", link: "/api-reference/release/list-release-links" }, + { text: "Get Link", link: "/api-reference/release/get-release-link-detail" }, + { text: "Update Link", link: "/api-reference/release/update-release-link-detail" }, + { text: "Delete Link", link: "/api-reference/release/delete-release-link" }, + ], + }, + { + text: "Release Changelog", + collapsed: true, + items: [ + { text: "Get Changelog", link: "/api-reference/release/get-release-changelog" }, + { text: "Update Changelog", link: "/api-reference/release/update-release-changelog" }, + ], + }, { text: "Customers", collapsed: true, diff --git a/docs/api-reference/release/add-labels-to-release.md b/docs/api-reference/release/add-labels-to-release.md new file mode 100644 index 00000000..659b49e2 --- /dev/null +++ b/docs/api-reference/release/add-labels-to-release.md @@ -0,0 +1,137 @@ +--- +title: Add labels to release +description: Create labels to release via Plane API. HTTP POST request format, required fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Add labels to release + +
+ POST + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/labels/ +
+ +
+
+ +Adds one or more labels to a release. Labels must be workspace-wide or belong to the release's project, otherwise the request fails with a 400 `RELEASE_LABEL_OUT_OF_SCOPE` error. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Array of release label IDs to add to the release. + + + +
+
+ +
+ +### Scopes + +`releases:write` + +
+ +
+
+ + + + + + + + + +```json +[ + { + "id": "f6a7b8c9-d0e1-2345-fabc-678901234567", + "name": "Breaking change", + "color": "#FF5630", + "sort_order": 10, + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null + } +] +``` + + + +
+
diff --git a/docs/api-reference/release/add-project-release.md b/docs/api-reference/release/add-project-release.md new file mode 100644 index 00000000..67a21bfb --- /dev/null +++ b/docs/api-reference/release/add-project-release.md @@ -0,0 +1,237 @@ +--- +title: Create a project release +description: Create a release for a project via Plane API. HTTP POST request format, required fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# 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 a 400 `RELEASE_NAME_ALREADY_EXISTS` error is returned. If `tag` is provided, it must reference a global release tag or a tag belonging to this project, otherwise a 400 `{"tag": "RELEASE_TAG_OUT_OF_SCOPE"}` error is returned. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier of the project. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Name of the release. + + + + + +HTML description of the release. + + + + + +JSON description of the release. + + + + + +Status of the release. Can be: `unreleased`, `released`, `cancelled`. Defaults to `unreleased`. + + + + + +Target date of the release in YYYY-MM-DD format. + + + + + +Actual release date of the release in YYYY-MM-DD format. + + + + + +ID of the user who leads the release. + + + + + +ID of the release tag associated with the release. + + + + + +Whether this is the latest release. Defaults to `false`. + + + + + +Whether this release is a prerelease. Defaults to `false`. + + + + + +External ID from an external source. + + + + + +External source identifier. + + + +
+
+ +
+ +### Scopes + +`releases:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "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": "

Spring feature release.

", + "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" +} +``` + + + +
+
diff --git a/docs/api-reference/release/add-release-comment.md b/docs/api-reference/release/add-release-comment.md new file mode 100644 index 00000000..d5490e39 --- /dev/null +++ b/docs/api-reference/release/add-release-comment.md @@ -0,0 +1,165 @@ +--- +title: Create a release comment +description: Create a release comment via Plane API. HTTP POST request format, required fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Create a release comment + +
+ POST + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/comments/ +
+ +
+
+ +Creates a new comment on a release. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +HTML-formatted content of the comment. + + + + + +ID of the parent comment, for threaded replies. + + + + + +Whether the comment has been resolved. + + + +
+
+ +
+ +### Scopes + +`releases.comments:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "c0ffee00-1111-2222-3333-444444444444", + "created_at": "2025-03-02T09:15:00.000000Z", + "updated_at": "2025-03-02T09:15:00.000000Z", + "deleted_at": null, + "comment": { + "description_html": "

QA sign-off complete.

", + "description_binary": null, + "description_stripped": "QA sign-off complete.", + "description_json": {} + }, + "is_hidden": false, + "edited_at": null, + "is_resolved": false, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "parent": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/add-release-label.md b/docs/api-reference/release/add-release-label.md new file mode 100644 index 00000000..92b951e0 --- /dev/null +++ b/docs/api-reference/release/add-release-label.md @@ -0,0 +1,150 @@ +--- +title: Create a release label +description: Create a release label via Plane API. HTTP POST request format, required fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Create a release label + +
+ POST + /api/v1/workspaces/{workspace_slug}/releases/labels/ +
+ +
+
+ +Creates a new release label in the workspace label catalog. The label name must be unique per workspace (or per project, when scoped to one), otherwise the request fails with a 400 `RELEASE_LABEL_NAME_ALREADY_EXISTS` error. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Name of the release label. + + + + + +Hex color code for the label. Defaults to `#4E5355`. + + + + + +Sort order for the label. Defaults to 0. + + + + + +ID of the project to scope the label to. When omitted, the label is workspace-wide. This cannot be changed after creation. + + + +
+
+ +
+ +### Scopes + +`releases.labels:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "f6a7b8c9-d0e1-2345-fabc-678901234567", + "name": "Breaking change", + "color": "#FF5630", + "sort_order": 10, + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/add-release-link.md b/docs/api-reference/release/add-release-link.md new file mode 100644 index 00000000..06b28bcc --- /dev/null +++ b/docs/api-reference/release/add-release-link.md @@ -0,0 +1,158 @@ +--- +title: Create a release link +description: Create a release link via Plane API. HTTP POST request format, required fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Create a release link + +
+ POST + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/links/ +
+ +
+
+ +Creates a new link attached to a release. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Title or description of the link. + + + + + +URL of the external resource. Must be unique within the release. + + + + + +Arbitrary metadata to store alongside the link. Defaults to `{}`. + + + +
+
+ +
+ +### Scopes + +`releases.links:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", + "created_at": "2025-03-03T11:00:00.000000Z", + "updated_at": "2025-03-03T11:00:00.000000Z", + "deleted_at": null, + "title": "Release notes", + "url": "https://example.com/releases/v2.4.0", + "metadata": {}, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + + + +
+
diff --git a/docs/api-reference/release/add-release-tag.md b/docs/api-reference/release/add-release-tag.md new file mode 100644 index 00000000..c5a98c96 --- /dev/null +++ b/docs/api-reference/release/add-release-tag.md @@ -0,0 +1,165 @@ +--- +title: Create a release tag +description: Create a release tag via Plane API. HTTP POST request format, required fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Create a release tag + +
+ POST + /api/v1/workspaces/{workspace_slug}/releases/tags/ +
+ +
+
+ +Creates a new release tag in a workspace. `version` must be unique per workspace; if `project` is set, it must be unique per project. Duplicate versions return a 400 with code `RELEASE_TAG_VERSION_ALREADY_EXISTS`. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Version string for the release tag, for example `2.4.0`. + + + + + +Plain text description of the release tag. + + + + + +Commit hash the release tag points to. + + + + + +Name of the corresponding git tag, for example `v2.4.0`. + + + + + +ID of the project to scope this release tag to. When omitted, the release tag is workspace-wide. + + + +
+
+ +
+ +### Scopes + +`releases.tags:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "9f8e7d6c-5b4a-3210-fedc-ba0987654321", + "created_at": "2025-03-01T10:00:00.000000Z", + "updated_at": "2025-03-01T10:00:00.000000Z", + "deleted_at": null, + "version": "2.4.0", + "description": "Spring release tag", + "commit_hash": "9fceb02d0ae598e95dc970b74767f19372d61af8", + "git_tag": "v2.4.0", + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/add-release-work-items.md b/docs/api-reference/release/add-release-work-items.md new file mode 100644 index 00000000..fe132163 --- /dev/null +++ b/docs/api-reference/release/add-release-work-items.md @@ -0,0 +1,130 @@ +--- +title: Add work items to release +description: Add work items to release via Plane API. HTTP POST request format, required fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Add work items to release + +
+ POST + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/work-items/ +
+ +
+
+ +Adds one or more work items to a release. Work items already linked to the release are skipped. For a project-scoped release, every work item must belong to that project, otherwise the request fails with a 400 `RELEASE_WORK_ITEM_OUT_OF_SCOPE` error. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Array of work item IDs to add to the release. + + + +
+
+ +
+ +### Scopes + +`releases.work_items:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "message": "Work items added successfully" +} +``` + + + +
+
diff --git a/docs/api-reference/release/add-release.md b/docs/api-reference/release/add-release.md new file mode 100644 index 00000000..eb8d4384 --- /dev/null +++ b/docs/api-reference/release/add-release.md @@ -0,0 +1,231 @@ +--- +title: Create a release +description: Create a release via Plane API. HTTP POST request format, required fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Create a release + +
+ POST + /api/v1/workspaces/{workspace_slug}/releases/ +
+ +
+
+ +Creates a new workspace-level release. `name` must be unique within the workspace, otherwise a 400 `RELEASE_NAME_ALREADY_EXISTS` error is returned. If `tag` is provided, it must reference a global release tag or a tag belonging to the same project, otherwise a 400 `{"tag": "RELEASE_TAG_OUT_OF_SCOPE"}` error is returned. Any `project` value in the request body is ignored; releases created through this endpoint are always workspace-level. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Name of the release. + + + + + +HTML description of the release. + + + + + +JSON description of the release. + + + + + +Status of the release. Can be: `unreleased`, `released`, `cancelled`. Defaults to `unreleased`. + + + + + +Target date of the release in YYYY-MM-DD format. + + + + + +Actual release date of the release in YYYY-MM-DD format. + + + + + +ID of the user who leads the release. + + + + + +ID of the release tag associated with the release. + + + + + +Whether this is the latest release. Defaults to `false`. + + + + + +Whether this release is a prerelease. Defaults to `false`. + + + + + +External ID from an external source. + + + + + +External source identifier. + + + +
+
+ +
+ +### Scopes + +`releases:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "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": "

Spring feature release.

", + "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": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/delete-project-release.md b/docs/api-reference/release/delete-project-release.md new file mode 100644 index 00000000..fac8882c --- /dev/null +++ b/docs/api-reference/release/delete-project-release.md @@ -0,0 +1,108 @@ +--- +title: Delete a project release +description: Permanently delete a project release via Plane API. Removes the release. Returns 204 on success. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Delete a project release + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/projects/{project_id}/releases/{release_id}/ +
+ +
+
+ +Permanently deletes a release scoped to a project. This action cannot be undone. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier of the project. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Scopes + +`releases:write` + +
+ +
+
+ + + + + + + + + +```json +// 204 No Content +``` + + + +
+
diff --git a/docs/api-reference/release/delete-release-comment.md b/docs/api-reference/release/delete-release-comment.md new file mode 100644 index 00000000..521de027 --- /dev/null +++ b/docs/api-reference/release/delete-release-comment.md @@ -0,0 +1,108 @@ +--- +title: Delete a release comment +description: Permanently delete a release comment via Plane API. Removes the comment. Returns 204 on success. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Delete a release comment + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/comments/{comment_id}/ +
+ +
+
+ +Permanently deletes a comment from a release. This action cannot be undone. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + + + +The unique identifier for the comment. + + + +
+
+ +
+ +### Scopes + +`releases.comments:write` + +
+ +
+
+ + + + + + + + + +```json +// 204 No Content +``` + + + +
+
diff --git a/docs/api-reference/release/delete-release-label.md b/docs/api-reference/release/delete-release-label.md new file mode 100644 index 00000000..376a6afd --- /dev/null +++ b/docs/api-reference/release/delete-release-label.md @@ -0,0 +1,101 @@ +--- +title: Delete a release label +description: Permanently delete a release label via Plane API. Removes the label from the workspace catalog. Returns 204 on success. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Delete a release label + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/releases/labels/{label_id}/ +
+ +
+
+ +Permanently deletes a release label from the workspace label catalog. This action cannot be undone. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release label. + + + +
+
+ +
+ +### Scopes + +`releases.labels:write` + +
+ +
+
+ + + + + + + + + +```json +// 204 No Content +``` + + + +
+
diff --git a/docs/api-reference/release/delete-release-link.md b/docs/api-reference/release/delete-release-link.md new file mode 100644 index 00000000..f40733b0 --- /dev/null +++ b/docs/api-reference/release/delete-release-link.md @@ -0,0 +1,108 @@ +--- +title: Delete a release link +description: Permanently delete a release link via Plane API. Removes the link. Returns 204 on success. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Delete a release link + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/links/{link_id}/ +
+ +
+
+ +Permanently deletes a link from a release. This action cannot be undone. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + + + +The unique identifier for the link. + + + +
+
+ +
+ +### Scopes + +`releases.links:write` + +
+ +
+
+ + + + + + + + + +```json +// 204 No Content +``` + + + +
+
diff --git a/docs/api-reference/release/delete-release-tag.md b/docs/api-reference/release/delete-release-tag.md new file mode 100644 index 00000000..6bc98f12 --- /dev/null +++ b/docs/api-reference/release/delete-release-tag.md @@ -0,0 +1,99 @@ +--- +title: Delete a release tag +description: Permanently delete a release tag via Plane API. Removes the release tag. Returns 204 on success. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Delete a release tag + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/releases/tags/{tag_id}/ +
+ +
+
+ +Permanently deletes a release tag from a workspace. This action cannot be undone. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release tag. + + + +
+
+ +
+ +### Scopes + +`releases.tags:write` + +
+ +
+
+ + + + + + + + + +```json +// 204 No Content +``` + + + +
+
diff --git a/docs/api-reference/release/delete-release.md b/docs/api-reference/release/delete-release.md new file mode 100644 index 00000000..f2734af2 --- /dev/null +++ b/docs/api-reference/release/delete-release.md @@ -0,0 +1,102 @@ +--- +title: Delete a release +description: Permanently delete a release via Plane API. Removes the release. Returns 204 on success. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Delete a release + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/ +
+ +
+
+ +Permanently deletes a workspace-level release. This action cannot be undone. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Scopes + +`releases:write` + +
+ +
+
+ + + + + + + + + +```json +// 204 No Content +``` + + + +
+
diff --git a/docs/api-reference/release/get-project-release-detail.md b/docs/api-reference/release/get-project-release-detail.md new file mode 100644 index 00000000..57e13b42 --- /dev/null +++ b/docs/api-reference/release/get-project-release-detail.md @@ -0,0 +1,133 @@ +--- +title: Retrieve a project release +description: Get retrieve a project release details via Plane API. Retrieve complete information for a specific resource. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Retrieve a project release + +
+ GET + /api/v1/workspaces/{workspace_slug}/projects/{project_id}/releases/{release_id}/ +
+ +
+
+ +Retrieves the details of an existing release scoped to a project by its ID. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier of the project. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Scopes + +`releases:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "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": "

Spring feature release.

", + "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" +} +``` + + + +
+
diff --git a/docs/api-reference/release/get-release-changelog.md b/docs/api-reference/release/get-release-changelog.md new file mode 100644 index 00000000..3e34e1f1 --- /dev/null +++ b/docs/api-reference/release/get-release-changelog.md @@ -0,0 +1,114 @@ +--- +title: Retrieve a release changelog +description: Get retrieve a release changelog details via Plane API. Retrieve complete information for a specific resource. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Retrieve a release changelog + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/changelog/ +
+ +
+
+ +Retrieves the changelog for a release. The changelog is created empty the first time it is accessed, so this request never returns a 404 for an existing release. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Scopes + +`releases:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "5d4c3b2a-1908-4756-8fed-cba987654321", + "created_at": "2025-03-01T10:05:00.000000Z", + "updated_at": "2025-03-05T14:40:00.000000Z", + "deleted_at": null, + "changelog": { + "description_html": "

Added dark mode. Fixed login redirect loop.

", + "description_binary": null, + "description_stripped": "Added dark mode. Fixed login redirect loop.", + "description_json": {} + }, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + + + +
+
diff --git a/docs/api-reference/release/get-release-comment-detail.md b/docs/api-reference/release/get-release-comment-detail.md new file mode 100644 index 00000000..1cce8670 --- /dev/null +++ b/docs/api-reference/release/get-release-comment-detail.md @@ -0,0 +1,127 @@ +--- +title: Retrieve a release comment +description: Get retrieve a release comment details via Plane API. Retrieve complete information for a specific resource. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Retrieve a release comment + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/comments/{comment_id}/ +
+ +
+
+ +Retrieves the details of an existing release comment by its ID. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + + + +The unique identifier for the comment. + + + +
+
+ +
+ +### Scopes + +`releases.comments:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "c0ffee00-1111-2222-3333-444444444444", + "created_at": "2025-03-02T09:15:00.000000Z", + "updated_at": "2025-03-02T09:15:00.000000Z", + "deleted_at": null, + "comment": { + "description_html": "

QA sign-off complete.

", + "description_binary": null, + "description_stripped": "QA sign-off complete.", + "description_json": {} + }, + "is_hidden": false, + "edited_at": null, + "is_resolved": false, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "parent": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/get-release-detail.md b/docs/api-reference/release/get-release-detail.md new file mode 100644 index 00000000..fc218a43 --- /dev/null +++ b/docs/api-reference/release/get-release-detail.md @@ -0,0 +1,127 @@ +--- +title: Retrieve a release +description: Get retrieve a release details via Plane API. Retrieve complete information for a specific resource. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Retrieve a release + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/ +
+ +
+
+ +Retrieves the details of an existing workspace-level release by its ID. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Scopes + +`releases:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "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": "

Spring feature release.

", + "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": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/get-release-label-detail.md b/docs/api-reference/release/get-release-label-detail.md new file mode 100644 index 00000000..6d9b44dd --- /dev/null +++ b/docs/api-reference/release/get-release-label-detail.md @@ -0,0 +1,109 @@ +--- +title: Retrieve a release label +description: Get retrieve a release label details via Plane API. Retrieve complete information for a specific resource. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Retrieve a release label + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/labels/{label_id}/ +
+ +
+
+ +Retrieves the details of an existing release label by its ID. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release label. + + + +
+
+ +
+ +### Scopes + +`releases.labels:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "f6a7b8c9-d0e1-2345-fabc-678901234567", + "name": "Breaking change", + "color": "#FF5630", + "sort_order": 10, + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/get-release-link-detail.md b/docs/api-reference/release/get-release-link-detail.md new file mode 100644 index 00000000..612d3cf2 --- /dev/null +++ b/docs/api-reference/release/get-release-link-detail.md @@ -0,0 +1,120 @@ +--- +title: Retrieve a release link +description: Get retrieve a release link details via Plane API. Retrieve complete information for a specific resource. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Retrieve a release link + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/links/{link_id}/ +
+ +
+
+ +Retrieves the details of an existing release link by its ID. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + + + +The unique identifier for the link. + + + +
+
+ +
+ +### Scopes + +`releases.links:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", + "created_at": "2025-03-03T11:00:00.000000Z", + "updated_at": "2025-03-03T11:00:00.000000Z", + "deleted_at": null, + "title": "Release notes", + "url": "https://example.com/releases/v2.4.0", + "metadata": {}, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + + + +
+
diff --git a/docs/api-reference/release/get-release-tag-detail.md b/docs/api-reference/release/get-release-tag-detail.md new file mode 100644 index 00000000..c779470d --- /dev/null +++ b/docs/api-reference/release/get-release-tag-detail.md @@ -0,0 +1,112 @@ +--- +title: Retrieve a release tag +description: Get retrieve a release tag details via Plane API. Retrieve complete information for a specific resource. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Retrieve a release tag + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/tags/{tag_id}/ +
+ +
+
+ +Retrieves the details of an existing release tag by its ID. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release tag. + + + +
+
+ +
+ +### Scopes + +`releases.tags:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "9f8e7d6c-5b4a-3210-fedc-ba0987654321", + "created_at": "2025-03-01T10:00:00.000000Z", + "updated_at": "2025-03-05T14:30:00.000000Z", + "deleted_at": null, + "version": "2.4.0", + "description": "Spring release tag", + "commit_hash": "9fceb02d0ae598e95dc970b74767f19372d61af8", + "git_tag": "v2.4.0", + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/list-labels-for-release.md b/docs/api-reference/release/list-labels-for-release.md new file mode 100644 index 00000000..4670ec2a --- /dev/null +++ b/docs/api-reference/release/list-labels-for-release.md @@ -0,0 +1,142 @@ +--- +title: List labels for a release +description: List labels for a release via Plane API. HTTP GET request with pagination, filtering, and query parameters. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# List labels for a release + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/labels/ +
+ +
+
+ +Returns a list of all labels attached to a release. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Number of results per page. Defaults to 20. + + + + + +Cursor string for pagination in the format `value:offset:is_prev`. + + + +
+
+ +
+ +### Scopes + +`releases:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "next_cursor": "20:1:0", + "prev_cursor": "", + "next_page_results": false, + "prev_page_results": false, + "count": 1, + "total_pages": 1, + "total_results": 1, + "extra_stats": null, + "results": [ + { + "id": "f6a7b8c9-d0e1-2345-fabc-678901234567", + "name": "Breaking change", + "color": "#FF5630", + "sort_order": 10, + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null + } + ] +} +``` + + + +
+
diff --git a/docs/api-reference/release/list-project-releases.md b/docs/api-reference/release/list-project-releases.md new file mode 100644 index 00000000..7ff4ef74 --- /dev/null +++ b/docs/api-reference/release/list-project-releases.md @@ -0,0 +1,157 @@ +--- +title: List all project releases +description: List all releases for a project via Plane API. HTTP GET request with pagination, filtering, and query parameters. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# List all project releases + +
+ GET + /api/v1/workspaces/{workspace_slug}/projects/{project_id}/releases/ +
+ +
+
+ +Returns a list of all releases scoped to a project. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier of the project. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Number of results per page. Defaults to 20. + + + + + +Cursor string for pagination in the format `value:offset:is_prev`. + + + +
+
+ +
+ +### Scopes + +`releases:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "next_cursor": "20:1:0", + "prev_cursor": "", + "next_page_results": false, + "prev_page_results": false, + "count": 1, + "total_pages": 1, + "total_results": 1, + "extra_stats": null, + "results": [ + { + "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": "

Spring feature release.

", + "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" + } + ] +} +``` + + + +
+
diff --git a/docs/api-reference/release/list-release-comments.md b/docs/api-reference/release/list-release-comments.md new file mode 100644 index 00000000..6d4c2ce4 --- /dev/null +++ b/docs/api-reference/release/list-release-comments.md @@ -0,0 +1,154 @@ +--- +title: List all release comments +description: List all release comments via Plane API. HTTP GET request with pagination, filtering, and query parameters. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# List all release comments + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/comments/ +
+ +
+
+ +Returns a list of all comments on a release. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Number of results per page. Defaults to 20. + + + + + +Cursor string for pagination in the format `value:offset:is_prev`. + + + +
+
+ +
+ +### Scopes + +`releases.comments:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "next_cursor": "20:1:0", + "prev_cursor": "", + "next_page_results": false, + "prev_page_results": false, + "count": 1, + "total_pages": 1, + "total_results": 1, + "extra_stats": null, + "results": [ + { + "id": "c0ffee00-1111-2222-3333-444444444444", + "created_at": "2025-03-02T09:15:00.000000Z", + "updated_at": "2025-03-02T09:15:00.000000Z", + "deleted_at": null, + "comment": { + "description_html": "

QA sign-off complete.

", + "description_binary": null, + "description_stripped": "QA sign-off complete.", + "description_json": {} + }, + "is_hidden": false, + "edited_at": null, + "is_resolved": false, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "parent": null + } + ] +} +``` + + + +
+
diff --git a/docs/api-reference/release/list-release-labels.md b/docs/api-reference/release/list-release-labels.md new file mode 100644 index 00000000..2bdbb62f --- /dev/null +++ b/docs/api-reference/release/list-release-labels.md @@ -0,0 +1,139 @@ +--- +title: List all release labels +description: List all release labels via Plane API. HTTP GET request with pagination, filtering, and query parameters. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# List all release labels + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/labels/ +
+ +
+
+ +Returns a list of all release labels in the workspace label catalog, ordered by `sort_order`. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Return labels owned by this project. When omitted, only workspace-wide labels are returned. + + + + + +Number of results per page. Defaults to 20. + + + + + +Cursor string for pagination in the format `value:offset:is_prev`. + + + +
+
+ +
+ +### Scopes + +`releases.labels:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "next_cursor": "20:1:0", + "prev_cursor": "", + "next_page_results": false, + "prev_page_results": false, + "count": 1, + "total_pages": 1, + "total_results": 1, + "extra_stats": null, + "results": [ + { + "id": "f6a7b8c9-d0e1-2345-fabc-678901234567", + "name": "Breaking change", + "color": "#FF5630", + "sort_order": 10, + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null + } + ] +} +``` + + + +
+
diff --git a/docs/api-reference/release/list-release-links.md b/docs/api-reference/release/list-release-links.md new file mode 100644 index 00000000..f175f08c --- /dev/null +++ b/docs/api-reference/release/list-release-links.md @@ -0,0 +1,147 @@ +--- +title: List all release links +description: List all release links via Plane API. HTTP GET request with pagination, filtering, and query parameters. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# List all release links + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/links/ +
+ +
+
+ +Returns a list of all links attached to a release. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Number of results per page. Defaults to 20. + + + + + +Cursor string for pagination in the format `value:offset:is_prev`. + + + +
+
+ +
+ +### Scopes + +`releases.links:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "next_cursor": "20:1:0", + "prev_cursor": "", + "next_page_results": false, + "prev_page_results": false, + "count": 1, + "total_pages": 1, + "total_results": 1, + "extra_stats": null, + "results": [ + { + "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", + "created_at": "2025-03-03T11:00:00.000000Z", + "updated_at": "2025-03-03T11:00:00.000000Z", + "deleted_at": null, + "title": "Release notes", + "url": "https://example.com/releases/v2.4.0", + "metadata": {}, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + } + ] +} +``` + + + +
+
diff --git a/docs/api-reference/release/list-release-tags.md b/docs/api-reference/release/list-release-tags.md new file mode 100644 index 00000000..6b833023 --- /dev/null +++ b/docs/api-reference/release/list-release-tags.md @@ -0,0 +1,145 @@ +--- +title: List all release tags +description: List all release tags via Plane API. HTTP GET request with pagination, filtering, and query parameters. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# List all release tags + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/tags/ +
+ +
+
+ +Returns a list of all release tags in a workspace. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Return release tags owned by this project. When omitted, only workspace-wide release tags are returned. + + + + + +Number of results per page. Defaults to 20. + + + + + +Cursor string for pagination in the format `value:offset:is_prev`. + + + +
+
+ +
+ +### Scopes + +`releases.tags:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "next_cursor": "20:1:0", + "prev_cursor": "", + "next_page_results": false, + "prev_page_results": false, + "count": 1, + "total_pages": 1, + "total_results": 1, + "extra_stats": null, + "results": [ + { + "id": "9f8e7d6c-5b4a-3210-fedc-ba0987654321", + "created_at": "2025-03-01T10:00:00.000000Z", + "updated_at": "2025-03-05T14:30:00.000000Z", + "deleted_at": null, + "version": "2.4.0", + "description": "Spring release tag", + "commit_hash": "9fceb02d0ae598e95dc970b74767f19372d61af8", + "git_tag": "v2.4.0", + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null + } + ] +} +``` + + + +
+
diff --git a/docs/api-reference/release/list-release-work-items.md b/docs/api-reference/release/list-release-work-items.md new file mode 100644 index 00000000..a70a179c --- /dev/null +++ b/docs/api-reference/release/list-release-work-items.md @@ -0,0 +1,144 @@ +--- +title: List all work items in a release +description: List all work items in a release via Plane API. HTTP GET request with pagination, filtering, and query parameters. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# List all work items in a release + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/work-items/ +
+ +
+
+ +Returns a list of all work items linked to a release. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Number of results per page. Defaults to 20. + + + + + +Cursor string for pagination in the format `value:offset:is_prev`. + + + +
+
+ +
+ +### Scopes + +`releases.work_items:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "next_cursor": "20:1:0", + "prev_cursor": "", + "next_page_results": false, + "prev_page_results": false, + "count": 2, + "total_pages": 1, + "total_results": 2, + "extra_stats": null, + "results": [ + { + "id": "d4e5f6a7-b8c9-0123-defa-456789012345", + "project_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", + "name": "Fix login redirect" + }, + { + "id": "e5f6a7b8-c9d0-1234-efab-567890123456", + "project_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", + "name": "Add SSO support for enterprise plan" + } + ] +} +``` + + + +
+
diff --git a/docs/api-reference/release/list-releases.md b/docs/api-reference/release/list-releases.md new file mode 100644 index 00000000..78407345 --- /dev/null +++ b/docs/api-reference/release/list-releases.md @@ -0,0 +1,151 @@ +--- +title: List all releases +description: List all releases via Plane API. HTTP GET request with pagination, filtering, and query parameters. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# List all releases + +
+ GET + /api/v1/workspaces/{workspace_slug}/releases/ +
+ +
+
+ +Returns a list of all workspace-level releases (releases where `project` is `null`). + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + +
+
+ +
+ +### Query Parameters + +
+ + + +Number of results per page. Defaults to 20. + + + + + +Cursor string for pagination in the format `value:offset:is_prev`. + + + +
+
+ +
+ +### Scopes + +`releases:read` + +
+ +
+
+ + + + + + + + + +```json +{ + "next_cursor": "20:1:0", + "prev_cursor": "", + "next_page_results": false, + "prev_page_results": false, + "count": 1, + "total_pages": 1, + "total_results": 1, + "extra_stats": null, + "results": [ + { + "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": "

Spring feature release.

", + "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": null + } + ] +} +``` + + + +
+
diff --git a/docs/api-reference/release/overview.md b/docs/api-reference/release/overview.md new file mode 100644 index 00000000..2c6b5596 --- /dev/null +++ b/docs/api-reference/release/overview.md @@ -0,0 +1,214 @@ +--- +title: Overview +description: Plane Release API overview. Learn about endpoints, request/response format, and how to work with releases via REST API. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Overview + +Releases let you plan, track, and ship versions of your product. A release groups work items, carries a version tag, labels, links, comments, and a changelog, and can be scoped to the whole workspace or to a single project. + +[Learn more about Releases](https://docs.plane.so/releases) + +Releases are available on paid plans. Requests return `402 Payment Required` when the feature is not enabled for the workspace. + +
+
+ +## The Release Object + +### Attributes + +- `id` _uuid_ + + Unique identifier for the release + +- `name` _string_ **(required)** + + Name of the release. Must be unique within the workspace, otherwise a 400 `RELEASE_NAME_ALREADY_EXISTS` error is returned. + +- `description` _object_ + + Read-only nested description object with `description_html`, `description_binary`, `description_stripped`, and `description_json` + +- `description_html` _string_ (write-only) + + HTML description used to set the release's description on create/update + +- `description_json` _object_ (write-only) + + JSON description used to set the release's description on create/update + +- `status` _string_ + + Status of the release. Can be: `unreleased`, `released`, `cancelled`. Defaults to `unreleased` + +- `target_date` _date_ + + Target date for the release in YYYY-MM-DD format + +- `release_date` _date_ + + Actual release date in YYYY-MM-DD format + +- `lead` _uuid_ + + User ID of the release lead + +- `tag` _uuid_ + + ID of the release tag associated with the release. Must reference a global tag or a tag belonging to the same project, otherwise a 400 `{"tag": "RELEASE_TAG_OUT_OF_SCOPE"}` error is returned. + +- `is_latest` _boolean_ + + Whether this is the latest release. Defaults to `false` + +- `is_prerelease` _boolean_ + + Whether this release is a prerelease. Defaults to `false` + +- `project` _uuid_ + + ID of the project the release belongs to. `null` for workspace-level releases. Immutable after creation; ignored on update. + +- `external_id` _string_ + + External ID from an external source + +- `external_source` _string_ + + External source identifier + +- `workspace` _uuid_ + + Workspace UUID which is automatically saved + +- `created_at` _timestamp_ + + The timestamp when the release was created + +- `updated_at` _timestamp_ + + The timestamp when the release was last updated + +- `deleted_at` _timestamp_ + + The timestamp when the release was deleted, if applicable + +- `created_by` _uuid_ + + ID of the user who created the release + +- `updated_by` _uuid_ + + ID of the user who last updated the release + +## Related objects + +### Release Tag + +- `id` _uuid_ +- `version` _string_ **(required)** — must be unique within the workspace or project, otherwise 400 `{"version": "RELEASE_TAG_VERSION_ALREADY_EXISTS"}` +- `description` _string_ — plain text +- `commit_hash` _string_ +- `git_tag` _string_ +- `project` _uuid_ — `null` for a workspace-wide tag; immutable after creation +- `workspace` _uuid_ +- `created_at` _timestamp_ +- `updated_at` _timestamp_ +- `deleted_at` _timestamp_ +- `created_by` _uuid_ +- `updated_by` _uuid_ + +### Release Label + +- `id` _uuid_ +- `name` _string_ **(required)** — must be unique within the workspace or project, otherwise 400 `{"name": "RELEASE_LABEL_NAME_ALREADY_EXISTS"}` +- `color` _string_ — defaults to `#4E5355` +- `sort_order` _integer_ — defaults to `0` +- `workspace` _uuid_ +- `project` _uuid_ — `null` for a workspace-wide label; immutable after creation + +### Release Comment + +- `id` _uuid_ +- `release` _uuid_ (read-only) +- `comment` _object_ — read-only nested description object, same shape as the release's `description` +- `comment_html` _string_ (write-only) +- `parent` _uuid_ — parent comment for threaded replies +- `edited_at` _timestamp_ +- `is_resolved` _boolean_ — defaults to `false` +- `is_hidden` _boolean_ (read-only) +- `workspace` _uuid_ +- `created_at` _timestamp_ +- `updated_at` _timestamp_ +- `deleted_at` _timestamp_ +- `created_by` _uuid_ +- `updated_by` _uuid_ + +### Release Link + +- `id` _uuid_ +- `release` _uuid_ (read-only) +- `title` _string_ **(required)** +- `url` _string_ **(required)** — must be a valid URL, unique per release +- `metadata` _object_ — defaults to `{}` +- `workspace` _uuid_ +- `created_at` _timestamp_ +- `updated_at` _timestamp_ +- `deleted_at` _timestamp_ +- `created_by` _uuid_ +- `updated_by` _uuid_ + +### Release Changelog + +- `id` _uuid_ +- `release` _uuid_ (read-only) +- `changelog` _object_ — read-only nested description object, same shape as the release's `description` +- `description_html` _string_ (write-only) +- `description_json` _object_ (write-only) +- `workspace` _uuid_ +- `created_at` _timestamp_ +- `updated_at` _timestamp_ +- `deleted_at` _timestamp_ +- `created_by` _uuid_ +- `updated_by` _uuid_ + +
+
+ + + +```json +{ + "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": "

Spring feature release.

", + "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": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/remove-labels-from-release.md b/docs/api-reference/release/remove-labels-from-release.md new file mode 100644 index 00000000..c64669cb --- /dev/null +++ b/docs/api-reference/release/remove-labels-from-release.md @@ -0,0 +1,127 @@ +--- +title: Remove labels from release +description: Delete labels from release via Plane API. HTTP DELETE request for removing resources. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Remove labels from release + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/labels/ +
+ +
+
+ +Removes one or more labels from a release. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Array of release label IDs to remove from the release. + + + +
+
+ +
+ +### Scopes + +`releases:write` + +
+ +
+
+ + + + + + + + + +```json +// 204 No Content +``` + + + +
+
diff --git a/docs/api-reference/release/remove-release-work-items.md b/docs/api-reference/release/remove-release-work-items.md new file mode 100644 index 00000000..e0e33c6b --- /dev/null +++ b/docs/api-reference/release/remove-release-work-items.md @@ -0,0 +1,127 @@ +--- +title: Remove work items from release +description: Remove work items from release via Plane API. HTTP DELETE request for removing resources. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Remove work items from release + +
+ DELETE + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/work-items/ +
+ +
+
+ +Removes one or more work items from a release. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Array of work item IDs to remove from the release. + + + +
+
+ +
+ +### Scopes + +`releases.work_items:write` + +
+ +
+
+ + + + + + + + + +```json +// 204 No Content +``` + + + +
+
diff --git a/docs/api-reference/release/update-project-release-detail.md b/docs/api-reference/release/update-project-release-detail.md new file mode 100644 index 00000000..f795c56d --- /dev/null +++ b/docs/api-reference/release/update-project-release-detail.md @@ -0,0 +1,228 @@ +--- +title: Update a project release +description: Update a project release via Plane API. HTTP PATCH request format, editable fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Update a project release + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/projects/{project_id}/releases/{release_id}/ +
+ +
+
+ +Updates an existing release scoped to a project by setting the values of the parameters passed. Any parameters not provided will be left unchanged. `name` must remain unique within the workspace, otherwise a 400 `RELEASE_NAME_ALREADY_EXISTS` error is returned. If `tag` is provided, it must reference a global release tag or a tag belonging to this project, otherwise a 400 `{"tag": "RELEASE_TAG_OUT_OF_SCOPE"}` error is returned. `project` cannot be changed and is ignored if passed. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier of the project. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Name of the release. + + + + + +HTML description of the release. + + + + + +JSON description of the release. + + + + + +Status of the release. Can be: `unreleased`, `released`, `cancelled`. + + + + + +Target date of the release in YYYY-MM-DD format. + + + + + +Actual release date of the release in YYYY-MM-DD format. + + + + + +ID of the user who leads the release. + + + + + +ID of the release tag associated with the release. + + + + + +Whether this is the latest release. + + + + + +Whether this release is a prerelease. + + + + + +External ID from an external source. + + + + + +External source identifier. + + + +
+
+ +
+ +### Scopes + +`releases:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "created_at": "2025-03-01T10:00:00.000000Z", + "updated_at": "2025-04-02T09:00:00.000000Z", + "deleted_at": null, + "name": "v2.4.0", + "description": { + "description_html": "

Spring feature release.

", + "description_binary": null, + "description_stripped": "Spring feature release.", + "description_json": {} + }, + "status": "released", + "target_date": "2025-03-31", + "release_date": "2025-04-02", + "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" +} +``` + + + +
+
diff --git a/docs/api-reference/release/update-release-changelog.md b/docs/api-reference/release/update-release-changelog.md new file mode 100644 index 00000000..2c1c88bf --- /dev/null +++ b/docs/api-reference/release/update-release-changelog.md @@ -0,0 +1,149 @@ +--- +title: Update a release changelog +description: Update a release changelog via Plane API. HTTP PATCH request format, editable fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Update a release changelog + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/changelog/ +
+ +
+
+ +Updates the changelog for a release by setting the values of the parameters passed. Any parameters not provided will be left unchanged. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +HTML content for the changelog. Write-only; the stored value is returned in the response as the nested `changelog` object. + + + + + +Rich-text JSON content for the changelog. Write-only; the stored value is returned in the response as the nested `changelog` object. + + + +
+
+ +
+ +### Scopes + +`releases:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "5d4c3b2a-1908-4756-8fed-cba987654321", + "created_at": "2025-03-01T10:05:00.000000Z", + "updated_at": "2025-03-06T09:10:00.000000Z", + "deleted_at": null, + "changelog": { + "description_html": "

Added dark mode. Fixed login redirect loop.

", + "description_binary": null, + "description_stripped": "Added dark mode. Fixed login redirect loop.", + "description_json": {} + }, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + + + +
+
diff --git a/docs/api-reference/release/update-release-comment-detail.md b/docs/api-reference/release/update-release-comment-detail.md new file mode 100644 index 00000000..2657a947 --- /dev/null +++ b/docs/api-reference/release/update-release-comment-detail.md @@ -0,0 +1,177 @@ +--- +title: Update a release comment +description: Update a release comment via Plane API. HTTP PATCH request format, editable fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Update a release comment + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/comments/{comment_id}/ +
+ +
+
+ +Updates an existing release comment by setting the values of the parameters passed. Any parameters not provided will be left unchanged. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + + + +The unique identifier for the comment. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +HTML-formatted content of the comment. + + + + + +ID of the parent comment, for threaded replies. + + + + + +Whether the comment has been resolved. + + + + + +Timestamp when the comment was last edited, in ISO 8601 format. + + + +
+
+ +
+ +### Scopes + +`releases.comments:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "c0ffee00-1111-2222-3333-444444444444", + "created_at": "2025-03-02T09:15:00.000000Z", + "updated_at": "2025-03-02T10:05:00.000000Z", + "deleted_at": null, + "comment": { + "description_html": "

QA sign-off complete. Retested after hotfix.

", + "description_binary": null, + "description_stripped": "QA sign-off complete. Retested after hotfix.", + "description_json": {} + }, + "is_hidden": false, + "edited_at": "2025-03-02T10:05:00.000000Z", + "is_resolved": true, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "parent": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/update-release-detail.md b/docs/api-reference/release/update-release-detail.md new file mode 100644 index 00000000..7c549285 --- /dev/null +++ b/docs/api-reference/release/update-release-detail.md @@ -0,0 +1,222 @@ +--- +title: Update a release +description: Update a release via Plane API. HTTP PATCH request format, editable fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Update a release + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/ +
+ +
+
+ +Updates an existing workspace-level release by setting the values of the parameters passed. Any parameters not provided will be left unchanged. `name` must remain unique within the workspace, otherwise a 400 `RELEASE_NAME_ALREADY_EXISTS` error is returned. If `tag` is provided, it must reference a global release tag or a tag belonging to the same project, otherwise a 400 `{"tag": "RELEASE_TAG_OUT_OF_SCOPE"}` error is returned. `project` cannot be changed and is ignored if passed. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Name of the release. + + + + + +HTML description of the release. + + + + + +JSON description of the release. + + + + + +Status of the release. Can be: `unreleased`, `released`, `cancelled`. + + + + + +Target date of the release in YYYY-MM-DD format. + + + + + +Actual release date of the release in YYYY-MM-DD format. + + + + + +ID of the user who leads the release. + + + + + +ID of the release tag associated with the release. + + + + + +Whether this is the latest release. + + + + + +Whether this release is a prerelease. + + + + + +External ID from an external source. + + + + + +External source identifier. + + + +
+
+ +
+ +### Scopes + +`releases:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "created_at": "2025-03-01T10:00:00.000000Z", + "updated_at": "2025-04-02T09:00:00.000000Z", + "deleted_at": null, + "name": "v2.4.0", + "description": { + "description_html": "

Spring feature release.

", + "description_binary": null, + "description_stripped": "Spring feature release.", + "description_json": {} + }, + "status": "released", + "target_date": "2025-03-31", + "release_date": "2025-04-02", + "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": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/update-release-label-detail.md b/docs/api-reference/release/update-release-label-detail.md new file mode 100644 index 00000000..3ecdad84 --- /dev/null +++ b/docs/api-reference/release/update-release-label-detail.md @@ -0,0 +1,150 @@ +--- +title: Update a release label +description: Update a release label via Plane API. HTTP PATCH request format, editable fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Update a release label + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/releases/labels/{label_id}/ +
+ +
+
+ +Updates an existing release label by setting the values of the parameters passed. Any parameters not provided will be left unchanged. The label name must remain unique per workspace (or per project), otherwise the request fails with a 400 `RELEASE_LABEL_NAME_ALREADY_EXISTS` error. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release label. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Name of the release label. + + + + + +Hex color code for the label. + + + + + +Sort order for the label. + + + +
+
+ +
+ +### Scopes + +`releases.labels:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "f6a7b8c9-d0e1-2345-fabc-678901234567", + "name": "Breaking change", + "color": "#DE350B", + "sort_order": 5, + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null +} +``` + + + +
+
diff --git a/docs/api-reference/release/update-release-link-detail.md b/docs/api-reference/release/update-release-link-detail.md new file mode 100644 index 00000000..6e86d0a9 --- /dev/null +++ b/docs/api-reference/release/update-release-link-detail.md @@ -0,0 +1,161 @@ +--- +title: Update a release link +description: Update a release link via Plane API. HTTP PATCH request format, editable fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Update a release link + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/releases/{release_id}/links/{link_id}/ +
+ +
+
+ +Updates an existing release link by setting the values of the parameters passed. Any parameters not provided will be left unchanged. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release. + + + + + +The unique identifier for the link. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Title or description of the link. + + + + + +URL of the external resource. Must be unique within the release. + + + + + +Arbitrary metadata to store alongside the link. + + + +
+
+ +
+ +### Scopes + +`releases.links:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", + "created_at": "2025-03-03T11:00:00.000000Z", + "updated_at": "2025-03-03T11:20:00.000000Z", + "deleted_at": null, + "title": "Release notes (updated)", + "url": "https://example.com/releases/v2.4.0/notes", + "metadata": {}, + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "release": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + + + +
+
diff --git a/docs/api-reference/release/update-release-tag-detail.md b/docs/api-reference/release/update-release-tag-detail.md new file mode 100644 index 00000000..5a777df6 --- /dev/null +++ b/docs/api-reference/release/update-release-tag-detail.md @@ -0,0 +1,159 @@ +--- +title: Update a release tag +description: Update a release tag via Plane API. HTTP PATCH request format, editable fields, and example responses. +keywords: plane, plane api, rest api, api integration, releases, release management, versioning +--- + +# Update a release tag + +
+ PATCH + /api/v1/workspaces/{workspace_slug}/releases/tags/{tag_id}/ +
+ +
+
+ +Updates an existing release tag by setting the values of the parameters passed. Any parameters not provided will be left unchanged. `project` is immutable after creation and cannot be changed here. + +
+ +### Path Parameters + +
+ + + +The workspace_slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL. For example, in the URL `https://app.plane.so/my-team/projects/`, the workspace slug is `my-team`. + + + + + +The unique identifier for the release tag. + + + +
+
+ +
+ +### Body Parameters + +
+ + + +Version string for the release tag, for example `2.4.0`. + + + + + +Plain text description of the release tag. + + + + + +Commit hash the release tag points to. + + + + + +Name of the corresponding git tag, for example `v2.4.0`. + + + +
+
+ +
+ +### Scopes + +`releases.tags:write` + +
+ +
+
+ + + + + + + + + +```json +{ + "id": "9f8e7d6c-5b4a-3210-fedc-ba0987654321", + "created_at": "2025-03-01T10:00:00.000000Z", + "updated_at": "2025-03-06T08:45:00.000000Z", + "deleted_at": null, + "version": "2.4.0", + "description": "Spring release tag", + "commit_hash": "a3f9c1d8e7b6054321fedcba9876543210abcd1", + "git_tag": "v2.4.0", + "created_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "updated_by": "16c61a3a-512a-48ac-b0be-b6b46fe6f430", + "workspace": "cd4ab5a2-1a5f-4516-a6c6-8da1a9fa5be4", + "project": null +} +``` + + + +
+