Shortcut Software Labels API

openapi: 3.2.0
info:
  title: Shortcut Categories Labels API
  version: '3.0'
  description: Shortcut API
servers:
- url: https://api.app.shortcut.com
security:
- api_token: []
tags:
- name: Labels
paths:
  /api/v3/labels:
    get:
      parameters:
      - in: query
        name: slim
        description: A true/false boolean indicating if the slim versions of the Label should be returned.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Label'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: listLabels
      description: List Labels returns a list of all Labels and their attributes.
      summary: List Labels
      tags:
      - Labels
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLabelParams'
        description: Request parameters for creating a Label on a Shortcut Story.
        required: true
      responses:
        '201':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: createLabel
      description: Create Label allows you to create a new Label in Shortcut.
      summary: Create Label
      tags:
      - Labels
  /api/v3/labels/{label-public-id}:
    get:
      parameters:
      - in: path
        name: label-public-id
        description: The unique ID of the Label.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: getLabel
      description: Get Label returns information about the selected Label.
      summary: Get Label
      tags:
      - Labels
    put:
      parameters:
      - in: path
        name: label-public-id
        description: The unique ID of the Label you wish to update.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLabel'
        required: true
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
        '400':
          description: Schema mismatch
        '404':
          description: Resource does not exist
        '422':
          description: Unprocessable
      operationId: updateLabel
      description: Update Label allows you to replace a Label name with another name. If you try to name a Label something that already exists, you will receive a 422 response.
      summary: Update Label
      tags:
      - Labels
    delete:
      parameters:
      - in: path
        name: label-public-id
        description: The unique ID of the Label.
        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: deleteLabel
      description: Delete Label can be used to delete any Label.
      summary: Delete Label
      tags:
      - Labels
  /api/v3/labels/{label-public-id}/epics:
    get:
      parameters:
      - in: path
        name: label-public-id
        description: The unique ID of the Label.
        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: listLabelEpics
      description: List all of the Epics with the Label.
      summary: List Label Epics
      tags:
      - Labels
  /api/v3/labels/{label-public-id}/stories:
    get:
      parameters:
      - in: path
        name: label-public-id
        description: The unique ID of the Label.
        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: listLabelStories
      description: List all of the Stories with the Label.
      summary: List Label Stories
      tags:
      - Labels
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
    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
    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
    UpdateLabel:
      x-doc-skip: true
      type: object
      properties:
        name:
          maxLength: 128
          minLength: 1
          description: The new name of the label.
          type: string
        description:
          maxLength: 1024
          description: The new description of the label.
          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'
        archived:
          description: A true/false boolean indicating if the Label has been archived.
          type: boolean
      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
    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
    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:
   

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