Project release links overview

Project release links attach external URLs, such as a build, a store listing, or a tag in your Git host, to a project release. They are the same object as release links on a workspace release, served under the project route.

Each URL can appear only once on a release. Adding a URL the release already links to returns 400 with an error on url.

Learn more about project releases

The project release link object

Attributes

• id string (uuid)

  Unique identifier for the link.

• release_id string (uuid)

  The release the link is on.

• title string

  The link's display title. Maximum 255 characters.

• url string (uri)

  The target URL. Maximum 200 characters, and unique on the release.

• metadata object

  Free-form JSON stored with the link. Defaults to {}.

• created_at string (date-time)

  When the link was created.

• updated_at string (date-time)

  When the link was last updated.

• created_by_id string (uuid)

  The user who added the link.

• updated_by_id string (uuid)

  The user who last updated the link.

Response200

{
  "id": "6c2e9a14-3d7b-4f85-a0e9-1b4d8c7f2e39",
  "release_id": "3e8a1f52-7c4b-4d9e-a6f1-0b2c5d8e9f14",
  "title": "GitHub release v4.2.0",
  "url": "https://github.com/acme/mobile/releases/tag/v4.2.0",
  "metadata": {},
  "created_at": "2026-02-26T18:10:44.209631Z",
  "updated_at": "2026-02-26T18:10:44.209631Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/projects/{project_id}/releases/{release_id}/links/	List project release links
GET	/api/v2/workspaces/{slug}/projects/{project_id}/releases/{release_id}/links/{pk}/	Get a project release link
POST	/api/v2/workspaces/{slug}/projects/{project_id}/releases/{release_id}/links/	Create a project release link
PATCH	/api/v2/workspaces/{slug}/projects/{project_id}/releases/{release_id}/links/{pk}/	Update a project release link
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/releases/{release_id}/links/{pk}/	Delete a project release link

Access follows the release

Links have no permissions of their own. Every request checks your access to the parent release in its project:

• Reading links needs view access to the release. Without it, list and get return 404, the same answer as for a release that doesn't exist.
• Creating a link needs view and edit access to the release. Without view access you get 404. With view access but no edit access you get 403.
• Updating or deleting a link needs edit access to the release, and returns 403 without it.

Every route also checks that the release belongs to the project in the path and that the link belongs to the release. A mismatch at either level returns 404.

These routes need the project releases entitlement on your plan, and return 402 payment_required without it. The workspace link routes at /api/v2/workspaces/{slug}/releases/{release_id}/links/ don't serve project releases and return 404 for them.

Response shaping

Every project release link read accepts ?fields= for sparse responses. See Sparse fields. Errors follow the shared problem+json contract.

Changed from v1

In v1, links on a project release were served on the workspace route, /api/v1/workspaces/{slug}/releases/{release_id}/links/. In v2 they live under the project route. See Migrating from v1.