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

update_change_request

Changes a change request's words, records touched or impact while it is not yet decided, or moves it by hand along its lifecycle; the moves through the approval gate are refused.

Change a request until the approvers decide it, and move it along afterwards. Send any of the fields raise_change_request takes; affected replaces the records touched wholesale. A request is edited while submitted, under_analysis or awaiting_approval; an approved or rejected one no longer changes. status makes a move by hand: under_analysis (needs change-request:analyse on the project), closed, and after the approval implementing, implemented, verified (needs change-request:verify, and stamps who verified and when) and closed. The moves into and out of the gate (awaiting_approval, approved, rejected) are the approval engine's and are refused; use submit_for_review on the person's word. Runs the same actions as the application's editor and Move to menu: change_request.updated with what changed, the records touched included, change_request.status_changed for a move, and a version per save.

Requires ability

change-request:update

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

Runs the same actions as

PATCH/v1/change-requests/{changeRequest}POST/v1/change-requests/{changeRequest}/statusPOST/v1/change-requests/{changeRequest}/verify

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

Fires events

change_request.updatedchange_request.status_changed

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

change_request_id*string

UUID of the change request.

titlestringoptional

What the change is called, 3 to 200 characters.

descriptionstringoptional

What is asked for and why, as HTML.

reasonstringoptional

Why it was raised.

new_requirementclarificationdefectregulatoryclient_requesttechnical_debtscope_reduction
baseline_idstringoptional

UUID of the baseline the change is raised against.

stakeholder_idstringoptional

UUID of the stakeholder who asked.

affectedarrayoptional

The records it touches, replacing the list: objects with type and id.

impact_scopestringoptional

What the change touches, as HTML.

impact_schedule_daysintegeroptional

Days the schedule moves; negative when it shortens.

impact_effort_hoursnumberoptional

Hours of effort.

impact_costnumberoptional

The cost, in the project's currency.

impact_riskstringoptional

What the change risks, as HTML.

impact_levelstringoptional

How hard it hits the project.

lowmediumhigh
prioritystringoptional

How urgent the change is.

lowestlowmediumhighhighest
statusstringoptional

A move by hand the lifecycle allows; the gate's states go through submit_for_review.

submittedunder_analysisawaiting_approvalapprovedrejectedimplementingimplementedverifiedclosed

What it returns

{  "data": {    "id": "c7d8e9f0-a1b2-4c3d-8e4f-5a6b7c8d9e0f",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "number": 2,    "reference": "CRM-CR-2",    "title": "Accept vouchers on every renewal",    "description": "<p>The client wants the voucher applied to every renewal.</p>",    "reason": "client_request",    "requested_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",    "requester_name": "Bea Analyst",    "stakeholder_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",    "stakeholder_name": "Gail of the Client",    "baseline_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",    "baseline_name": "v1.0 scope",    "affected": [      {        "artefact_type": "requirement",        "artefact_id": "a8b9c0d1-e2f3-4a4b-9c5d-6e7f8a9b0c13",        "reference": "CRM-FR-12",        "title": "Password reset by email"      },      {        "artefact_type": "business-rule",        "artefact_id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",        "reference": "CRM-BR-7",        "title": "One voucher per order"      }    ],    "impact_scope": "<p>CRM-FR-12 gains a renewal clause; CRM-BR-7 gains an exception for renewals.</p>",    "impact_schedule_days": 5,    "impact_effort_hours": "24.00",    "impact_cost": "1800.00",    "impact_risk": "<p>The renewal job runs unattended.</p>",    "impact_level": "high",    "ai_impact_draft": null,    "analysed_at": null,    "priority": "high",    "status": "under_analysis",    "decision_note": null,    "verified_by": null,    "verified_at": null,    "version": 0,    "approved_at": null,    "approved_revision_id": null,    "position": 1,    "created_at": "2026-10-29T09:20:00+00:00",    "updated_at": "2026-10-29T10:10:00+00:00"  }}

How it fails

VALIDATION_FAILED

a field change on a request already decided; a status the lifecycle does not allow from where the request stands, a status the approval engine owns, or any move while a request is under review; a title shorter than 3 or longer than 200 characters; an unknown reason, priority, impact_level or status; an impact number out of range; a baseline or stakeholder that is not the project's.

RESOURCE_NOT_FOUND

unknown change_request_id, a request outside the token's scope, or a record under affected that is hidden, gone or another project's.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry change-request:update (or change-request:analyse and change-request:verify for those moves).

TOKEN_MISSING_ABILITY

token lacks change-request:update.

Related

raise_change_requestraise a new request.analyse_change_impactfill the empty impact fields from Heimdall's reading.submit_for_reviewthe move into the gate, on the person's word.delete_change_requestremove a request that was never agreed.Change Requests APIthe same writes over REST, the verify move through its own endpoint.

How is this guide?

Last updated on