Work item pages overview

A work item page is a link between a work item and a page. The link is the resource. It has its own id, and {pk} in these routes is that link id, not the page id. Deleting a link removes the association and leaves the page untouched.

A link has nothing to edit, so there is no PATCH. To point a work item at a different page, delete the link and create a new one.

Learn more about linking pages to work items

The work item page object

Attributes

• id string (uuid)

  Unique identifier for the link. Use it as {pk} to read or delete the link.

• page_id string (uuid)

  The linked page.

• work_item_id string (uuid)

  The work item the page is linked to.

• project_id string (uuid)

  The work item's project.

• 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 created the link.

• updated_by_id string (uuid) or null

  The user who last updated the link. null until someone updates it.

Get the page in the same call

Add ?expand=page to any read. Each link then carries a page object with the page's id, name, access, is_locked, and archived_at, next to page_id.

Response200

{
  "id": "c4e8a1f2-7b3d-4e59-9a06-2f1d8c5b7e34",
  "page_id": "9c1f0b3d-6d2e-4c9a-8b41-2f7e5a0d6c88",
  "work_item_id": "5d2a8e47-1c3b-4f96-b0e8-7a4c9d2f1b63",
  "project_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-01-14T09:22:41.478363Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by_id": null
}

Endpoints

Method	Path	Description
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/pages/	List work item pages
GET	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/pages/{pk}/	Get a work item page
POST	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/pages/	Create a work item page
DELETE	/api/v2/workspaces/{slug}/projects/{project_id}/work-items/{work_item_id}/pages/{pk}/	Delete a work item page

Which pages you can link

You can link any page in the workspace: a page in the work item's project, a page in another project, or a workspace (wiki) page. A page id from another workspace returns 400 invalid_request.

The API doesn't check whether you can see the page itself. You can link a private page that belongs to someone else, and ?expand=page on the link then returns that page's name.

A work item links to a page at most once. Linking the same page again returns 409 conflict. To check first, list the links with ?page_id=.

Creating and deleting a link each add an entry to the work item's activity.

Permissions

Every call needs page access in the project and a work item you can see. List, get, and create check the project's page permissions first and return 403 without them: reading needs page view access, and creating a link needs page create access. Then a work item you can't see, or one that isn't in the path's project, returns 404 with detail Work item not found. Delete checks in the other order: the work item and the link come first (404), then page delete access (403).

Response shaping

Every read accepts ?fields= for sparse responses and ?expand=page. See Sparse fields and Expanding relations. Errors follow the shared problem+json contract.

Changed from v1

• v2 returns the link flat, with page_id, work_item_id, and project_id. v1 always embeds the page and returns issue, project, and workspace. Use ?expand=page to embed the page in v2.
• Linking a page that's already linked returns 409 conflict. v1 returns 400 with PAGE_ALREADY_LINKED.
• A page_id that isn't in the workspace returns 400 invalid_request. v1 returns 404 with PAGE_NOT_FOUND.

See Migrating from v1 for the full list.