Shortcut Software Milestones API

openapi: 3.2.0
info:
  title: Shortcut Categories Milestones API
  version: '3.0'
  description: Shortcut API
servers:
- url: https://api.app.shortcut.com
security:
- api_token: []
tags:
- name: Milestones
paths:
  /api/v3/milestones:
    get:
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Milestone'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listMilestones
      deprecated: true
      description: '(Deprecated: Use ''List Objectives'') List Milestones returns a list of all Milestones and their attributes.'
      summary: List Milestones
      tags:
      - Milestones
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMilestone'
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Milestone'
        '400':
          description: Schema mismatch
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnusableEntitlementError'
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createMilestone
      deprecated: true
      description: '(Deprecated: Use ''Create Objective'') Create Milestone allows you to create a new Milestone in Shortcut.'
      summary: Create Milestone
      tags:
      - Milestones
  /api/v3/milestones/{milestone-public-id}:
    get:
      parameters:
      - in: path
        name: milestone-public-id
        description: The ID of the Milestone.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Milestone'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: getMilestone
      deprecated: true
      description: '(Deprecated: Use ''Get Objective'') Get Milestone returns information about a chosen Milestone.'
      summary: Get Milestone
      tags:
      - Milestones
    put:
      parameters:
      - in: path
        name: milestone-public-id
        description: The ID of the Milestone.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMilestone'
        required: true
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Milestone'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: updateMilestone
      deprecated: true
      description: '(Deprecated: Use ''Update Objective'') Update Milestone can be used to update Milestone properties.'
      summary: Update Milestone
      tags:
      - Milestones
    delete:
      parameters:
      - in: path
        name: milestone-public-id
        description: The ID of the Milestone.
        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: deleteMilestone
      deprecated: true
      description: '(Deprecated: Use ''Delete Objective'') Delete Milestone can be used to delete any Milestone.'
      summary: Delete Milestone
      tags:
      - Milestones
  /api/v3/milestones/{milestone-public-id}/epics:
    get:
      parameters:
      - in: path
        name: milestone-public-id
        description: The ID of the Milestone.
        required: true
        schema:
          type: integer
          format: int64
      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: listMilestoneEpics
      deprecated: true
      description: '(Deprecated: Use ''List Objective Epics'') List all of the Epics within the Milestone.'
      summary: List Milestone Epics
      tags:
      - Milestones
components:
  schemas:
    UpdateMilestone:
      x-doc-skip: true
      type: object
      properties:
        description:
          maxLength: 100000
          description: The Milestone's description.
          type: string
        archived:
          description: A boolean indicating whether the Milestone is archived or not
          type: boolean
        completed_at_override:
          description: A manual override for the time/date the Milestone was completed.
          type:
          - string
          - 'null'
          format: date-time
        name:
          maxLength: 256
          minLength: 1
          description: The name of the Milestone.
          type: string
        state:
          description: The workflow state that the Milestone is in.
          type: string
          enum:
          - in progress
          - to do
          - done
        started_at_override:
          description: A manual override for the time/date the Milestone was started.
          type:
          - string
          - 'null'
          format: date-time
        categories:
          description: An array of IDs of Categories attached to the Milestone.
          type: array
          items:
            $ref: '#/components/schemas/CreateCategoryParams'
        before_id:
          description: The ID of the Milestone we want to move this Milestone before.
          type: integer
          format: int64
        after_id:
          description: The ID of the Milestone we want to move this Milestone after.
          type: integer
          format: int64
      additionalProperties: false
    EpicSlim:
      description: EpicSlim represents the same resource as an Epic but is more light-weight, including all Epic fields except the comments array. The description string can be optionally included. Use the [Get Epic](#Get-Epic) endpoint to fetch the unabridged payload for an Epic.
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Epic.
          type: string
        description:
          description: The Epic's description.
          type: string
        archived:
          description: True/false boolean that indicates whether the Epic is archived or not.
          type: boolean
        started:
          description: A true/false boolean indicating if the Epic has been started.
          type: boolean
        entity_type:
          description: A string description of this resource.
          type: string
        labels:
          description: An array of Labels attached to the Epic.
          type: array
          items:
            $ref: '#/components/schemas/LabelSlim'
        mention_ids:
          description: '`Deprecated:` use `member_mention_ids`.'
          type: array
          items:
            type: string
            format: uuid
        member_mention_ids:
          description: An array of Member IDs that have been mentioned in the Epic description.
          type: array
          items:
            type: string
            format: uuid
        associated_groups:
          description: An array containing Group IDs and Group-owned story counts for the Epic's associated groups.
          type: array
          items:
            $ref: '#/components/schemas/EpicAssociatedGroup'
        project_ids:
          description: The IDs of Projects related to this Epic.
          type: array
          items:
            type: integer
            format: int64
        stories_without_projects:
          description: The number of stories in this epic which are not associated with a project.
          type: integer
          format: int64
        completed_at_override:
          description: A manual override for the time/date the Epic was completed.
          type:
          - string
          - 'null'
          format: date-time
        productboard_plugin_id:
          description: The ID of the associated productboard integration.
          type:
          - string
          - 'null'
          format: uuid
        started_at:
          description: The time/date the Epic was started.
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          description: The time/date the Epic was completed.
          type:
          - string
          - 'null'
          format: date-time
        objective_ids:
          description: An array of IDs for Objectives to which this epic is related.
          type: array
          items:
            type: integer
            format: int64
        name:
          description: The name of the Epic.
          type: string
        global_id:
          x-doc-skip: true
          type: string
        completed:
          description: A true/false boolean indicating if the Epic has been completed.
          type: boolean
        productboard_url:
          description: The URL of the associated productboard feature.
          type:
          - string
          - 'null'
        planned_start_date:
          description: The Epic's planned start date.
          type:
          - string
          - 'null'
          format: date-time
        state:
          description: '`Deprecated` The workflow state that the Epic is in.'
          type: string
        milestone_id:
          description: '`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`.'
          type:
          - integer
          - 'null'
          format: int64
        requested_by_id:
          description: The ID of the Member that requested the epic.
          type: string
          format: uuid
        epic_state_id:
          description: The ID of the Epic State.
          type: integer
          format: int64
        label_ids:
          description: An array of Label ids attached to the Epic.
          type: array
          items:
            type: integer
            format: int64
        started_at_override:
          description: A manual override for the time/date the Epic was started.
          type:
          - string
          - 'null'
          format: date-time
        group_id:
          description: '`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.'
          type:
          - string
          - 'null'
          format: uuid
        updated_at:
          description: The time/date the Epic was updated.
          type:
          - string
          - 'null'
          format: date-time
        group_mention_ids:
          description: An array of Group IDs that have been mentioned in the Epic description.
          type: array
          items:
            type: string
            format: uuid
        productboard_id:
          description: The ID of the associated productboard feature.
          type:
          - string
          - 'null'
          format: uuid
        follower_ids:
          description: An array of UUIDs for any Members you want to add as Followers on this Epic.
          type: array
          items:
            type: string
            format: uuid
        group_ids:
          description: An array of UUIDS for Groups to which this Epic is related.
          type: array
          items:
            type: string
            format: uuid
        owner_ids:
          description: An array of UUIDs for any members you want to add as Owners on this new Epic.
          type: array
          items:
            type: string
            format: uuid
        external_id:
          description: This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
          type:
          - string
          - 'null'
        id:
          description: The unique ID of the Epic.
          type: integer
          format: int64
        position:
          description: The Epic's relative position in the Epic workflow state.
          type: integer
          format: int64
        productboard_name:
          description: The name of the associated productboard feature.
          type:
          - string
          - 'null'
        deadline:
          description: The Epic's deadline.
          type:
          - string
          - 'null'
          format: date-time
        stats:
          $ref: '#/components/schemas/EpicStats'
        created_at:
          description: The time/date the Epic was created.
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: false
      required:
      - app_url
      - archived
      - started
      - entity_type
      - labels
      - mention_ids
      - member_mention_ids
      - associated_groups
      - project_ids
      - stories_without_projects
      - completed_at_override
      - productboard_plugin_id
      - started_at
      - completed_at
      - objective_ids
      - name
      - global_id
      - completed
      - productboard_url
      - planned_start_date
      - state
      - milestone_id
      - requested_by_id
      - epic_state_id
      - label_ids
      - started_at_override
      - group_id
      - updated_at
      - group_mention_ids
      - productboard_id
      - follower_ids
      - group_ids
      - owner_ids
      - external_id
      - id
      - position
      - productboard_name
      - deadline
      - stats
      - created_at
    Milestone:
      description: (Deprecated) A Milestone is a collection of Epics that represent a release or some other large initiative that you are working on. Milestones have become Objectives, so you should use Objective-related API resources instead of Milestone ones.
      type: object
      properties:
        app_url:
          description: The Shortcut application url for the Milestone.
          type: string
        description:
          description: The Milestone's description.
          type: string
        archived:
          description: A boolean indicating whether the Milestone has been archived or not.
          type: boolean
        started:
          description: A true/false boolean indicating if the Milestone has been started.
          type: boolean
        entity_type:
          description: A string description of this resource.
          type: string
        completed_at_override:
          description: A manual override for the time/date the Milestone was completed.
          type:
          - string
          - 'null'
          format: date-time
        started_at:
          description: The time/date the Milestone was started.
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          description: The time/date the Milestone was completed.
          type:
          - string
          - 'null'
          format: date-time
        name:
          description: The name of the Milestone.
          type: string
        global_id:
          x-doc-skip: true
          type: string
        completed:
          description: A true/false boolean indicating if the Milestone has been completed.
          type: boolean
        state:
          description: The workflow state that the Milestone is in.
          type: string
        started_at_override:
          description: A manual override for the time/date the Milestone was started.
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          description: The time/date the Milestone was updated.
          type: string
          format: date-time
        categories:
          description: An array of Categories attached to the Milestone.
          type: array
          items:
            $ref: '#/components/schemas/Category'
        id:
          description: The unique ID of the Milestone.
          type: integer
          format: int64
        key_result_ids:
          description: The IDs of the Key Results associated with the Objective.
          type: array
          items:
            type: string
            format: uuid
        position:
          description: A number representing the position of the Milestone in relation to every other Milestone within the Workspace.
          type: integer
          format: int64
        stats:
          $ref: '#/components/schemas/MilestoneStats'
        created_at:
          description: The time/date the Milestone was created.
          type: string
          format: date-time
      additionalProperties: false
      required:
      - app_url
      - description
      - archived
      - started
      - entity_type
      - completed_at_override
      - started_at
      - completed_at
      - name
      - global_id
      - completed
      - state
      - started_at_override
      - updated_at
      - categories
      - id
      - key_result_ids
      - position
      - stats
      - created_at
    UnusableEntitlementError:
      type: object
      properties:
        reason_tag:
          description: The tag for violating an entitlement action.
          type: string
          enum:
          - entitlement-violation
        entitlement_tag:
          maxLength: 63
          minLength: 1
          description: Short tag describing the unusable entitlement action taken by the user.
          type: string
        message:
          maxLength: 256
          minLength: 1
          description: Message displayed to the user on why their action failed.
          type: string
      additionalProperties: false
      required:
      - reason_tag
      - entitlement_tag
      - message
    Category:
      description: A Category can be used to associate Objectives.
      type: object
      properties:
        archived:
          description: A true/false boolean indicating if the Category 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 Category (for example, "#ff0000").
          pattern: ^#[a-fA-F0-9]{6}$
          format: css-color
          minLength: 1
          type:
          - string
          - 'null'
        name:
          description: The name of the Category.
          type: string
        global_id:
          description: The Global ID of the Category.
          x-doc-skip: true
          type: string
        type:
          description: The type of entity this Category is associated with; currently Milestone or Objective is the only type of Category.
          x-doc-skip: true
          type: string
        updated_at:
          description: The time/date that the Category was updated.
          type: string
          format: date-time
        external_id:
          description: This field can be set to another unique ID. In the case that the Category 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 Category.
          type: integer
          format: int64
        created_at:
          description: The time/date that the Category was created.
          type: string
          format: date-time
      additionalProperties: false
      required:
      - archived
      - entity_type
      - color
      - name
      - global_id
      - type
      - updated_at
      - external_id
      - id
      - created_at
    MilestoneStats:
      description: A group of calculated values for this Milestone.
      type: object
      properties:
        average_cycle_time:
          description: The average cycle time (in seconds) of completed stories in this Milestone.
          type: integer
          format: int64
        average_lead_time:
          description: The average lead time (in seconds) of completed stories in this Milestone.
          type: integer
          format: int64
        num_related_documents:
          description: The number of related documents to this Milestone.
          type: integer
          format: int64
      additionalProperties: false
      required:
      - num_related_documents
    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
    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
    CreateCategoryParams:
      description: Request parameters for creating a Category with a Objective.
      type: object
      properties:
        name:
          maxLength: 128
          minLength: 1
          description: The name of the new Category.
          type: string
        color:
          pattern: ^#[a-fA-F0-9]{6}$
          format: css-color
          description: The hex color to be displayed with the Category (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 Category has been imported from another tool, the ID in the other tool can be indicated here.
          type: string
      additionalProperties: false
      required:
      - name
    CreateMilestone:
      x-doc-skip: true
      type: object
      properties:
        name:
          maxLength: 256
          minLength: 1
          description: The name of the Milestone.
          type: string
        description:
          maxLength: 100000
          description: The Milestone's description.
          type: string
        state:
          description: The workflow state that the Milestone is in.
          type: string
          enum:
          - in progress
          - to do
          - done
        started_at_override:
          description: A manual override for the time/date the Milestone was started.
          type: string
          format: date-time
        completed_at_override:
          description: A manual override for the time/date the Milestone was completed.
          type: string
          format: date-time
        categories:
          description: An array of IDs of Categories attached to the Milestone.
          type: array
          items:
            $ref: '#/components/schemas/CreateCategoryParams'
      additionalProperties: false
      required:
      - name
    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
          - 'null'
          format: date-time
        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: The total number of done Stories in this Epic.
          type: integer
          format: int64
      additionalProperties: false
      required:
      - num_points_done
      - num_related_documents
      - num_stories_unstarted
      - num_stories_total
      - last_story_update
      - num_points_started
      - num_points_unstarted
      - num_stories_started
      - num_stories_unestimated
      - num_stories_backlog
      - num_points_backlog
      - num_points
      - num_stories_done
  securitySchemes:
    api_token:
      type: apiKey
      in: header
      name: Shortcut-Token