Shortcut Software Iterations API

openapi: 3.2.0
info:
  title: Shortcut Categories Iterations API
  version: '3.0'
  description: Shortcut API
servers:
- url: https://api.app.shortcut.com
security:
- api_token: []
tags:
- name: Iterations
paths:
  /api/v3/iterations:
    get:
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IterationSlim'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listIterations
      summary: List Iterations
      tags:
      - Iterations
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIteration'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Iteration'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createIteration
      summary: Create Iteration
      tags:
      - Iterations
  /api/v3/iterations/disable:
    put:
      responses:
        '204':
          description: No Content
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: disableIterations
      description: Disables Iterations for the current workspace
      summary: Disable Iterations
      tags:
      - Iterations
  /api/v3/iterations/enable:
    put:
      responses:
        '204':
          description: No Content
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: enableIterations
      description: Enables Iterations for the current workspace
      summary: Enable Iterations
      tags:
      - Iterations
  /api/v3/iterations/{iteration-public-id}:
    get:
      parameters:
      - in: path
        name: iteration-public-id
        description: The unique ID of the Iteration.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Iteration'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: getIteration
      summary: Get Iteration
      tags:
      - Iterations
    put:
      parameters:
      - in: path
        name: iteration-public-id
        description: The unique ID of the Iteration.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIteration'
        required: true
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Iteration'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: updateIteration
      summary: Update Iteration
      tags:
      - Iterations
    delete:
      parameters:
      - in: path
        name: iteration-public-id
        description: The unique ID of the Iteration.
        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: deleteIteration
      summary: Delete Iteration
      tags:
      - Iterations
  /api/v3/iterations/{iteration-public-id}/stories:
    get:
      parameters:
      - in: path
        name: iteration-public-id
        description: The unique ID of the Iteration.
        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: listIterationStories
      description: Get a list of all Stories in an Iteration.
      summary: List Iteration Stories
      tags:
      - Iterations
components:
  schemas:
    Label:
      description: A Label can be used to associate and filter Stories and Epics, and also create new Workspaces.
      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
        stats:
          $ref: '#/components/schemas/LabelStats'
        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
    LabelStats:
      description: A group of calculated values for this Label. This is not included if the slim? flag is set to true for the List Labels endpoint.
      type: object
      properties:
        num_related_documents:
          description: The total number of Documents associated this Label.
          type: integer
          format: int64
        num_epics:
          description: The total number of Epics with this Label.
          type: integer
          format: int64
        num_stories_unstarted:
          description: The total number of stories unstarted Stories with this Label.
          type: integer
          format: int64
        num_stories_total:
          description: The total number of Stories with this Label.
          type: integer
          format: int64
        num_epics_unstarted:
          description: The number of unstarted epics associated with this label.
          type: integer
          format: int64
        num_epics_in_progress:
          description: The number of in progress epics associated with this label.
          type: integer
          format: int64
        num_points_unstarted:
          description: The total number of unstarted points with this Label.
          type: integer
          format: int64
        num_stories_unestimated:
          description: The total number of Stories with no point estimate with this Label.
          type: integer
          format: int64
        num_points_in_progress:
          description: The total number of in-progress points with this Label.
          type: integer
          format: int64
        num_epics_total:
          description: The total number of Epics associated with this Label.
          type: integer
          format: int64
        num_stories_completed:
          description: The total number of completed Stories with this Label.
          type: integer
          format: int64
        num_points_completed:
          description: The total number of completed points with this Label.
          type: integer
          format: int64
        num_stories_backlog:
          description: The total number of stories backlog Stories with this Label.
          type: integer
          format: int64
        num_points_total:
          description: The total number of points with this Label.
          type: integer
          format: int64
        num_stories_in_progress:
          description: The total number of in-progress Stories with this Label.
          type: integer
          format: int64
        num_points_backlog:
          description: The total number of backlog points with this Label.
          type: integer
          format: int64
        num_epics_completed:
          description: The number of completed Epics associated with this Label.
          type: integer
          format: int64
      additionalProperties: false
      required:
      - num_related_documents
      - num_epics
      - num_stories_unstarted
      - num_stories_total
      - num_epics_unstarted
      - num_epics_in_progress
      - num_points_unstarted
      - num_stories_unestimated
      - num_points_in_progress
      - num_epics_total
      - num_stories_completed
      - num_points_completed
      - num_stories_backlog
      - num_points_total
      - num_stories_in_progress
      - num_points_backlog
      - num_epics_completed
    StoryStats:
      description: The stats object for Stories
      type: object
      properties:
        num_related_documents:
          description: The number of documents related to this Story.
          type: integer
          format: int64
      additionalProperties: false
      required:
      - num_related_documents
    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
    Iteration:
      description: An Iteration is a defined, time-boxed period of development for a collection of Stories. See https://help.shortcut.com/hc/en-us/articles/360028953452-Iterations-Overview for more information.
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Iteration.
          type: string
        description:
          description: The description of the iteration.
          type: string
        entity_type:
          description: A string description of this resource
          type: string
        labels:
          description: An array of labels attached to the iteration.
          type: array
          items:
            $ref: '#/components/schemas/Label'
        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 Story description.
          type: array
          items:
            type: string
            format: uuid
        associated_groups:
          description: An array containing Group IDs and Group-owned story counts for the Iteration's associated groups.
          x-doc-skip: true
          type: array
          items:
            $ref: '#/components/schemas/IterationAssociatedGroup'
        name:
          description: The name of the iteration.
          type: string
        global_id:
          x-doc-skip: true
          type: string
        label_ids:
          description: An array of label ids attached to the iteration.
          type: array
          items:
            type: integer
            format: int64
        updated_at:
          description: The instant when this iteration was last updated.
          type: string
          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
        end_date:
          description: The date this iteration ends.
          type: string
          format: date-time
        follower_ids:
          description: An array of UUIDs for any Members listed as Followers.
          type: array
          items:
            type: string
            format: uuid
        group_ids:
          description: An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
          type: array
          items:
            type: string
            format: uuid
        start_date:
          description: The date this iteration begins.
          type: string
          format: date-time
        status:
          description: The status of the iteration. Values are either "unstarted", "started", or "done".
          type: string
        id:
          description: The ID of the iteration.
          type: integer
          format: int64
        stats:
          $ref: '#/components/schemas/IterationStats'
        created_at:
          description: The instant when this iteration was created.
          type: string
          format: date-time
      additionalProperties: false
      required:
      - app_url
      - description
      - entity_type
      - labels
      - mention_ids
      - member_mention_ids
      - associated_groups
      - name
      - global_id
      - label_ids
      - updated_at
      - group_mention_ids
      - end_date
      - follower_ids
      - group_ids
      - start_date
      - status
      - id
      - stats
      - created_at
    CreateIteration:
      type: object
      properties:
        follower_ids:
          description: An array of UUIDs for any Members you want to add as Followers.
          type: array
          items:
            type: string
            format: uuid
        group_ids:
          description: An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
          type: array
          items:
            type: string
            format: uuid
        labels:
          description: An array of Labels attached to the Iteration.
          type: array
          items:
            $ref: '#/components/schemas/CreateLabelParams'
        description:
          maxLength: 100000
          description: The description of the Iteration.
          type: string
        name:
          maxLength: 256
          minLength: 1
          description: The name of this Iteration.
          type: string
        start_date:
          minLength: 1
          description: The date this Iteration begins, e.g. 2019-07-01.
          type: string
        end_date:
          minLength: 1
          description: The date this Iteration ends, e.g. 2019-07-01.
          type: string
      additionalProperties: false
      required:
      - name
      - start_date
      - end_date
    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 enabled.'
          type:
          - integer
          - 'null'
          format: int64
        estimate:
          description: The numeric point estimate of the story. Can also be null, which means unestimated.
          type:
          - integer
          - 'null'
          format: int64
        position:
          description: A number representing the position of the story in relation to every other story in the current project.
          type: integer
          format: int64
        blocked:
          description: A true/false boolean indicating if the Story is currently blocked.
          type: boolean
        project_id:
          description: The ID of the project the story belongs to.
          type:
          - integer
          - 'null'
          format: int64
        linked_file_ids:
          description: An array of IDs of LinkedFiles attached to the story.
          type: array
          items:
            type: integer
            format: int64
        deadline:
          description: The due date of the story.
          type:
          - string
          - 'null'
          format: date-time
        stats:
          $ref: '#/components/schemas/StoryStats'
        comment_ids:
          description: An array of IDs of Comments attached to the story.
          type: array
          items:
            type: integer
            format: int64
        cycle_time:
          description: The cycle time (in seconds) of this story when complete.
          type: integer
          format: int64
        created_at:
          description: The time/date the Story was created.
          type: string
          format: date-time
        moved_at:
          description: The time/date the Story was last changed workflow-state.
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: false
      required:
      - app_url
      - archived
      - started
      - story_links
      - entity_type
      - labels
      - task_ids
      - mention_ids
      - member_mention_ids
      - story_type
      - file_ids
      - num_tasks_completed
      - workflow_id
      - completed_at_override
      - started_at
      - completed_at
      - name
      - global_id
      - completed
      - blocker
      - epic_id
      - story_template_id
      - external_links
      - previous_iteration_ids
      - requested_by_id
      - iteration_id
      - label_ids
      - started_at_override
      - group_id
      - workflow_state_id
      - updated_at
      - group_mention_ids
      - follower_ids
      - owner_ids
      - external_id
      - id
      - estimate
      - position
      - blocked
      - project_id
      - linked_file_ids
      - deadline
      - stats
      - comment_ids
      - created_at
      - moved_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
    UpdateIteration:
      type: object
      properties:
        follower_ids:
          description: An array of UUIDs for any Members you want to add as Followers.
          type: array
          items:
            type: string
            format: uuid
        group_ids:
          description: An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
          type: array
          items:
            type: string
            format: uuid
        labels:
          description: An array of Labels attached to the Iteration.
          type: array
          items:
            $ref: '#/components/schemas/CreateLabelParams'
        description:
          maxLength: 100000
          description: The description of the Iteration.
          type: string
        name:
          maxLength: 256
          minLength: 1
          description: The name of this Iteration
          type: string
        start_date:
          minLength: 1
          description: The date this Iteration begins, e.g. 2019-07-01
          type: string
        end_date:
          minLength: 1
          description: The date this Iteration ends, e.g. 2019-07-05.
          type: string
      additionalProperties: false
    IterationAssociatedGroup:
      x-doc-skip: true
      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 Iteration.
          type: integer
          format: int64
      additionalProperties: false
      required:
      - group_id
    CreateLabelParams:
      description: Request parameters for creating a Label on a Shortcut Story.
      type: object
      properties:
        name:
          maxLength: 128
          minLength: 1
          description: The name of the new Label.
          type: string
        description:
          maxLength: 1024
          description: The description of the new Label.
          type: string
        color:
          pattern: ^#[a-fA-F0-9]{6}$
          format: css-color
          description: The hex color to be displayed with the Label (for example, "#ff0000").
          minLength: 1
          type: string
        external_id:
          maxLength: 128
          minLength: 1
          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
      additionalProperties: false
      required:
      - name
    IterationSlim:
      description: 'IterationSlim represents the same resource as an Iteration, but is more light-weight. Use the [Get Iteration](#Get-Iteration) endpoint to fetch the unabridged payload for an Iteration. '
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Iteration.
          type: string
        entity_type:
          description: A string description of this resource
          type: string
        labels:
          description: An array of labels attached to the iteration.
          type: array
          items:
            $ref: '#/components/schemas/Label'
        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 Story description.
          type: array
          items:
            type: string
            format: uuid
        associated_groups:
          description: An array containing Group IDs and Group-owned story counts for the Iteration's associated groups.
          x-doc-skip: true
          type: 

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