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

create_work_item

Adds a work item of any kind to a project's backlog, with everything set at once; the full form beside create_story_draft.

Add a work item: project_id and title are required; type is story by default or one of task, subtask, bug, spike, improvement; description (HTML), epic_id, parent_id (the story or task a sub-task or bug hangs under), priority (medium by default), status (backlog by default; later moves go through move_work_item), the four people, story_points, estimate_minutes, remaining_minutes, due_on, component_ids and label_ids apply to every kind. A story adds persona_id, as_a, i_want, so_that, business_value_points and acceptance_criteria; a bug adds severity, environment_id, component_id, steps_to_reproduce, expected_result, actual_result and reproducible; a spike adds timebox_minutes and outcome. The item takes the next number of the project, writes its first version and is announced as work_item.created.

create_story_draft remains the short road for a story; use this for a task, a bug or a spike, or for a story with the persona, the labels and the components set in one call. A staff token with work-item:create on the project is needed.

Requires ability

work-item:create

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

Annotations

Destructive

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

Arguments

project_id*string

UUID of the project.

title*string

The title, 3 to 200 characters.

typestringoptional

The kind; story by default.

storytasksubtaskbugspikeimprovement
statusstringoptional

Where it starts; backlog by default. Later moves go through move_work_item.

backlogreadyin_progressin_reviewin_qadonecancelled
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": 7,    "reference": "SCL-7",    "type": "task",    "parent_id": null,    "epic_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",    "title": "Set up the payment gateway sandbox",    "description": "<p>Request sandbox keys and wire the SDK behind a feature flag.</p>",    "status": "backlog",    "resolution": null,    "priority": "high",    "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": null,    "estimate_minutes": 240,    "remaining_minutes": null,    "due_on": null,    "started_at": null,    "completed_at": null,    "persona_id": null,    "as_a": null,    "i_want": null,    "so_that": null,    "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": ["c0a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b"],    "labels": [      {        "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",        "name": "payments",        "color": "emerald"      }    ],    "acceptance_criteria": [],    "position": 7,    "version": 1,    "approved_at": null,    "created_at": "2026-10-28T10:05:00+00:00",    "updated_at": "2026-10-28T10:05:00+00:00"  }}

How it fails

VALIDATION_FAILED

title missing or outside 3 to 200 characters, a type, priority, status, severity or reproducible outside its set, an epic_id, parent_id, persona_id, 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 project_id, or a project 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:create.

TOKEN_MISSING_ABILITY

token lacks work-item:create.

Related

create_story_draftthe short road for a story.update_work_itemchange it later.move_work_itemmove it along its lifecycle.Work items APIthe same door over REST.

How is this guide?

Last updated on