Shortcut Software Epics API

openapi: 3.2.0
info:
  title: Shortcut Categories Epics API
  version: '3.0'
  description: Shortcut API
servers:
- url: https://api.app.shortcut.com
security:
- api_token: []
tags:
- name: Epics
paths:
  /api/v3/epics:
    get:
      parameters:
      - in: query
        name: includes_description
        description: A true/false boolean indicating whether to return Epics with their descriptions.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EpicSlim'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listEpics
      description: List Epics returns a list of all Epics and their attributes.
      summary: List Epics
      tags:
      - Epics
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEpic'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Epic'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createEpic
      description: Create Epic allows you to create a new Epic in Shortcut.
      summary: Create Epic
      tags:
      - Epics
  /api/v3/epics/paginated:
    get:
      parameters:
      - in: query
        name: includes_description
        description: A true/false boolean indicating whether to return Epics with their descriptions.
        required: false
        schema:
          type: boolean
      - in: query
        name: page
        description: The page number to return, starting with 1. Defaults to 1.
        required: false
        schema:
          type: integer
          format: int64
      - in: query
        name: page_size
        description: The number of Epics to return per page. Minimum 1, maximum 250, default 10.
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpicPaginatedResults'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listEpicsPaginated
      description: List Epics with pagination returns a paginated list of Epics and their attributes.
      summary: List Epics Paginated
      tags:
      - Epics
  /api/v3/epics/{epic-public-id}:
    get:
      parameters:
      - in: path
        name: epic-public-id
        description: The unique ID of the Epic.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Epic'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: getEpic
      description: Get Epic returns information about the selected Epic.
      summary: Get Epic
      tags:
      - Epics
    put:
      parameters:
      - in: path
        name: epic-public-id
        description: The unique ID of the Epic.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEpic'
        required: true
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Epic'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: updateEpic
      description: Update Epic can be used to update numerous fields in the Epic. The only required parameter is Epic ID, which can be found in the Shortcut UI.
      summary: Update Epic
      tags:
      - Epics
    delete:
      parameters:
      - in: path
        name: epic-public-id
        description: The unique ID of the Epic.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: No Content
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: deleteEpic
      description: Delete Epic can be used to delete the Epic. The only required parameter is Epic ID.
      summary: Delete Epic
      tags:
      - Epics
  /api/v3/epics/{epic-public-id}/comments:
    get:
      parameters:
      - in: path
        name: epic-public-id
        description: The unique ID of the Epic.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ThreadedComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listEpicComments
      description: Get a list of all Comments on an Epic.
      summary: List Epic Comments
      tags:
      - Epics
    post:
      parameters:
      - in: path
        name: epic-public-id
        description: The ID of the associated Epic.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEpicComment'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadedComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createEpicComment
      description: This endpoint allows you to create a threaded Comment on an Epic.
      summary: Create Epic Comment
      tags:
      - Epics
  /api/v3/epics/{epic-public-id}/comments/{comment-public-id}:
    post:
      parameters:
      - in: path
        name: epic-public-id
        description: The ID of the associated Epic.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the parent Epic Comment.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCommentComment'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadedComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createEpicCommentComment
      description: This endpoint allows you to create a nested Comment reply to an existing Epic Comment.
      summary: Create Epic Comment Comment
      tags:
      - Epics
    get:
      parameters:
      - in: path
        name: epic-public-id
        description: The ID of the associated Epic.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the Comment.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadedComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: getEpicComment
      description: This endpoint returns information about the selected Epic Comment.
      summary: Get Epic Comment
      tags:
      - Epics
    put:
      parameters:
      - in: path
        name: epic-public-id
        description: The ID of the associated Epic.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the Comment.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateComment'
        required: true
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadedComment'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: updateEpicComment
      description: This endpoint allows you to update a threaded Comment on an Epic.
      summary: Update Epic Comment
      tags:
      - Epics
    delete:
      parameters:
      - in: path
        name: epic-public-id
        description: The ID of the associated Epic.
        required: true
        schema:
          type: integer
          format: int64
      - in: path
        name: comment-public-id
        description: The ID of the Comment.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: No Content
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: deleteEpicComment
      description: This endpoint allows you to delete a Comment from an Epic.
      summary: Delete Epic Comment
      tags:
      - Epics
  /api/v3/epics/{epic-public-id}/documents:
    get:
      parameters:
      - in: path
        name: epic-public-id
        description: The unique ID of the Epic.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocSlim'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listEpicDocuments
      description: Get a list of all Documents related to this Epic.
      summary: List Epic Documents
      tags:
      - Epics
  /api/v3/epics/{epic-public-id}/health:
    get:
      parameters:
      - in: path
        name: epic-public-id
        description: The unique ID of the Epic.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: getEpicHealth
      description: Get the current health for the specified Epic.
      summary: Get Epic Health
      tags:
      - Epics
    post:
      parameters:
      - in: path
        name: epic-public-id
        description: The unique ID of the Epic.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEpicHealth'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createEpicHealth
      description: Create a new health status for the specified Epic.
      summary: Create Epic Health
      tags:
      - Epics
  /api/v3/epics/{epic-public-id}/health-history:
    get:
      parameters:
      - in: path
        name: epic-public-id
        description: The unique ID of the Epic.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Health'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listEpicHealths
      description: List the history of health statuses for the specified Epic, most recent first.
      summary: List Epic Healths
      tags:
      - Epics
  /api/v3/epics/{epic-public-id}/stories:
    get:
      parameters:
      - in: path
        name: epic-public-id
        description: The unique ID of the Epic.
        required: true
        schema:
          type: integer
          format: int64
      - in: query
        name: includes_description
        description: A true/false boolean indicating whether to return Stories with their descriptions.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StorySlim'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listEpicStories
      description: Get a list of all Stories in an Epic.
      summary: List Epic Stories
      tags:
      - Epics
components:
  schemas:
    EpicSlim:
      description: EpicSlim represents the same resource as an Epic but is more light-weight, including all Epic fields except the comments array. The description string can be optionally included. Use the [Get Epic](#Get-Epic) endpoint to fetch the unabridged payload for an Epic.
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Epic.
          type: string
        description:
          description: The Epic's description.
          type: string
        archived:
          description: True/false boolean that indicates whether the Epic is archived or not.
          type: boolean
        started:
          description: A true/false boolean indicating if the Epic has been started.
          type: boolean
        entity_type:
          description: A string description of this resource.
          type: string
        labels:
          description: An array of Labels attached to the Epic.
          type: array
          items:
            $ref: '#/components/schemas/LabelSlim'
        mention_ids:
          description: '`Deprecated:` use `member_mention_ids`.'
          type: array
          items:
            type: string
            format: uuid
        member_mention_ids:
          description: An array of Member IDs that have been mentioned in the Epic description.
          type: array
          items:
            type: string
            format: uuid
        associated_groups:
          description: An array containing Group IDs and Group-owned story counts for the Epic's associated groups.
          type: array
          items:
            $ref: '#/components/schemas/EpicAssociatedGroup'
        project_ids:
          description: The IDs of Projects related to this Epic.
          type: array
          items:
            type: integer
            format: int64
        stories_without_projects:
          description: The number of stories in this epic which are not associated with a project.
          type: integer
          format: int64
        completed_at_override:
          description: A manual override for the time/date the Epic was completed.
          type:
          - string
          - 'null'
          format: date-time
        productboard_plugin_id:
          description: The ID of the associated productboard integration.
          type:
          - string
          - 'null'
          format: uuid
        started_at:
          description: The time/date the Epic was started.
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          description: The time/date the Epic was completed.
          type:
          - string
          - 'null'
          format: date-time
        objective_ids:
          description: An array of IDs for Objectives to which this epic is related.
          type: array
          items:
            type: integer
            format: int64
        name:
          description: The name of the Epic.
          type: string
        global_id:
          x-doc-skip: true
          type: string
        completed:
          description: A true/false boolean indicating if the Epic has been completed.
          type: boolean
        productboard_url:
          description: The URL of the associated productboard feature.
          type:
          - string
          - 'null'
        planned_start_date:
          description: The Epic's planned start date.
          type:
          - string
          - 'null'
          format: date-time
        state:
          description: '`Deprecated` The workflow state that the Epic is in.'
          type: string
        milestone_id:
          description: '`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`.'
          type:
          - integer
          - 'null'
          format: int64
        requested_by_id:
          description: The ID of the Member that requested the epic.
          type: string
          format: uuid
        epic_state_id:
          description: The ID of the Epic State.
          type: integer
          format: int64
        label_ids:
          description: An array of Label ids attached to the Epic.
          type: array
          items:
            type: integer
            format: int64
        started_at_override:
          description: A manual override for the time/date the Epic was started.
          type:
          - string
          - 'null'
          format: date-time
        group_id:
          description: '`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.'
          type:
          - string
          - 'null'
          format: uuid
        updated_at:
          description: The time/date the Epic was updated.
          type:
          - string
          - 'null'
          format: date-time
        group_mention_ids:
          description: An array of Group IDs that have been mentioned in the Epic description.
          type: array
          items:
            type: string
            format: uuid
        productboard_id:
          description: The ID of the associated productboard feature.
          type:
          - string
          - 'null'
          format: uuid
        follower_ids:
          description: An array of UUIDs for any Members you want to add as Followers on this Epic.
          type: array
          items:
            type: string
            format: uuid
        group_ids:
          description: An array of UUIDS for Groups to which this Epic is related.
          type: array
          items:
            type: string
            format: uuid
        owner_ids:
          description: An array of UUIDs for any members you want to add as Owners on this new Epic.
          type: array
          items:
            type: string
            format: uuid
        external_id:
          description: This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
          type:
          - string
          - 'null'
        id:
          description: The unique ID of the Epic.
          type: integer
          format: int64
        position:
          description: The Epic's relative position in the Epic workflow state.
          type: integer
          format: int64
        productboard_name:
          description: The name of the associated productboard feature.
          type:
          - string
          - 'null'
        deadline:
          description: The Epic's deadline.
          type:
          - string
          - 'null'
          format: date-time
        stats:
          $ref: '#/components/schemas/EpicStats'
        created_at:
          description: The time/date the Epic was created.
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: false
      required:
      - app_url
      - archived
      - started
      - entity_type
      - labels
      - mention_ids
      - member_mention_ids
      - associated_groups
      - project_ids
      - stories_without_projects
      - completed_at_override
      - productboard_plugin_id
      - started_at
      - completed_at
      - objective_ids
      - name
      - global_id
      - completed
      - productboard_url
      - planned_start_date
      - state
      - milestone_id
      - requested_by_id
      - epic_state_id
      - label_ids
      - started_at_override
      - group_id
      - updated_at
      - group_mention_ids
      - productboard_id
      - follower_ids
      - group_ids
      - owner_ids
      - external_id
      - id
      - position
      - productboard_name
      - deadline
      - stats
      - created_at
    LabelSlim:
      description: A Label can be used to associate and filter Stories and Epics, and also create new Workspaces. A slim Label does not include aggregate stats. Fetch the Label using the labels endpoint to retrieve them.
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Label.
          type: string
        description:
          description: The description of the Label.
          type:
          - string
          - 'null'
        archived:
          description: A true/false boolean indicating if the Label has been archived.
          type: boolean
        entity_type:
          description: A string description of this resource.
          type: string
        color:
          description: The hex color to be displayed with the Label (for example, "#ff0000").
          pattern: ^#[a-fA-F0-9]{6}$
          format: css-color
          minLength: 1
          type:
          - string
          - 'null'
        name:
          description: The name of the Label.
          type: string
        global_id:
          x-doc-skip: true
          type: string
        updated_at:
          description: The time/date that the Label was updated.
          type:
          - string
          - 'null'
          format: date-time
        external_id:
          description: This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here.
          type:
          - string
          - 'null'
        id:
          description: The unique ID of the Label.
          type: integer
          format: int64
        created_at:
          description: The time/date that the Label was created.
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: false
      required:
      - app_url
      - description
      - archived
      - entity_type
      - color
      - name
      - global_id
      - updated_at
      - external_id
      - id
      - created_at
    StorySlim:
      description: StorySlim represents the same resource as a Story, but is more light-weight. For certain fields it provides ids rather than full resources (e.g., `comment_ids` and `file_ids`) and it also excludes certain aggregate values (e.g., `cycle_time`). The `description` field can be optionally included. Use the [Get Story](#Get-Story) endpoint to fetch the unabridged payload for a Story.
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Story.
          type: string
        description:
          description: The description of the Story.
          type: string
        archived:
          description: True if the story has been archived or not.
          type: boolean
        started:
          description: A true/false boolean indicating if the Story has been started.
          type: boolean
        story_links:
          description: An array of story links attached to the Story.
          type: array
          items:
            $ref: '#/components/schemas/TypedStoryLink'
        entity_type:
          description: A string description of this resource.
          type: string
        labels:
          description: An array of labels attached to the story.
          type: array
          items:
            $ref: '#/components/schemas/LabelSlim'
        task_ids:
          description: An array of IDs of Tasks attached to the story.
          type: array
          items:
            type: integer
            format: int64
        mention_ids:
          description: '`Deprecated:` use `member_mention_ids`.'
          type: array
          items:
            type: string
            format: uuid
        synced_item:
          $ref: '#/components/schemas/SyncedItem'
        member_mention_ids:
          description: An array of Member IDs that have been mentioned in the Story description.
          type: array
          items:
            type: string
            format: uuid
        story_type:
          description: The type of story (feature, bug, chore).
          type: string
        custom_fields:
          description: An array of CustomField value assertions for the story.
          type: array
          items:
            $ref: '#/components/schemas/StoryCustomField'
        file_ids:
          description: An array of IDs of Files attached to the story.
          type: array
          items:
            type: integer
            format: int64
        num_tasks_completed:
          description: The number of tasks on the story which are complete.
          type: integer
          format: int64
        workflow_id:
          description: The ID of the workflow the story belongs to.
          type: integer
          format: int64
        completed_at_override:
          description: A manual override for the time/date the Story was completed.
          type:
          - string
          - 'null'
          format: date-time
        started_at:
          description: The time/date the Story was started.
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          description: The time/date the Story was completed.
          type:
          - string
          - 'null'
          format: date-time
        name:
          description: The name of the story.
          type: string
        global_id:
          x-doc-skip: true
          type: string
        completed:
          description: A true/false boolean indicating if the Story has been completed.
          type: boolean
        blocker:
          description: A true/false boolean indicating if the Story is currently a blocker of another story.
          type: boolean
        epic_id:
          description: The ID of the epic the story belongs to.
          type:
          - integer
          - 'null'
          format: int64
        story_template_id:
          description: The ID of the story template used to create this story, or null if not created using a template.
          type:
          - string
          - 'null'
          format: uuid
        external_links:
          description: An array of external links (strings) associated with a Story
          type: array
          items:
            type: string
        previous_iteration_ids:
          description: The IDs of the iteration the story belongs to.
          type: array
          items:
            type: integer
            format: int64
        requested_by_id:
          description: The ID of the Member that requested the story.
          type: string
          format: uuid
        iteration_id:
          description: The ID of the iteration the story belongs to.
          type:
          - integer
          - 'null'
          format: int64
        sub_task_story_ids:
          description: 'The Story IDs of Sub-tasks attached to the Story

            Field only applicable when Sub-task feature is enabled.'
          type: array
          items:
            type: integer
            format: int64
        formatted_vcs_branch_name:
          description: The formatted branch name for this story.
          x-doc-skip: true
          type:
          - string
          - 'null'
        label_ids:
          description: An array of label ids attached to the story.
          type: array
          items:
            type: integer
            format: int64
        started_at_override:
          description: A manual override for the time/date the Story was started.
          type:
          - string
          - 'null'
          format: date-time
        group_id:
          description: The ID of the group associated with the story.
          type:
          - string
          - 'null'
          format: uuid
        workflow_state_id:
          description: The ID of the workflow state the story is currently in.
          type: integer
          format: int64
        updated_at:
          description: The time/date the Story was updated.
          type:
          - string
          - 'null'
          format: date-time
        group_mention_ids:
          description: An array of Group IDs that have been mentioned in the Story description.
          type: array
          items:
            type: string
            format: uuid
        follower_ids:
          description: An array of UUIDs for any Members listed as Followers.
          type: array
          items:
            type: string
            format: uuid
        owner_ids:
          description: An array of UUIDs of the owners of this story.
          type: array
          items:
            type: string
            format: uuid
        external_id:
          description: This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
          type:
          - string
          - 'null'
        id:
          description: The unique ID of the Story.
          type: integer
          format: int64
        lead_time:
          description: The lead time (in seconds) of this story when complete.
          type: integer
          format: int64
        parent_story_id:
          description: 'The ID of the parent story to this story (making this story a sub-task).

            Field only applicable when Sub-task feature is enable

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shortcut-software/refs/heads/main/openapi/shortcut-software-epics-api-openapi.yml