Epic Tools

Four tools for managing epics: create, update, get (with progress data), and delete.

Permission Model

• Getting epics: requires Epics: Read permission
• Creating epics: requires Epics: Create permission
• Updating epics: requires Epics: Update permission (Own/All scope)
• Deleting epics: requires Epics: Delete permission (Own/All scope)
• Project owners and admins bypass all permission checks

Enums

Colors

Value	Color
0	Grey
1	Green
2	Blue
3	Red
4	Purple
5	Yellow

Status

Epic status is derived from issue lane positions — it isn't stored on the epic. An epic with no issues, or any issue not in the project's last lane, is Open. An epic with at least one issue and every issue in the last lane is Closed. The last lane is the highest order, tie-broken by highest id.

Value	Status
0	Open
1	Closed

create-epic

Create a new epic to group and order issues on the timeline.

Parameters

Parameter	Type	Required	Description
project_id	integer	Yes	The project to create the epic in
title	string	Yes	Epic title (max 255 characters)
color	integer	Yes	Color code (0–5, see table above)
description	string	No	Epic description (max 10,000 characters). An empty or whitespace-only value is stored as null.
start	date	No	Start date (ISO 8601). Required if end is provided.
end	date	No	End date (ISO 8601). Must be after start. Required if start is provided.
order	integer	No	Display order (default 0, minimum 0)
issue_ids	array	No	Issue IDs to attach (must belong to the same project, at most 500). Omit or send null for an epic with no issues.

Behavior

• Status is derived from issue lanes; new epics start with no issues, so they're Open (status 0, status_name Open)
• Start and end dates must be provided together — you can't set one without the other
• Every issue ID must be an issue of the specified project (at most 500); otherwise the create is rejected and nothing is stored
• Response includes created_at and updated_at (ISO 8601)
• Requires the appropriate Epics permission for this action

Example Prompt

Create a red epic called "Q1 Auth Overhaul" in the kendo project for the month of April. Attach the three auth-related issues we created earlier.

update-epic

Update an existing epic's details, dates, or issue assignments.

Parameters

Parameter	Type	Required	Description
epic_id	integer	Yes	The epic to update
title	string	No	New title (max 255 characters)
description	string	No	New description (max 10,000 characters), or null to clear. An empty or whitespace-only value clears it too.
color	integer	No	Color code (0–5)
start	date	No	New start date, or null to clear. Send together with end — both dates, or both null to clear the window.
end	date	No	New end date, or null to clear. Must be after start. Send together with start.
order	integer	No	New display order (minimum 0)
issue_ids	array	No	Complete list of issue IDs to attach (at most 500). Omit or send null to keep current assignments. Pass [] to detach all.

Behavior

• Only provided fields are updated
• Omitting issue_ids, or sending null, preserves current issue assignments; passing [] detaches all issues
• Every issue ID must exist in the epic's project (at most 500); otherwise the update is rejected
• Status is not directly editable — it's derived from the lanes of the epic's issues
• The response includes the derived status (0/1) and status_name (Open/Closed)
• Response includes created_at and updated_at (ISO 8601)
• Requires the appropriate Epics permission for this action

Example Prompt

Push the "Auth Overhaul" deadline to mid-May and attach the new MFA issue

get-epics

Get epics for a project with full issue details and progress data. Read-only and safe to call repeatedly.

Parameters

Parameter	Type	Required	Description
project_id	integer	Yes	The project to get epics for
epic_id	integer	No	Get a single epic by ID
status	integer	No	Filter by derived status (0 Open, 1 Closed)

Behavior

• Returns epics with full issue details (key, title, lane, assignee)
• Each epic includes derived status (0/1) and status_name (Open/Closed) — see Status above
• Includes progress data: completed issues (those in the project's last lane) vs total
• Each epic includes attachments_count — the number of files attached to the epic
• Each epic includes created_at and updated_at (ISO 8601)
• Results ordered by display order
• Marked as #[IsReadOnly] and #[IsIdempotent]

Example Prompt

Show me the open epics in the kendo project and their progress.

delete-epic

Permanently delete an epic.

Destructive

This action cannot be undone. The epic is permanently removed. Issues linked to the epic are NOT deleted — only the epic association is removed.

Parameters

Parameter	Type	Required	Description
epic_id	integer	Yes	The epic to delete

Behavior

• Issues linked to the epic are preserved — only the epic grouping is removed
• Requires Epics: Delete permission

Example Prompt

Delete the "Auth Overhaul" epic, we're restructuring the roadmap

See Also

• Resources — Read epic data via kendo://projects/{id}/epics
• Projects Guide — Understanding epics and timeline planning
• Epics API — REST endpoints for epic management