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 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

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
}