update_epic
Changes an epic in part and moves it where the lifecycle allows by hand; the review states stay with the approvers.
Change an epic by epic_id with any of title, summary, goal, business_value, hypothesis, success_metrics, owner_id, priority, starts_on, due_on, color and status. A field left out keeps its value; a field sent as null is cleared. The fields go through the same action the Epics page runs and write a version; epic.updated goes out. A status goes through the epic's own move: in_progress, done, cancelled or back to draft are moves a person may make by hand, and epic.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 epic: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.
Runs the same actions as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires events
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
epic_id*stringUUID of the epic.
titlestringoptionalWhat the epic is called, 3 to 200 characters.
summarystringoptionalWhat the epic covers, as HTML.
goalstringoptionalOne sentence on what it achieves.
business_valuestringoptionalWhy the client wants it, as HTML.
hypothesisstringoptionalThe bet it makes, if any.
success_metricsstringoptionalHow the team will know it worked, as HTML.
owner_idstringoptionalUUID of the person who answers for it.
prioritystringoptionalIts MoSCoW priority; should by default.
mustshouldcouldwontstarts_onstringoptionalWhen work on it starts, YYYY-MM-DD.
due_onstringoptionalWhen it is due, YYYY-MM-DD.
colorstringoptionalThe badge colour the board and the roadmap paint it in.
zincredorangeamberyellowlimegreenemeraldtealcyanskyblueindigovioletpurplefuchsiapinkrosestatusstringoptionalA move the lifecycle allows by hand; the review states go through submit_for_review.
draftin_reviewapprovedin_progressdonecancelledWhat it returns
{ "data": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "number": 1, "reference": "SCL-1", "title": "Order placement", "summary": "<p>Services, items, pickup or drop-off, and the payment step.</p>", "goal": "A customer books a wash in under two minutes.", "business_value": "<p>Every order placed online is one the counter does not type in.</p>", "hypothesis": null, "success_metrics": "<p>Seventy percent of orders placed online by month three.</p>", "owner_id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "owner_name": "Bea Analyst", "priority": "must", "status": "in_progress", "starts_on": "2026-11-02", "due_on": "2026-12-19", "color": "emerald", "position": 1, "version": 3, "approved_at": "2026-10-30T10:00:00+00:00", "approved_revision_id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a4b", "created_at": "2026-10-28T09:55:00+00:00", "updated_at": "2026-11-02T08:00:00+00:00" }}How it fails
VALIDATION_FAILEDa field outside its limits, a status of in_review or approved (the message says to submit the epic for review), a move the lifecycle does not allow from where the epic stands, a move while a request is open, or an owner_id who is not on the team.
RESOURCE_NOT_FOUNDunknown epic_id, or an epic 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 epic:update.
TOKEN_MISSING_ABILITYtoken lacks epic:update.
How is this guide?
Last updated on