Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
WRITE

link_pull_request

Links a pull request to a work item by hand, for one whose title, branch and body left the item's key out; composes the address, keeps the state given, and never moves the item.

Link a pull request that the repository's webhook could not match. Give work_item_id, repository_id (one of the project's live repositories) and number (without the hash), with title, url, author and state (open by default, or draft, merged, closed) when you have them; the address is composed from the repository's own when url is left out. The answer is the reference as the item now carries it; code.pull_request_linked goes out the first time, and linking the same number again refreshes the title, address and state. Linking never moves the item: the project's automatic moves (to review when a pull request opens, to QA or done when it merges) happen on the host's own word through the webhook, and a person or an agent moves an item by hand with move_work_item. Put the key in the pull request's title or branch next time and the webhook does this for you. It needs work-item:update; a client guest's token is refused.

Requires ability

work-item:update

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Annotations

Idempotent

Sending the same arguments twice changes nothing the second time.

work_item_id*string

UUID of the work item the pull request delivers.

repository_id*string

UUID of the project repository the pull request is on.

number*integer

The pull request number, without the hash.

titlestringoptional

The pull request's title, up to 500 characters.

urlstringoptional

Where it opens; composed from the repository when left out.

authorstringoptional

Who opened it, as the host names them.

statestringoptional

Where it stands; open by default.

openmergedcloseddraftpushed
{  "data": {    "id": "4d5e6f70-8192-4cad-8e1f-3a4b5c6d7e8f",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "work_item_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",    "reference": "CRM-142",    "work_item_title": "Apply a voucher at checkout",    "repository_id": "9e8d7c6b-5a49-4382-a716-05f4e3d2c1b0",    "repository_full_name": "zuse-technologies/portal",    "kind": "pull_request",    "external_id": "42",    "ref": "#42",    "title": "Voucher at checkout",    "url": "https://github.com/zuse-technologies/portal/pull/42",    "author": "nimal",    "state": "open",    "additions": null,    "deletions": null,    "opened_at": "2026-11-02T11:05:00+00:00",    "merged_at": null,    "closed_at": null,    "linked_by": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b",    "created_at": "2026-11-02T11:05:00+00:00",    "updated_at": "2026-11-02T11:05:00+00:00"  }}
VALIDATION_FAILED

repository_id or number missing or malformed, state not one of the values listed, or the repository is disconnected.

RESOURCE_NOT_FOUND

unknown work_item_id, or a repository_id that is not one of the item's project's repositories.

FORBIDDEN

the token is a client guest's, or the holder may not change the project's items.

TOKEN_MISSING_ABILITY

token lacks work-item:update.

Related

list_code_referenceswhat the item already carries.link_committhe same for a commit.move_work_itemmove the item yourself when the project's automatic moves are off.Code references APIthe same link over REST, and the unlink that stays there.

How is this guide?

Last updated on