Shortcut Software Epics API

openapi: 3.0.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:
    CreateCommentComment:
      x-doc-skip: true
      type: object
      properties:
        text:
          maxLength: 100000
          description: The comment text.
          minLength: 1
          type: string
        author_id:
          description: The Member ID of the Comment's author. Defaults to the user identified by the API token.
          type: string
          format: uuid
        created_at:
          description: Defaults to the time/date the comment is created, but can be set to reflect another date.
          type: string
          format: date-time
        updated_at:
          description: Defaults to the time/date the comment is last updated, but can be set to reflect another date.
          type: string
          format: date-time
        external_id:
          maxLength: 128
          description: This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.
          type: string
      additionalProperties: false
      required:
      - text
    SyncedItem:
      x-doc-skip: true
      description: The synced item for the story.
      type: object
      properties:
        external_id:
          description: The id used to reference an external entity.
          type: string
        url:
          description: The url to the external entity.
          type: string
      additionalProperties: false
      required:
      - external_id
      - url
    Epic:
      description: An Epic is a collection of stories that together might make up a release, a objective, or some other large initiative that you are working on.
      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
          format: date-time
          nullable: true
        productboard_plugin_id:
          description: The ID of the associated productboard integration.
          type: string
          format: uuid
          nullable: true
        started_at:
          description: The time/date the Epic was started.
          type: string
          format: date-time
          nullable: true
        completed_at:
          description: The time/date the Epic was completed.
          type: string
          format: date-time
          nullable: true
        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
        comments:
          description: A nested array of threaded comments.
          type: array
          items:
            $ref: '#/components/schemas/ThreadedComment'
        productboard_url:
          description: The URL of the associated productboard feature.
          type: string
          nullable: true
        planned_start_date:
          description: The Epic's planned start date.
          type: string
          format: date-time
          nullable: true
        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
          format: int64
          nullable: true
        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
          format: date-time
          nullable: true
        group_id:
          description: '`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.'
          type: string
          format: uuid
          nullable: true
        updated_at:
          description: The time/date the Epic was updated.
          type: string
          format: date-time
          nullable: true
        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
          format: uuid
          nullable: true
        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
          nullable: true
        id:
          description: The unique ID of the Epic.
          type: integer
          format: int64
        health:
          $ref: '#/components/schemas/Health'
        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
          nullable: true
        deadline:
          description: The Epic's deadline.
          type: string
          format: date-time
          nullable: true
        stats:
          $ref: '#/components/schemas/EpicStats'
        created_at:
          description: The time/date the Epic was created.
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
      required:
      - app_url
      - description
      - 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
      - comments
      - 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
    StoryCustomField:
      type: object
      properties:
        field_id:
          description: The unique public ID for a CustomField.
          type: string
          format: uuid
        value_id:
          description: The unique public ID for a CustomFieldEnumValue.
          type: string
          format: uuid
        value:
          description: A string representation of the value, if applicable.
          type: string
      additionalProperties: false
      required:
      - field_id
      - value_id
      - value
    CreateEpicComment:
      x-doc-skip: true
      type: object
      properties:
        text:
          maxLength: 100000
          description: The comment text.
          minLength: 1
          type: string
        author_id:
          description: The Member ID of the Comment's author. Defaults to the user identified by the API token.
          type: string
          format: uuid
        created_at:
          description: Defaults to the time/date the comment is created, but can be set to reflect another date.
          type: string
          format: date-time
        updated_at:
          description: Defaults to the time/date the comment is last updated, but can be set to reflect another date.
          type: string
          format: date-time
        external_id:
          maxLength: 128
          description: This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.
          type: string
      additionalProperties: false
      required:
      - text
    CreateEpic:
      x-doc-skip: true
      type: object
      properties:
        description:
          maxLength: 100000
          description: The Epic's description.
          type: string
        labels:
          description: An array of Labels attached to the Epic.
          type: array
          items:
            $ref: '#/components/schemas/CreateLabelParams'
        completed_at_override:
          description: A manual override for the time/date the Epic was completed.
          type: string
          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:
          maxLength: 256
          minLength: 1
          description: The Epic's name.
          type: string
        planned_start_date:
          description: The Epic's planned start date.
          type: string
          format: date-time
          nullable: true
        state:
          description: '`Deprecated` The Epic''s state (to do, in progress, or done); will be ignored when `epic_state_id` is set.'
          type: string
          enum:
          - in progress
          - to do
          - done
        milestone_id:
          description: '`Deprecated` The ID of the Milestone this Epic is related to. Use `objective_ids`.'
          type: integer
          format: int64
          nullable: true
        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
        started_at_override:
          description: A manual override for the time/date the Epic was started.
          type: string
          format: date-time
        group_id:
          description: '`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.'
          type: string
          format: uuid
          nullable: true
        updated_at:
          description: Defaults to the time/date it is created but can be set to reflect another date.
          type: string
          format: date-time
        follower_ids:
          description: An array of UUIDs for any Members you want to add as Followers on this new 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
        converted_from_story_id:
          description: The ID of the Story that was converted to an Epic.
          type: integer
          format: int64
          nullable: true
        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:
          maxLength: 128
          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
        deadline:
          description: The Epic's deadline.
          type: string
          format: date-time
          nullable: true
        created_at:
          description: Defaults to the time/date it is created but can be set to reflect another date.
          type: string
          format: date-time
      additionalProperties: false
      required:
      - name
    EpicAssociatedGroup:
      type: object
      properties:
        group_id:
          description: The Group ID of the associated group.
          type: string
          format: uuid
        associated_stories_count:
          description: The number of stories this Group owns in the Epic.
          type: integer
          format: int64
      additionalProperties: false
      required:
      - group_id
    UpdateComment:
      x-doc-skip: true
      type: object
      properties:
        text:
          description: The updated comment text.
          type: string
      additionalProperties: false
      required:
      - text
    EpicStats:
      description: A group of calculated values for this Epic.
      type: object
      properties:
        num_points_done:
          description: The total number of completed points in this Epic.
          type: integer
          format: int64
        num_related_documents:
          description: The total number of documents associated with this Epic.
          type: integer
          format: int64
        num_stories_unstarted:
          description: The total number of unstarted Stories in this Epic.
          type: integer
          format: int64
        num_stories_total:
          description: The total number of Stories in this Epic.
          type: integer
          format: int64
        last_story_update:
          description: The date of the last update of a Story in this Epic.
          type: string
          format: date-time
          nullable: true
        num_points_started:
          description: The total number of started points in this Epic.
          type: integer
          format: int64
        num_points_unstarted:
          description: The total number of unstarted points in this Epic.
          type: integer
          format: int64
        num_stories_started:
          description: The total number of started Stories in this Epic.
          type: integer
          format: int64
        num_stories_unestimated:
          description: The total number of Stories with no point estimate.
          type: integer
          format: int64
        num_stories_backlog:
          description: The total number of backlog Stories in this Epic.
          type: integer
          format: int64
        num_points_backlog:
          description: The total number of backlog points in this Epic.
          type: integer
          format: int64
        num_points:
          description: The total number of points in this Epic.
          type: integer
          format: int64
        num_stories_done:
          description:

# --- 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