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

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 the request fails with a 400 RELEASE_NAME_ALREADY_EXISTS error.

• description object

  Read-only nested description object with description_html, description_binary, description_stripped, and description_json

• description_html string (write-only)

  HTML used to set the release's description when you create or update it

• description_json object (write-only)

  JSON used to set the release's description when you create or update it

• status string

  Status of the release: unreleased, released, or 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 the request fails with a 400 {"tag": "RELEASE_TAG_OUT_OF_SCOPE"} error.

• 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, set automatically

• 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

Response200

{
  "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": null
}