Shortcut Software Labels API
The Labels API from Shortcut Software — 4 operation(s) for labels.
OpenAPI Specification
openapi: 3.0.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:
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
EpicStats:
description: A group of calculated values for this Epic.
type: object
properties:
num_points_done:
description: The total number of completed points in this Epic.
type: integer
format: int64
num_related_documents:
description: The total number of documents associated with this Epic.
type: integer
format: int64
num_stories_unstarted:
description: The total number of unstarted Stories in this Epic.
type: integer
format: int64
num_stories_total:
description: The total number of Stories in this Epic.
type: integer
format: int64
last_story_update:
description: The date of the last update of a Story in this Epic.
type: string
format: date-time
nullable: true
num_points_started:
description: The total number of started points in this Epic.
type: integer
format: int64
num_points_unstarted:
description: The total number of unstarted points in this Epic.
type: integer
format: int64
num_stories_started:
description: The total number of started Stories in this Epic.
type: integer
format: int64
num_stories_unestimated:
description: The total number of Stories with no point estimate.
type: integer
format: int64
num_stories_backlog:
description: The total number of backlog Stories in this Epic.
type: integer
format: int64
num_points_backlog:
description: The total number of backlog points in this Epic.
type: integer
format: int64
num_points:
description: The total number of points in this Epic.
type: integer
format: int64
num_stories_done:
description: 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
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
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
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
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
format: date-time
nullable: true
productboard_plugin_id:
description: The ID of the associated productboard integration.
type: string
format: uuid
nullable: true
started_at:
description: The time/date the Epic was started.
type: string
format: date-time
nullable: true
completed_at:
description: The time/date the Epic was completed.
type: string
format: date-time
nullable: true
objective_ids:
description: An array of IDs for Objectives to which this epic is related.
type: array
items:
type: integer
format: int64
name:
description: The name of the Epic.
type: string
global_id:
x-doc-skip: true
type: string
completed:
description: A true/false boolean indicating if the Epic has been completed.
type: boolean
productboard_url:
description: The URL of the associated productboard feature.
type: string
nullable: true
planned_start_date:
description: The Epic's planned start date.
type: string
format: date-time
nullable: true
state:
description: '`Deprecated` The workflow state that the Epic is in.'
type: string
milestone_id:
description: '`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`.'
type: integer
format: int64
nullable: true
requested_by_id:
description: The ID of the Member that requested the epic.
type: string
format: uuid
epic_state_id:
description: The ID of the Epic State.
type: integer
format: int64
label_ids:
description: An array of Label ids attached to the Epic.
type: array
items:
type: integer
format: int64
started_at_override:
description: A manual override for the time/date the Epic was started.
type: string
format: date-time
nullable: true
group_id:
description: '`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.'
type: string
format: uuid
nullable: true
updated_at:
description: The time/date the Epic was updated.
type: string
format: date-time
nullable: true
group_mention_ids:
description: An array of Group IDs that have been mentioned in the Epic description.
type: array
items:
type: string
format: uuid
productboard_id:
description: The ID of the associated productboard feature.
type: string
format: uuid
nullable: true
follower_ids:
description: An array of UUIDs for any Members you want to add as Followers on this Epic.
type: array
items:
type: string
format: uuid
group_ids:
description: An array of UUIDS for Groups to which this Epic is related.
type: array
items:
type: string
format: uuid
owner_ids:
description: An array of UUIDs for any members you want to add as Owners on this new Epic.
type: array
items:
type: string
format: uuid
external_id:
description: This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
type: string
nullable: true
id:
description: The unique ID of the Epic.
type: integer
format: int64
position:
description: The Epic's relative position in the Epic workflow state.
type: integer
format: int64
productboard_name:
description: The name of the associated productboard feature.
type: string
nullable: true
deadline:
description: The Epic's deadline.
type: string
format: date-time
nullable: true
stats:
$ref: '#/components/schemas/EpicStats'
created_at:
description: The time/date the Epic was created.
type: string
format: date-time
nullable: true
additionalProperties: false
required:
- app_url
- 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
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
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
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
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 arch
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shortcut-software/refs/heads/main/openapi/shortcut-software-labels-api-openapi.yml