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)

  The user who last updated the link.

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": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}

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.

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 a work item you can see. 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. After that check, the project's page permissions decide access. Reading needs page view access in the project, creating a link needs page create access, and deleting one needs page delete access.

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.