create_story_draft
Add a story to a project's backlog with its sentence, its epic, its priority and its acceptance criteria, as a draft a person reviews.
Add a story to a project's backlog: a title, the sentence in the persona's words (as_a, i_want, so_that), a description, the epic it hangs under, a priority and the acceptance criteria rows, each with its sentence, its kind and an optional Given, When and Then. The story takes the next number of the project's tracker sequence, starts in the backlog, names the person you act as its reporter and writes its first version with the criteria inside it; work_item.created goes out.
A bounded write: it creates one story and nothing else, so the person reviews it on the Backlog page before anyone builds it. Write the criteria as a tester would tick them, a functional row for the happy path, a negative row for what must be refused and an edge row for the boundary, and keep the title short. The epic must be an epic of the same project.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Arguments
project_id*stringUUID of the project the story belongs to.
title*stringWhat the story is called, 3 to 200 characters.
as_astringoptionalThe persona, as in "As a returning shopper".
i_wantstringoptionalWhat they want, as in "I want to reorder my last basket".
so_thatstringoptionalWhy, as in "so that I do not pick every item again".
descriptionstringoptionalWhat the story is, as HTML.
epic_idstringoptionalUUID of the epic it hangs under, an epic of the same project.
prioritystringoptionalHow urgent it is; medium by default.
lowestlowmediumhighhighestacceptance_criteriaarrayoptionalThe criteria that say when it is done: objects with title (required), given, when, then and kind (functional, negative, edge or non_functional).
What it returns
{ "data": { "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "number": 143, "reference": "CRM-143", "type": "story", "parent_id": null, "epic_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "title": "Tier downgrade warning", "description": null, "status": "backlog", "resolution": null, "priority": "high", "assignee_id": null, "assignee_name": null, "reporter_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "reporter_name": "Nimal Fernando", "reviewer_id": null, "qa_owner_id": null, "story_points": null, "estimate_minutes": null, "remaining_minutes": null, "due_on": null, "started_at": null, "completed_at": null, "persona_id": null, "as_a": "platinum member", "i_want": "to be warned before I drop a tier", "so_that": "I can keep my perks", "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": [], "acceptance_criteria": [ { "id": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c03", "work_item_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "position": 0, "title": "A member within reach of the threshold is warned thirty days ahead", "given": null, "when": null, "then": null, "kind": "functional", "verified_at": null, "verified_by": null }, { "id": "b8c9d0e1-f2a3-4b4c-8d5e-6f7a8b9c0d14", "work_item_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "position": 1, "title": "A member already below the threshold gets no warning", "given": null, "when": null, "then": null, "kind": "negative", "verified_at": null, "verified_by": null } ], "position": 4, "version": 0, "approved_at": null, "created_at": "2026-11-03T10:00:00+00:00", "updated_at": "2026-11-03T10:00:00+00:00" }}How it fails
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope or the person's visibility.
VALIDATION_FAILEDthe title is missing or too long, a sentence part or a criterion is too long, a criterion lacks its sentence, priority or a criterion kind is not one of its values, or the epic is not an epic of the project.
TOKEN_MISSING_ABILITYtoken lacks work-item:create.
FORBIDDENthe token holder's role on the project does not carry work-item:create.
How is this guide?
Last updated on