Shortcut Software Iterations API

openapi: 3.0.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:
    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
    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
    IterationStats:
      description: A group of calculated values for this Iteration.
      type: object
      properties:
        num_points_done:
          description: The total number of completed points in this Iteration.
          type: integer
          format: int64
        num_related_documents:
          description: The total number of documents related to an Iteration
          type: integer
          format: int64
        average_cycle_time:
          description: The average cycle time (in seconds) of completed stories in this Iteration.
          type: integer
          format: int64
        num_stories_unstarted:
          description: The total number of unstarted Stories in this Iteration.
          type: integer
          format: int64
        num_points_started:
          description: The total number of started points in this Iteration.
          type: integer
          format: int64
        num_points_unstarted:
          description: The total number of unstarted points in this Iteration.
          type: integer
          format: int64
        num_stories_started:
          description: The total number of started Stories in this Iteration.
          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 Iteration.
          type: integer
          format: int64
        average_lead_time:
          description: The average lead time (in seconds) of completed stories in this Iteration.
          type: integer
          format: int64
        num_points_backlog:
          description: The total number of backlog points in this Iteration.
          type: integer
          format: int64
        num_points:
          description: The total number of points in this Iteration.
          type: integer
          format: int64
        num_stories_done:
          description: The total number of done Stories in this Iteration.
          type: integer
          format: int64
      additionalProperties: false
      required:
      - num_points_done
      - num_related_documents
      - num_stories_unstarted
      - num_points_started
      - num_points_unstarted
      - num_stories_started
      - num_stories_unestimated
      - num_stories_backlog
      - num_points_backlog
      - num_points
      - num_stories_done
    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
          nullable: true
        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
          nullable: true
        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
          format: date-time
          nullable: true
        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
          nullable: true
        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
          format: date-time
          nullable: true
      additionalProperties: false
      required:
      - app_url
      - description
      - archived
      - entity_type
      - color
      - name
      - global_id
      - updated_at
      - external_id
      - id
      - created_at
    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
    TypedStoryLink:
      description: 'The type of Story Link. The string can be subject or object. '
      type: object
      properties:
        entity_type:
          description: A string description of this resource.
          type: string
        object_id:
          description: The ID of the object Story.
          type: integer
          format: int64
        verb:
          description: How the subject Story acts on the object Story. This can be "blocks", "duplicates", or "relates to".
          type: string
        type:
          description: This indicates whether the Story is the subject or object in the Story Link.
          type: string
        updated_at:
          description: The time/date when the Story Link was last updated.
          type: string
          format: date-time
        id:
          description: The unique identifier of the Story Link.
          type: integer
          format: int64
        subject_id:
          description: The ID of the subject Story.
          type: integer
          format: int64
        subject_workflow_state_id:
          description: The workflow state of the "subject" story.
          x-doc-skip: true
          type: integer
          format: int64
        created_at:
          description: The time/date when the Story Link was created.
          type: string
          format: date-time
      additionalProperties: false
      required:
      - entity_type
      - object_id
      - verb
      - type
      - updated_at
      - id
      - subject_id
      - subject_workflow_state_id
      - created_at
    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
    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
          format: date-time
          nullable: true
        started_at:
          description: The time/date the Story was started.
          type: string
          format: date-time
          nullable: true
        completed_at:
          description: The time/date the Story was completed.
          type: string
          format: date-time
          nullable: true
        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
          format: int64
          nullable: true
        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
          format: uuid
          nullable: true
        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
          format: int64
          nullable: true
        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
          nullable: true
        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
          format: date-time
          nullable: true
        group_id:
          description: The ID of the group associated with the story.
          type: string
          format: uuid
          nullable: true
        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
          format: date-time
          nullable: true
        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
          nullable: true
        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
          format: int64
          nullable: true
        estimate:
          description: The numeric point estimate of the story. Can also be null, which means unestimated.
          type: integer
          format: int64
          nullable: true
        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
          format: int64
          nullable: true
        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
          format: date-time
          nullable: true
        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
          format: date-time
          nullable: true
      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
          nullable: true
        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
          nullable: true
        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
          format: date-time
          nullable: true
        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
          nullable: true
        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
          format: date-time
          nullable: true
      additionalProperties: false
      required:
      - app_url
      - description
      - archived
      - entity_type
      - color
      - name
      - global_id
      - updated_at
      - external_id
      - id
      - 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
    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: 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.


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