Acceptance Criteria
The acceptance criteria rows on a work item: one sentence each with an optional Given, When and Then and a kind, written in the item's editor, ordered, versioned with the item and replaced over the API.
By the end of this page you will have written the acceptance criteria of a story as rows a tester can tick, know what each row carries and what reads it, and know how the rows are ordered, replaced and kept with every version of the item.
An acceptance criterion is one sentence that says when a story is done: a member who crosses the platinum threshold gets the email within the hour. A story carries as many as it needs, each with an optional Given, When and Then for the ones worth spelling out as a scenario, and a kind that says what the row checks: the happy path, what must be refused, the edge of the input or a quality the story must keep. The rows are structured, not free text, so QA can tick them one by one from a passing run, test cases can be drafted one per row, and the traceability matrix can say which criterion a test covers.
Before you begin
| You want to | You need |
|---|---|
| Read the criteria | work-item:view-any on the project. A client guest reads the agreed items' criteria. |
| Write or change the criteria | work-item:update, or work-item:create while adding the item. |
| Replace them through the API | work-item:update on a token. |
The rows live on the item: open the project, choose Backlog in the sidebar and open the item's editor. Every kind of item may carry criteria; a story almost always should.
Write the criteria
- Open the item in the editor (New Item, or Edit Item on an existing one) and scroll to Acceptance Criteria.
- Press Add Criterion. A row appears with its kind, its sentence and the three scenario fields.
- Type the sentence: one line a tester can tick, in the persona's terms, with the outcome in it.
- Pick the kind when it is not the happy path: negative for what must be refused, edge case for the boundary of the input, non-functional for a quality the story must keep.
- Fill Given, When and Then when the scenario is worth spelling out: the starting state, what happens and what must be true after. Leave them empty when the sentence is enough.
- Add the next row, and press Create Item or Save Changes when the list is complete.
The rows are saved with the item in one version. A row with nothing in its sentence is refused; a sentence needs at least three characters and at most 300, each scenario field at most 500, and an item carries at most fifty rows.
Write the negative and the edge
A story with only happy-path criteria is half a story. Heimdall's quality review will flag a story without a negative criterion, and the test generator drafts one case per kind, so a row of each kind gives QA the suite it needs.
Order and remove rows
Each row carries three buttons: Move up and Move down change its place in the list, and Remove criterion drops it. The order is the order QA ticks them in and the order the test generator drafts them in, so put the main path first. Removing a row takes effect when you save; the version before the save still carries it, so a row removed by mistake comes back with Restore this version.
Read the criteria
The item's detail flyout lists the rows under Acceptance Criteria in order, each with its kind badge, its sentence and its scenario on one line beneath. An item without rows reads No criteria yet. A client guest reads the rows of the agreed items like everyone else; they are what the client signs off.
Replace the criteria over the API
Beside the editor, a token replaces an item's criteria in one call: PUT /v1/work-items/{item}/acceptance-criteria takes the full list in order, keeps and changes the rows
sent with an id, adds the rows without one, removes every row left out, and answers the item with
its rows. The call writes a version of the item and work_item.criteria_changed goes out with how
many rows were added, changed and removed; a call that changes nothing stays quiet. The same rows
can be sent inside POST …/work-items and PATCH /v1/work-items/{item} under
acceptance_criteria, which saves them with the item's fields in one version.
All the fields
What happens next
- The rows travel inside every version of the item, so a restore brings the criteria of that version back with the fields.
- A save of the item that changes the rows writes a version whose diff lists
acceptance_criteria; a replace through the API also raiseswork_item.criteria_changed. - Test cases will be drafted one per row, QA will tick each row from an execution, and the traceability matrix will show which test covers which criterion, as the test module lands.
Heimdall on this page
Heimdall reads an item's criteria through the tools the MCP server offers and writes them into the stories it drafts.
Turning a sentence into a Given, When and Then, and suggesting the rows a story lacks, arrive with the inline assists.
From the API and MCP
Work Items API
Replace an item's criteria in one call, or send them with the item's fields; read them back on the item and in its versions.
create_story_draft
The MCP tool that drafts a story with its criteria rows.
get_work_item
The MCP tool that reads an item with its criteria in order.
Permissions
| Action | Permission |
|---|---|
| Read the criteria | work-item:view-any, work-item:view |
| Write them with the item | work-item:create on a new item, work-item:update after |
| Replace them through their own verb | work-item:update |
Frequently asked
Related
- Backlog — the items the criteria belong to
- Revisions and versions — the criteria inside every version
- Status reference — the four kinds
work_item.*webhook events
How is this guide?
Last updated on
Labels
A project's own words pinned on its work items: pick labels on an item, filter the backlog by one, and shape the vocabulary from the backlog's label manager with a colour and a meaning for each word.
Functional Requirements
The Requirements page of a project: what the system shall do, each requirement with its reference, statement, rationale, source, priority, verification method, status and owner, its review lifecycle and its versions.