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

update_work_item

Changes a work item in part; the criteria, components and labels are replaced only when their list is sent, and every change writes a version.

Change a work item by work_item_id with any of title, type, description (HTML), epic_id, parent_id, priority, the four people, story_points, estimate_minutes, remaining_minutes, due_on, component_ids and label_ids (each replaces its list), the story fields persona_id, as_a, i_want, so_that, business_value_points and acceptance_criteria (replaces the list; a row with an id keeps and changes that criterion), the bug fields severity, environment_id, component_id, steps_to_reproduce, expected_result, actual_result, reproducible, and the spike fields timebox_minutes and outcome. A field left out keeps its value; a field sent as null is cleared. Changing the type drops the fields the new kind does not carry. The change goes through the same action the Backlog page runs, writes a version a person can put back, and work_item.updated goes out.

The status moves through move_work_item and the assignee may also move through assign_work_item. A staff token with work-item:update on the project is needed.

Requires ability

work-item:update

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

Runs the same action as

PATCH/v1/work-items/{item}

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Fires one event

work_item.updated

Delivered to every endpoint subscribed to it once the change is made.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

work_item_id*string

UUID of the work item.

titlestringoptional

The title, 3 to 200 characters.

typestringoptional

The kind; changing it drops the fields the new kind does not carry.

storytasksubtaskbugspikeimprovement
descriptionstringoptional

What the item is, as HTML.

epic_idstringoptional

UUID of the epic it hangs under.

sprint_idstringoptional

UUID of the planned or running sprint it is planned into; null for the backlog.

parent_idstringoptional

UUID of the story or task a sub-task or bug hangs under.

prioritystringoptional

How urgent it is; medium by default.

lowestlowmediumhighhighest
assignee_idstringoptional

UUID of the person doing the work.

reporter_idstringoptional

UUID of the person who raised it; the acting person when left out on a create.

reviewer_idstringoptional

UUID of the person who reviews the code.

qa_owner_idstringoptional

UUID of the person who verifies it.

story_pointsstringoptional

The estimate on the project's scale, as text such as 5 or M.

estimate_minutesintegeroptional

The estimate in minutes.

remaining_minutesintegeroptional

What is left, in minutes.

due_onstringoptional

When it is due, YYYY-MM-DD.

persona_idstringoptional

UUID of the persona a story is written as.

as_astringoptional

The persona of a story, as in "returning shopper".

i_wantstringoptional

What they want, as in "to reorder my last basket".

so_thatstringoptional

Why, as in "I do not pick every item again".

business_value_pointsintegeroptional

The value of a story, in points.

severitystringoptional

How badly a bug hurts.

blockercriticalmajorminortrivial
environment_idstringoptional

UUID of the environment a bug was seen in.

component_idstringoptional

UUID of the component a bug was found in.

steps_to_reproducestringoptional

How to make a bug happen, as HTML.

expected_resultstringoptional

What should have happened, as HTML.

actual_resultstringoptional

What happened, as HTML.

reproduciblestringoptional

How reliably a bug comes back.

alwayssometimesoncenot_reproduced
timebox_minutesintegeroptional

A spike's time box, in minutes.

outcomestringoptional

A spike's outcome, as HTML.

component_idsstring[]optional

UUIDs of the components the item touches; the list replaces the current one.

label_idsstring[]optional

UUIDs of the labels pinned on the item; the list replaces the current one.

acceptance_criteriaarrayoptional

The criteria that say when a story is done, replacing the list: objects with title (required), given, when, then and kind (functional, negative, edge or non_functional); a row with an id keeps that criterion.

What it returns

{  "data": {    "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "number": 8,    "reference": "SCL-8",    "type": "story",    "parent_id": null,    "epic_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",    "title": "Track my order from my phone",    "description": null,    "status": "backlog",    "resolution": null,    "priority": "medium",    "assignee_id": null,    "assignee_name": null,    "reporter_id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",    "reporter_name": "Bea Analyst",    "reviewer_id": null,    "qa_owner_id": null,    "story_points": "3",    "estimate_minutes": null,    "remaining_minutes": null,    "due_on": null,    "started_at": null,    "completed_at": null,    "persona_id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c",    "as_a": "busy parent",    "i_want": "to see where my laundry is",    "so_that": "I know when to collect it",    "business_value_points": null,    "severity": null,    "environment_id": null,    "component_id": null,    "steps_to_reproduce": null,    "expected_result": null,    "actual_result": null,    "reproducible": null,    "timebox_minutes": null,    "outcome": null,    "component_ids": [],    "labels": [],    "acceptance_criteria": [      {        "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",        "work_item_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",        "position": 1,        "title": "The status page shows the current stage and the next one",        "given": null,        "when": null,        "then": null,        "kind": "functional",        "verified_at": null,        "verified_by": null      }    ],    "position": 8,    "version": 2,    "approved_at": null,    "created_at": "2026-10-28T10:08:00+00:00",    "updated_at": "2026-10-28T10:20:00+00:00"  }}

How it fails

VALIDATION_FAILED

a field outside its limits, a value outside its set, an epic, parent, persona, component, environment or label that is not the project's, a parent the kind does not allow, a person who is not on the team, or a criterion without a title.

RESOURCE_NOT_FOUND

unknown work_item_id, or an item outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry work-item:update.

TOKEN_MISSING_ABILITY

token lacks work-item:update.

Related

get_work_itemthe item as it stands.move_work_itemthe status.assign_work_itemthe person doing the work.list_revisionsevery version the changes wrote.Work items APIthe same doors over REST.

How is this guide?

Last updated on