submit_for_review
Puts an epic, story, requirement, business rule, use case, baseline or change request up for approval under the record's own submit ability, or resubmits it as the next round when its open request waits for changes.
Submit a record for approval once it is ready. artefact_type names the family (epic, work-item for a story, requirement, business-rule, use-case, baseline or change-request) and artefact_id the record; summary tells the approvers what changed and why. The record moves into review where it has a review status, the approvers are resolved from the project's policy, each is notified, and approval.requested goes out; a project whose gate is off approves it at once. When the record's open request is waiting for changes, the same call resubmits it as the next round.
A baseline passes two gates through this one door: a composed draft goes to the project manager's Baseline approval, which freezes it and locks the records it holds, and a frozen scope baseline goes, on the next call, to the Client sign-off of the stakeholders flagged as approving requirements. A change request goes to the Change request gate with the stakeholder who asked for it added to the approvers; its approval unlocks the baseline items it names.
The tool needs the record's own ability: the update ability for a planning record (requirement:update for a requirement, and so on), baseline:freeze for a baseline, change-request:approve for a change request, and a staff token. Deciding is a person's act: there is no tool for it. Read the request afterwards with get_approval_request.
Runs the same actions 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.
Annotations
A client that honours annotations asks a person before running it.
Arguments
artefact_type*stringThe family of the record to submit.
epicwork-itemrequirementbusiness-ruleuse-casebaselinechange-requestgenerated-documentsprintartefact_id*stringUUID of the record to submit.
summarystringoptionalWhat changed and why, for the approvers; up to 2000 characters.
2000What it returns
{ "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "approvable_type": "requirement", "approvable_id": "a8b9c0d1-e2f3-4a4b-9c5d-6e7f8a9b0c13", "reference": "CRM-FR-12", "title": "Apply a voucher at checkout", "kind": "requirement_review", "status": "pending", "rule": "any", "quorum": 1, "round": 1, "approvers": [ { "user_id": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b", "name": "Pat Manager", "via": "role", "stakeholder_id": null } ], "tally": { "approved": 0, "needed": 1, "total": 1 }, "requires_comment": true, "requested_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "requester_name": "Bea Analyst", "summary": "First cut of the voucher rules.", "revision_id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a4b", "due_at": "2026-10-31T09:20:00+00:00", "remind_at": "2026-10-29T09:20:00+00:00", "auto_approve_at": null, "reminded_at": null, "escalated_at": null, "decided_at": null, "auto_approved": false, "decisions": [], "created_at": "2026-10-28T09:20:00+00:00", "updated_at": "2026-10-28T09:20:00+00:00" }}How it fails
VALIDATION_FAILEDunknown artefact_type; the record is already under review and not waiting for changes; it cannot be submitted as it stands (a task, a done story, an empty baseline, a signed baseline, an approved change request); the gate names nobody (a scope baseline with no stakeholder seat flagged and linked); summary is longer than 2000 characters.
RESOURCE_NOT_FOUNDunknown artefact_id, or a record outside the token's scope or the person's visibility.
FORBIDDENthe token is a client guest's, or the holder's role on the project does not carry the record's submit permission.
TOKEN_MISSING_ABILITYtoken lacks the record's submit ability.
How is this guide?
Last updated on