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

raise_change_request

Raises a change request on a project, numbered from the change requests' own sequence, with its reason, the baseline it changes, the stakeholder who asked, the records it touches and whatever impact is known; a guest token raises one without the impact.

Ask for a change to the agreed record. project_id and a title (3 to 200 characters) are required; description says what is asked for and why as HTML, reason is one of new_requirement, clarification, defect, regulatory, client_request, technical_debt or scope_reduction (default new requirement), priority runs from lowest to highest (default medium), baseline_id names the frozen baseline the change applies to and stakeholder_id the client's stakeholder who asked (both must be the project's), and affected names the records it touches as objects of type (epic, work-item, requirement, business-rule or use-case) and id, each becoming a link from the request. The impact fields (impact_scope, impact_schedule_days, impact_effort_hours, impact_cost, impact_risk, impact_level) may come now or later from the analyst or analyse_change_impact. The request is written as submitted with the token's holder as the person who raised it; a client guest's token raises it without the impact and with their own seat as the stakeholder when their account is linked to one. Submitting it to the approvers is a person's act, through submit_for_review on their word. Runs the same action as Raise Change Request in the application and emits change_request.created.

Requires ability

change-request:create

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

Runs the same action as

POST/v1/projects/{project}/change-requests

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

Fires one event

change_request.created

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

project_id*string

UUID of the project.

title*string

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, when the client did.

affectedarrayoptional

The records it touches: objects with type (epic, work-item, requirement, business-rule or use-case) 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

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 subscriptions too",    "description": "<p>The client wants the voucher applied to the first renewal as well.</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"      }    ],    "impact_scope": null,    "impact_schedule_days": null,    "impact_effort_hours": null,    "impact_cost": null,    "impact_risk": null,    "impact_level": null,    "ai_impact_draft": null,    "analysed_at": null,    "priority": "high",    "status": "submitted",    "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-29T09:20:00+00:00"  }}

How it fails

VALIDATION_FAILED

the title is missing, shorter than 3 or longer than 200 characters; an unknown reason, priority or impact_level; a schedule impact outside -3650..3650 days or a negative effort or cost; a baseline_id or stakeholder_id that is not the project's; a record under affected whose type cannot be touched; more than 200 records.

RESOURCE_NOT_FOUND

unknown project_id, or a record under affected that is hidden, gone or another project's; nothing is written.

FORBIDDEN

the holder's role on the project does not carry change-request:create.

TOKEN_MISSING_ABILITY

token lacks change-request:create.

Related

analyse_change_impactHeimdall's reading of the request's impact.update_change_requestchange the words, the records or the impact, or move it by hand.submit_for_reviewput it to the approvers, on the person's word.get_baselinethe records a baseline holds, to name the right ones.Change Requests APIthe same write over REST.

How is this guide?

Last updated on