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

create_epic

Adds an epic to a project as a draft, so Heimdall can split a brief into bodies of work and hang the stories under them.

Add an epic: project_id and title are required; summary (HTML), goal (one sentence), business_value (HTML), hypothesis, success_metrics (HTML), owner_id, priority (must, should, could or wont; should by default), starts_on, due_on and color fill in the rest. The epic takes the next number of the project's tracker sequence, starts as a draft, writes its first version and is announced as epic.created.

An epic reaches in review and approved through submit_for_review and the approvers, never by hand; the stories under it come from create_story_draft or create_work_item with the epic's id. A staff token with epic:create on the project is needed.

Requires ability

epic: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}/epics

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

Fires one event

epic.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 epic is called, 3 to 200 characters.

summarystringoptional

What the epic covers, as HTML.

goalstringoptional

One sentence on what it achieves.

business_valuestringoptional

Why the client wants it, as HTML.

hypothesisstringoptional

The bet it makes, if any.

success_metricsstringoptional

How the team will know it worked, as HTML.

owner_idstringoptional

UUID of the person who answers for it.

prioritystringoptional

Its MoSCoW priority; should by default.

mustshouldcouldwont
starts_onstringoptional

When work on it starts, YYYY-MM-DD.

due_onstringoptional

When it is due, YYYY-MM-DD.

colorstringoptional

The badge colour the board and the roadmap paint it in.

zincredorangeamberyellowlimegreenemeraldtealcyanskyblueindigovioletpurplefuchsiapinkrose

What 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>A customer picks services and items and chooses pickup or drop-off.</p>",    "goal": "A customer books a wash in under two minutes.",    "business_value": null,    "hypothesis": null,    "success_metrics": null,    "owner_id": null,    "owner_name": null,    "priority": "must",    "status": "draft",    "starts_on": null,    "due_on": null,    "color": null,    "position": 1,    "version": 0,    "approved_at": null,    "approved_revision_id": null,    "created_at": "2026-10-28T09:55:00+00:00",    "updated_at": "2026-10-28T09:55:00+00:00"  }}

How it fails

VALIDATION_FAILED

title missing or outside 3 to 200 characters, a priority outside MoSCoW, a color outside the palette, a date that is not YYYY-MM-DD, or an owner_id who is not on the team.

RESOURCE_NOT_FOUND

unknown project_id, or a project 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 epic:create.

TOKEN_MISSING_ABILITY

token lacks epic:create.

Related

list_epicsthe epics of the project today.update_epicchange or move one later.create_work_itemthe stories under it.submit_for_reviewput it up for approval.Epics APIthe same door over REST.

How is this guide?

Last updated on