DESTRUCTIVE

update_requirement

Changes a requirement in part and moves it where the lifecycle allows by hand; the kind is fixed and the review states stay with the approvers.

Change a requirement by requirement_id with any of title, category (a non-functional requirement's quality), statement and rationale (HTML), source_stakeholder_id, source (where it came from, in words), priority, measure, verification_method (test, inspection, analysis or demonstration), owner_id and status. The kind, functional or non-functional, never changes: it picked the sequence the requirement was numbered from. A field left out keeps its value; a field sent as null is cleared. The fields go through the same action the Requirements page runs and write a version; requirement.updated goes out. A status goes through its own move: deprecated, baselined or back to draft are moves a person may make by hand, and requirement.status_changed goes out. in_review and approved are reached through submit_for_review and the approvers, and any move is refused while an approval request is open. A staff token with requirement:update on the project is needed.

Requires ability

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

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

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

requirement_id*string

UUID of the requirement.

titlestringoptional

What the requirement is called, 3 to 200 characters.

categorystringoptional

The quality a non-functional requirement is about.

performancescalabilityavailabilityreliabilitysecurityprivacyusabilityaccessibilitycompatibilitymaintainabilityportabilitycomplianceobservabilitylocalisationother
statementstringoptional

What the system shall do or keep, as HTML.

rationalestringoptional

Why, as HTML.

source_stakeholder_idstringoptional

UUID of the stakeholder it came from.

sourcestringoptional

Where it came from, in words.

prioritystringoptional

Its MoSCoW priority.

mustshouldcouldwont
measurestringoptional

The metric and target that say when a non-functional requirement is met.

verification_methodstringoptional

How it will be shown to be met.

testinspectionanalysisdemonstration
owner_idstringoptional

UUID of the person who answers for it.

statusstringoptional

A move the lifecycle allows by hand; the review states go through submit_for_review.

draftin_reviewapprovedbaselineddeprecated

What it returns

{  "data": {    "id": "a8b9c0d1-e2f3-4a4b-9c5d-6e7f8a9b0c13",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "type": "functional",    "number": 12,    "reference": "SCL-FR-12",    "category": null,    "title": "Orders can be paid online",    "statement": "<p>The system shall take a card payment at order placement.</p>",    "rationale": "<p>The counter stops chasing payment on collection.</p>",    "source_stakeholder_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",    "source_stakeholder_name": "Nadeesha Perera",    "source": "Kick-off call",    "priority": "must",    "measure": null,    "verification_method": "test",    "status": "draft",    "owner_id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",    "owner_name": "Bea Analyst",    "position": 12,    "version": 2,    "approved_at": null,    "approved_revision_id": null,    "created_at": "2026-10-28T10:30:00+00:00",    "updated_at": "2026-10-28T11:45:00+00:00"  }}

How it fails

VALIDATION_FAILED

a field outside its limits, a category, priority or verification_method outside its set, a status of in_review or approved (the message says to submit the requirement for review), a move the lifecycle does not allow, a move while a request is open, or a stakeholder or owner that is not the project's or the team's.

RESOURCE_NOT_FOUND

unknown requirement_id, or a requirement 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 requirement:update.

TOKEN_MISSING_ABILITY

token lacks requirement:update.

How is this guide?

Last updated on