Shortcut API
create_category
Create Category allows you to create a new Category in Shortcut.
Parameters
$body
Type: object
{
"color" : "The hex color to be displayed with the Category (for example, \"#ff0000\").",
"name" : "The name of the new Category.",
"external_id" : "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" : "The type of entity this Category is associated with; currently Milestone is the only type of Category."
}
create_entity_template
Create a new entity template for your organization.
Parameters
$body
Request paramaters for creating an entirely new entity template.
Type: object
{
"name" : "The name of the new entity template",
"author_id" : "The id of the user creating this template.",
"story_contents" : {
"workflow_state_id" : "The ID of the workflow state the story is currently in.",
"workflow_id" : "The ID of the workflow.",
"label_ids" : [ "integer" ],
"linked_files" : [ {
"member_mention_ids" : [ "uuid" ],
"uploader_id" : "The UUID of the member that uploaded the file.",
"description" : "The description of the file.",
"created_at" : "The time/date the LinkedFile was created.",
"group_mention_ids" : [ "uuid" ],
"thumbnail_url" : "The URL of the file thumbnail, if the integration provided it.",
"type" : "The integration type (e.g. google, dropbox, box).",
"url" : "The URL of the file.",
"entity_type" : "A string description of this resource.",
"size" : "The filesize, if the integration provided it.",
"content_type" : "The content type of the image (e.g. txt/plain).",
"updated_at" : "The time/date the LinkedFile was updated.",
"story_ids" : [ "integer" ],
"name" : "The name of the linked file.",
"id" : "The unique identifier for the file.",
"mention_ids" : [ "uuid" ]
} ],
"description" : "The description of the story.",
"linked_file_ids" : [ "integer" ],
"labels" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"iteration_id" : "The ID of the iteration the to be populated.",
"story_type" : "The type of story (feature, bug, chore).",
"entity_type" : "A string description of this resource.",
"group_id" : "The ID of the group to be populated.",
"project_id" : "The ID of the project the story belongs to.",
"external_links" : [ "string" ],
"follower_ids" : [ "uuid" ],
"file_ids" : [ "integer" ],
"name" : "The name of the story.",
"estimate" : "The numeric point estimate to be populated.",
"files" : [ {
"member_mention_ids" : [ "uuid" ],
"uploader_id" : "The unique ID of the Member who uploaded the file.",
"description" : "The description of the file.",
"created_at" : "The time/date that the file was created.",
"group_mention_ids" : [ "uuid" ],
"external_id" : "This field can be set to another unique ID. In the case that the File has been imported from another tool, the ID in the other tool can be indicated here.",
"thumbnail_url" : "The url where the thumbnail of the file can be found in Shortcut.",
"url" : "The URL for the file.",
"entity_type" : "A string description of this resource.",
"filename" : "The name assigned to the file in Shortcut upon upload.",
"size" : "The size of the file.",
"content_type" : "Free form string corresponding to a text or image file.",
"updated_at" : "The time/date that the file was updated.",
"story_ids" : [ "integer" ],
"name" : "The optional User-specified name of the file.",
"id" : "The unique ID for the file.",
"mention_ids" : [ "uuid" ]
} ],
"deadline" : "The due date of the story.",
"tasks" : [ {
"description" : "The Task description.",
"external_id" : "This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.",
"complete" : "True/false boolean indicating whether the Task is completed. Defaults to false.",
"owner_ids" : [ "uuid" ]
} ],
"owner_ids" : [ "uuid" ],
"epic_id" : "The ID of the epic the to be populated."
}
}
create_epic
Create Epic allows you to create a new Epic in Shortcut.
Parameters
$body
Type: object
{
"requested_by_id" : "The ID of the member that requested the epic.",
"milestone_id" : "The ID of the Milestone this Epic is related to.",
"description" : "The Epic's description.",
"created_at" : "Defaults to the time/date it is created but can be set to reflect another date.",
"external_id" : "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.",
"labels" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"started_at_override" : "A manual override for the time/date the Epic was started.",
"updated_at" : "Defaults to the time/date it is created but can be set to reflect another date.",
"group_id" : "The ID of the group to associate with the epic.",
"epic_state_id" : "The ID of the Epic State.",
"follower_ids" : [ "uuid" ],
"name" : "The Epic's name.",
"planned_start_date" : "The Epic's planned start date.",
"state" : "`Deprecated` The Epic's state (to do, in progress, or done); will be ignored when `epic_state_id` is set.",
"deadline" : "The Epic's deadline.",
"completed_at_override" : "A manual override for the time/date the Epic was completed.",
"owner_ids" : [ "uuid" ]
}
create_epic_comment
This endpoint allows you to create a threaded Comment on an Epic.
Parameters
epic-public-id (required)
The ID of the associated Epic.
Type: integer
$body
Type: object
{
"updated_at" : "Defaults to the time/date the comment is last updated, but can be set to reflect another date.",
"created_at" : "Defaults to the time/date the comment is created, but can be set to reflect another date.",
"external_id" : "This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.",
"text" : "The comment text.",
"author_id" : "The Member ID of the Comment's author. Defaults to the user identified by the API token."
}
create_epic_comment_comment
This endpoint allows you to create a nested Comment reply to an existing Epic Comment.
Parameters
comment-public-id (required)
The ID of the parent Epic Comment.
Type: integer
epic-public-id (required)
The ID of the associated Epic.
Type: integer
$body
Type: object
{
"updated_at" : "Defaults to the time/date the comment is last updated, but can be set to reflect another date.",
"created_at" : "Defaults to the time/date the comment is created, but can be set to reflect another date.",
"external_id" : "This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.",
"text" : "The comment text.",
"author_id" : "The Member ID of the Comment's author. Defaults to the user identified by the API token."
}
create_group
Create Group
Parameters
$body
Type: object
{
"workflow_ids" : [ "integer" ],
"mention_name" : "The mention name of this Group.",
"display_icon_id" : "The Icon id for the avatar of this Group.",
"color" : "The color you wish to use for the Group in the system.",
"color_key" : "The color key you wish to use for the Group in the system.",
"member_ids" : [ "uuid" ],
"name" : "The name of this Group.",
"description" : "The description of the Group."
}
create_iteration
Create Iteration
Parameters
$body
Type: object
{
"end_date" : "The date this Iteration ends, e.g. 2019-07-01.",
"follower_ids" : [ "uuid" ],
"group_ids" : [ "uuid" ],
"name" : "The name of this Iteration.",
"description" : "The description of the Iteration.",
"labels" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"start_date" : "The date this Iteration begins, e.g. 2019-07-01."
}
create_label
Create Label allows you to create a new Label in Shortcut.
Parameters
$body
Request parameters for creating a Label on a Shortcut Story.
Type: object
{
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
}
create_linked_file
Create Linked File allows you to create a new Linked File in Shortcut.
Parameters
$body
Type: object
{
"uploader_id" : "The UUID of the member that uploaded the file.",
"size" : "The filesize, if the integration provided it.",
"content_type" : "The content type of the image (e.g. txt/plain).",
"story_id" : "The ID of the linked story.",
"name" : "The name of the file.",
"description" : "The description of the file.",
"thumbnail_url" : "The URL of the thumbnail, if the integration provided it.",
"type" : "The integration type of the file (e.g. google, dropbox, box).",
"url" : "The URL of linked file."
}
create_milestone
Create Milestone allows you to create a new Milestone in Shortcut.
Parameters
$body
Type: object
{
"started_at_override" : "A manual override for the time/date the Milestone was started.",
"name" : "The name of the Milestone.",
"description" : "The Milestone's description.",
"state" : "The workflow state that the Milestone is in.",
"categories" : [ {
"color" : "The hex color to be displayed with the Category (for example, \"#ff0000\").",
"name" : "The name of the new Category.",
"external_id" : "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."
} ],
"completed_at_override" : "A manual override for the time/date the Milestone was completed."
}
create_multiple_stories
Create Multiple Stories allows you to create multiple stories in a single request using the same syntax as Create Story.
Parameters
$body
Type: object
{
"stories" : [ {
"workflow_state_id" : "The ID of the workflow state the story will be in.",
"requested_by_id" : "The ID of the member that requested the story.",
"description" : "The description of the story.",
"linked_file_ids" : [ "integer" ],
"created_at" : "The time/date the Story was created.",
"external_id" : "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.",
"story_type" : "The type of story (feature, bug, chore).",
"archived" : "Controls the story's archived state.",
"updated_at" : "The time/date the Story was updated.",
"story_template_id" : "The id of the story template used to create this story, if applicable.",
"project_id" : "The ID of the project the story belongs to.",
"follower_ids" : [ "uuid" ],
"file_ids" : [ "integer" ],
"estimate" : "The numeric point estimate of the story. Can also be null, which means unestimated.",
"deadline" : "The due date of the story.",
"tasks" : [ {
"updated_at" : "Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date.",
"description" : "The Task description.",
"created_at" : "Defaults to the time/date the Task is created but can be set to reflect another creation time/date.",
"external_id" : "This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.",
"complete" : "True/false boolean indicating whether the Task is completed. Defaults to false.",
"owner_ids" : [ "uuid" ]
} ],
"comments" : [ {
"updated_at" : "Defaults to the time/date the comment is last updated, but can be set to reflect another date.",
"parent_id" : "The ID of the Comment that this comment is threaded under.",
"created_at" : "Defaults to the time/date the comment is created, but can be set to reflect another date.",
"external_id" : "This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.",
"text" : "The comment text.",
"author_id" : "The Member ID of the Comment's author. Defaults to the user identified by the API token."
} ],
"story_links" : [ {
"subject_id" : "The unique ID of the Story defined as subject.",
"verb" : "How the subject Story acts on the object Story. This can be \"blocks\", \"duplicates\", or \"relates to\".",
"object_id" : "The unique ID of the Story defined as object."
} ],
"labels" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"iteration_id" : "The ID of the iteration the story belongs to.",
"started_at_override" : "A manual override for the time/date the Story was started.",
"group_id" : "The id of the group to associate with this story.",
"external_links" : [ "string" ],
"name" : "The name of the story.",
"completed_at_override" : "A manual override for the time/date the Story was completed.",
"owner_ids" : [ "uuid" ],
"epic_id" : "The ID of the epic the story belongs to."
} ]
}
create_project
Create Project is used to create a new Shortcut Project.
Parameters
$body
Type: object
{
"start_time" : "The date at which the Project was started.",
"color" : "The color you wish to use for the Project in the system.",
"updated_at" : "Defaults to the time/date it is created but can be set to reflect another date.",
"follower_ids" : [ "uuid" ],
"name" : "The name of the Project.",
"description" : "The Project description.",
"created_at" : "Defaults to the time/date it is created but can be set to reflect another date.",
"external_id" : "This field can be set to another unique ID. In the case that the Project has been imported from another tool, the ID in the other tool can be indicated here.",
"team_id" : "The ID of the team the project belongs to.",
"abbreviation" : "The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.",
"iteration_length" : "The number of weeks per iteration in this Project."
}
create_story
Create Story is used to add a new story to your Shortcut.
Parameters
$body
Request parameters for creating a story.
Type: object
{
"workflow_state_id" : "The ID of the workflow state the story will be in.",
"requested_by_id" : "The ID of the member that requested the story.",
"description" : "The description of the story.",
"linked_file_ids" : [ "integer" ],
"created_at" : "The time/date the Story was created.",
"external_id" : "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.",
"story_type" : "The type of story (feature, bug, chore).",
"archived" : "Controls the story's archived state.",
"updated_at" : "The time/date the Story was updated.",
"story_template_id" : "The id of the story template used to create this story, if applicable.",
"project_id" : "The ID of the project the story belongs to.",
"follower_ids" : [ "uuid" ],
"file_ids" : [ "integer" ],
"estimate" : "The numeric point estimate of the story. Can also be null, which means unestimated.",
"deadline" : "The due date of the story.",
"tasks" : [ {
"updated_at" : "Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date.",
"description" : "The Task description.",
"created_at" : "Defaults to the time/date the Task is created but can be set to reflect another creation time/date.",
"external_id" : "This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.",
"complete" : "True/false boolean indicating whether the Task is completed. Defaults to false.",
"owner_ids" : [ "uuid" ]
} ],
"comments" : [ {
"updated_at" : "Defaults to the time/date the comment is last updated, but can be set to reflect another date.",
"parent_id" : "The ID of the Comment that this comment is threaded under.",
"created_at" : "Defaults to the time/date the comment is created, but can be set to reflect another date.",
"external_id" : "This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.",
"text" : "The comment text.",
"author_id" : "The Member ID of the Comment's author. Defaults to the user identified by the API token."
} ],
"story_links" : [ {
"subject_id" : "The unique ID of the Story defined as subject.",
"verb" : "How the subject Story acts on the object Story. This can be \"blocks\", \"duplicates\", or \"relates to\".",
"object_id" : "The unique ID of the Story defined as object."
} ],
"labels" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"iteration_id" : "The ID of the iteration the story belongs to.",
"started_at_override" : "A manual override for the time/date the Story was started.",
"group_id" : "The id of the group to associate with this story.",
"external_links" : [ "string" ],
"name" : "The name of the story.",
"completed_at_override" : "A manual override for the time/date the Story was completed.",
"owner_ids" : [ "uuid" ],
"epic_id" : "The ID of the epic the story belongs to."
}
create_story_comment
Create Comment allows you to create a Comment on any Story.
Parameters
story-public-id (required)
The ID of the Story that the Comment is in.
Type: integer
$body
Type: object
{
"updated_at" : "Defaults to the time/date the comment is last updated, but can be set to reflect another date.",
"parent_id" : "The ID of the Comment that this comment is threaded under.",
"created_at" : "Defaults to the time/date the comment is created, but can be set to reflect another date.",
"external_id" : "This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.",
"text" : "The comment text.",
"author_id" : "The Member ID of the Comment's author. Defaults to the user identified by the API token."
}
create_story_link
Story Links (called Story Relationships in the UI) allow you create semantic relationships between two stories. The parameters read like an active voice grammatical sentence: subject -> verb -> object.
The subject story acts on the object Story; the object story is the direct object of the sentence.
The subject story "blocks", "duplicates", or "relates to" the object story. Examples:
- "story 5 blocks story 6” -- story 6 is now "blocked" until story 5 is moved to a Done workflow state.
- "story 2 duplicates story 1” -- Story 2 represents the same body of work as Story 1 (and should probably be archived).
- "story 7 relates to story 3”
Parameters
$body
Type: object
{
"subject_id" : "The ID of the subject Story.",
"verb" : "The type of link.",
"object_id" : "The ID of the object Story."
}
create_story_reaction
Create a reaction to a story comment.
Parameters
comment-public-id (required)
The ID of the Comment.
Type: integer
story-public-id (required)
The ID of the Story that the Comment is in.
Type: integer
$body
Type: object
{
"emoji" : "The emoji short-code to add / remove. E.g. `:thumbsup::skin-tone-4:`."
}
create_task
Create Task is used to create a new task in a Story.
Parameters
story-public-id (required)
The ID of the Story that the Task will be in.
Type: integer
$body
Type: object
{
"updated_at" : "Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date.",
"description" : "The Task description.",
"created_at" : "Defaults to the time/date the Task is created but can be set to reflect another creation time/date.",
"external_id" : "This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.",
"complete" : "True/false boolean indicating whether the Task is completed. Defaults to false.",
"owner_ids" : [ "uuid" ]
}
delete_category
Delete Category can be used to delete any Category.
Parameters
category-public-id (required)
The unique ID of the Category.
Type: integer
delete_entity_template
Delete Entity Template
Parameters
entity-template-public-id (required)
The unique ID of the entity template.
Type: uuid
delete_epic
Delete Epic can be used to delete the Epic. The only required parameter is Epic ID.
Parameters
epic-public-id (required)
The unique ID of the Epic.
Type: integer
delete_epic_comment
This endpoint allows you to delete a Comment from an Epic.
Parameters
comment-public-id (required)
The ID of the Comment.
Type: integer
epic-public-id (required)
The ID of the associated Epic.
Type: integer
delete_file
Delete File deletes a previously uploaded file.
Parameters
file-public-id (required)
The File’s unique ID.
Type: integer
delete_iteration
Delete Iteration
Parameters
iteration-public-id (required)
The unique ID of the Iteration.
Type: integer
delete_label
Delete Label can be used to delete any Label.
Parameters
label-public-id (required)
The unique ID of the Label.
Type: integer
delete_linked_file
Delete Linked File can be used to delete any previously attached Linked-File.
Parameters
linked-file-public-id (required)
The unique identifier of the linked file.
Type: integer
delete_milestone
Delete Milestone can be used to delete any Milestone.
Parameters
milestone-public-id (required)
The ID of the Milestone.
Type: integer
delete_multiple_stories
Delete Multiple Stories allows you to delete multiple archived stories at once.
Parameters
$body
Type: object
{
"story_ids" : [ "integer" ]
}
delete_project
Delete Project can be used to delete a Project. Projects can only be deleted if all associated Stories are moved or deleted. In the case that the Project cannot be deleted, you will receive a 422 response.
Parameters
project-public-id (required)
The unique ID of the Project.
Type: integer
delete_story
Delete Story can be used to delete any Story.
Parameters
story-public-id (required)
The ID of the Story.
Type: integer
delete_story_comment
Delete a Comment from any story.
Parameters
comment-public-id (required)
The ID of the Comment.
Type: integer
story-public-id (required)
The ID of the Story that the Comment is in.
Type: integer
delete_story_link
Removes the relationship between the stories for the given Story Link.
Parameters
story-link-public-id (required)
The unique ID of the Story Link.
Type: integer
delete_story_reaction
Delete a reaction from any story comment.
Parameters
comment-public-id (required)
The ID of the Comment.
Type: integer
story-public-id (required)
The ID of the Story that the Comment is in.
Type: integer
$body
Type: object
{
"emoji" : "The emoji short-code to add / remove. E.g. `:thumbsup::skin-tone-4:`."
}
delete_task
Delete Task can be used to delete any previously created Task on a Story.
Parameters
story-public-id (required)
The unique ID of the Story this Task is associated with.
Type: integer
task-public-id (required)
The unique ID of the Task.
Type: integer
disable_groups
Disables Groups for the current workspace2
This operation has no parameters
disable_iterations
Disables Iterations for the current workspace
This operation has no parameters
disable_story_templates
Disables the Story Template feature for the given Organization.
This operation has no parameters
enable_groups
Enables Groups for the current workspace2
This operation has no parameters
enable_iterations
Enables Iterations for the current workspace
This operation has no parameters
enable_story_templates
Enables the Story Template feature for the given Organization.
This operation has no parameters
get_category
Get Category returns information about the selected Category.
Parameters
category-public-id (required)
The unique ID of the Category.
Type: integer
get_current_member_info
Returns information about the authenticated member.
This operation has no parameters
get_entity_template
Get Entity Template returns information about a given entity template.
Parameters
entity-template-public-id (required)
The unique ID of the entity template.
Type: uuid
get_epic
Get Epic returns information about the selected Epic.
Parameters
epic-public-id (required)
The unique ID of the Epic.
Type: integer
get_epic_comment
This endpoint returns information about the selected Epic Comment.
Parameters
comment-public-id (required)
The ID of the Comment.
Type: integer
epic-public-id (required)
The ID of the associated Epic.
Type: integer
get_epic_workflow
Get Epic Workflow returns the Epic Workflow for the organization.
This operation has no parameters
get_external_link_stories
Get Stories which have a given External Link associated with them.
Parameters
$body
Type: object
{
"external_link" : "The external link associated with one or more stories."
}
get_file
Get File returns information about the selected UploadedFile.
Parameters
file-public-id (required)
The File’s unique ID.
Type: integer
get_group
Get Group
Parameters
group-public-id (required)
The unique ID of the Group.
Type: uuid
get_iteration
Get Iteration
Parameters
iteration-public-id (required)
The unique ID of the Iteration.
Type: integer
get_label
Get Label returns information about the selected Label.
Parameters
label-public-id (required)
The unique ID of the Label.
Type: integer
get_linked_file
Get File returns information about the selected Linked File.
Parameters
linked-file-public-id (required)
The unique identifier of the linked file.
Type: integer
get_member
Returns information about a Member.
Parameters
member-public-id (required)
The Member's unique ID.
Type: uuid
$body
Type: object
{
"org-public-id" : "The unique ID of the Organization to limit the lookup to."
}
get_milestone
Get Milestone returns information about a chosen Milestone.
Parameters
milestone-public-id (required)
The ID of the Milestone.
Type: integer
get_project
Get Project returns information about the selected Project.
Parameters
project-public-id (required)
The unique ID of the Project.
Type: integer
get_repository
Get Repository returns information about the selected Repository.
Parameters
repo-public-id (required)
The unique ID of the Repository.
Type: integer
get_story
Get Story returns information about a chosen Story.
Parameters
story-public-id (required)
The ID of the Story.
Type: integer
get_story_comment
Get Comment is used to get Comment information.
Parameters
comment-public-id (required)
The ID of the Comment.
Type: integer
story-public-id (required)
The ID of the Story that the Comment is in.
Type: integer
get_story_link
Returns the stories and their relationship for the given Story Link.
Parameters
story-link-public-id (required)
The unique ID of the Story Link.
Type: integer
get_task
Returns information about a chosen Task.
Parameters
story-public-id (required)
The unique ID of the Story this Task is associated with.
Type: integer
task-public-id (required)
The unique ID of the Task.
Type: integer
get_workflow
Get Workflow returns information about a chosen Workflow.
Parameters
workflow-public-id (required)
The ID of the Workflow.
Type: integer
list_categories
List Categories returns a list of all Categories and their attributes.
This operation has no parameters
list_category_milestones
List Category Milestones returns a list of all Milestones with the Category.
Parameters
category-public-id (required)
The unique ID of the Category.
Type: integer
list_entity_templates
List all the entity templates for an organization.
This operation has no parameters
list_epic_comments
Get a list of all Comments on an Epic.
Parameters
epic-public-id (required)
The unique ID of the Epic.
Type: integer
list_epic_stories
Get a list of all Stories in an Epic.
Parameters
epic-public-id (required)
The unique ID of the Epic.
Type: integer
$body
Type: object
{
"includes_description" : "A true/false boolean indicating whether to return Stories with their descriptions."
}
list_epics
List Epics returns a list of all Epics and their attributes.
Parameters
$body
Type: object
{
"includes_description" : "A true/false boolean indicating whether to return Epics with their descriptions."
}
list_files
List Files returns a list of all UploadedFiles in the workspace.
This operation has no parameters
list_group_stories
List the Stories assigned to the Group. (By default, limited to 1,000).
Parameters
group-public-id (required)
The unique ID of the Group.
Type: uuid
$body
Type: object
{
"offset" : "The offset at which to begin returning results. (Defaults to 0)",
"limit" : "The maximum number of results to return. (Defaults to 1000, max 1000)"
}
list_groups
A group in our API maps to a "Team" within the Shortcut Product. A Team is a collection of Users that can be associated to Stories, Epics, and Iterations within Shortcut.
This operation has no parameters
list_iteration_stories
Get a list of all Stories in an Iteration.
Parameters
iteration-public-id (required)
The unique ID of the Iteration.
Type: integer
$body
Type: object
{
"includes_description" : "A true/false boolean indicating whether to return Stories with their descriptions."
}
list_iterations
List Iterations
This operation has no parameters
list_label_epics
List all of the Epics with the Label.
Parameters
label-public-id (required)
The unique ID of the Label.
Type: integer
list_label_stories
List all of the Stories with the Label.
Parameters
label-public-id (required)
The unique ID of the Label.
Type: integer
$body
Type: object
{
"includes_description" : "A true/false boolean indicating whether to return Stories with their descriptions."
}
list_labels
List Labels returns a list of all Labels and their attributes.
Parameters
$body
Type: object
{
"slim" : "A true/false boolean indicating if the slim versions of the Label should be returned."
}
list_linked_files
List Linked Files returns a list of all Linked-Files and their attributes.
This operation has no parameters
list_members
List Members returns information about members of the organization.
Parameters
$body
Type: object
{
"org-public-id" : "The unique ID of the Organization to limit the list to."
}
list_milestone_epics
List all of the Epics within the Milestone.
Parameters
milestone-public-id (required)
The ID of the Milestone.
Type: integer
list_milestones
List Milestones returns a list of all Milestones and their attributes.
This operation has no parameters
list_projects
List Projects returns a list of all Projects and their attributes.
This operation has no parameters
list_repositories
List Repositories returns a list of all Repositories and their attributes.
This operation has no parameters
list_stories
List Stories returns a list of all Stories in a selected Project and their attributes.
Parameters
project-public-id (required)
The unique ID of the Project.
Type: integer
$body
Type: object
{
"includes_description" : "A true/false boolean indicating whether to return Stories with their descriptions."
}
list_workflows
List Workflows returns a list of all Workflows in the organization.
This operation has no parameters
search
Search lets you search Epics and Stories based on desired parameters. Since ordering of the results can change over time (due to search ranking decay, new Epics and Stories being created), the next value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
Parameters
$body
Type: object
{
"next" : "The next page token.",
"include" : "string. Possible values: cursors",
"query" : "See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)",
"page_size" : "The number of search results to include in a page. Minimum of 1 and maximum of 25."
}
search_epics
Search Epics lets you search Epics based on desired parameters. Since ordering of stories can change over time (due to search ranking decay, new Epics being created), the next value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
Parameters
$body
Type: object
{
"next" : "The next page token.",
"include" : "string. Possible values: cursors",
"query" : "See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)",
"page_size" : "The number of search results to include in a page. Minimum of 1 and maximum of 25."
}
search_stories
Search Stories lets you search Stories based on desired parameters. Since ordering of stories can change over time (due to search ranking decay, new stories being created), the next value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
Parameters
$body
Type: object
{
"next" : "The next page token.",
"include" : "string. Possible values: cursors",
"query" : "See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)",
"page_size" : "The number of search results to include in a page. Minimum of 1 and maximum of 25."
}
search_stories_old
Search Stories lets you search Stories based on desired parameters.
Parameters
$body
Type: object
{
"workflow_state_id" : "The unique IDs of the specific Workflow States that the Stories should be in.",
"includes_description" : "Whether to include the story description in the response.",
"completed_at_start" : "Stories should have been competed after this date.",
"requested_by_id" : "The UUID of any Users who may have requested the Stories.",
"owner_id" : "An array of UUIDs for any Users who may be Owners of the Stories.",
"external_id" : "An ID or URL that references an external resource. Useful during imports.",
"workflow_state_types" : [ "string. Possible values: started | unstarted | done" ],
"story_type" : "The type of Stories that you want returned.",
"archived" : "A true/false boolean indicating whether the Story is in archived state.",
"updated_at_start" : "Stories should have been updated after this date.",
"created_at_start" : "Stories should have been created after this date.",
"project_id" : "The IDs for the Projects the Stories may be assigned to.",
"group_ids" : [ "uuid" ],
"estimate" : "The number of estimate points associate with the Stories.",
"created_at_end" : "Stories should have been created before this date.",
"label_name" : "The name of any associated Labels.",
"iteration_ids" : [ "integer" ],
"epic_ids" : [ "integer" ],
"label_ids" : [ "integer" ],
"project_ids" : [ "integer" ],
"updated_at_end" : "Stories should have been updated before this date.",
"iteration_id" : "The Iteration ID that may be associated with the Stories.",
"group_id" : "The Group ID that is associated with the Stories",
"completed_at_end" : "Stories should have been completed before this date.",
"deadline_end" : "Stories should have a deadline before this date.",
"owner_ids" : [ "uuid" ],
"epic_id" : "The Epic IDs that may be associated with the Stories.",
"deadline_start" : "Stories should have a deadline after this date."
}
story_history
Story History
Parameters
story-public-id (required)
The ID of the Story.
Type: integer
unlink_productboard_from_epic
This endpoint allows you to unlink a productboard epic.
Parameters
epic-public-id (required)
The unique ID of the Epic.
Type: integer
update_category
Update Category allows you to replace a Category name with another name. If you try to name a Category something that already exists, you will receive a 422 response.
Parameters
category-public-id (required)
The unique ID of the Category you wish to update.
Type: integer
$body
Type: object
{
"archived" : "A true/false boolean indicating if the Category has been archived.",
"color" : "The hex color to be displayed with the Category (for example, \"#ff0000\").",
"name" : "The new name of the Category."
}
update_entity_template
Update an entity template's name or its contents.
Parameters
entity-template-public-id (required)
The unique ID of the template to be updated.
Type: uuid
$body
Request parameters for changing either a template's name or any of the attributes it is designed to pre-populate.
Type: object
{
"name" : "The updated template name.",
"story_contents" : {
"workflow_state_id" : "The ID of the workflow state the story is currently in.",
"label_ids" : [ "integer" ],
"linked_files" : [ {
"member_mention_ids" : [ "uuid" ],
"uploader_id" : "The UUID of the member that uploaded the file.",
"description" : "The description of the file.",
"created_at" : "The time/date the LinkedFile was created.",
"group_mention_ids" : [ "uuid" ],
"thumbnail_url" : "The URL of the file thumbnail, if the integration provided it.",
"type" : "The integration type (e.g. google, dropbox, box).",
"url" : "The URL of the file.",
"entity_type" : "A string description of this resource.",
"size" : "The filesize, if the integration provided it.",
"content_type" : "The content type of the image (e.g. txt/plain).",
"updated_at" : "The time/date the LinkedFile was updated.",
"story_ids" : [ "integer" ],
"name" : "The name of the linked file.",
"id" : "The unique identifier for the file.",
"mention_ids" : [ "uuid" ]
} ],
"description" : "The description of the story.",
"linked_file_ids" : [ "integer" ],
"labels" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"iteration_id" : "The ID of the iteration the to be populated.",
"story_type" : "The type of story (feature, bug, chore).",
"entity_type" : "A string description of this resource.",
"group_id" : "The ID of the group to be populated.",
"project_id" : "The ID of the project the story belongs to.",
"external_links" : [ "string" ],
"follower_ids" : [ "uuid" ],
"file_ids" : [ "integer" ],
"name" : "The name of the story.",
"estimate" : "The numeric point estimate to be populated.",
"files" : [ {
"member_mention_ids" : [ "uuid" ],
"uploader_id" : "The unique ID of the Member who uploaded the file.",
"description" : "The description of the file.",
"created_at" : "The time/date that the file was created.",
"group_mention_ids" : [ "uuid" ],
"external_id" : "This field can be set to another unique ID. In the case that the File has been imported from another tool, the ID in the other tool can be indicated here.",
"thumbnail_url" : "The url where the thumbnail of the file can be found in Shortcut.",
"url" : "The URL for the file.",
"entity_type" : "A string description of this resource.",
"filename" : "The name assigned to the file in Shortcut upon upload.",
"size" : "The size of the file.",
"content_type" : "Free form string corresponding to a text or image file.",
"updated_at" : "The time/date that the file was updated.",
"story_ids" : [ "integer" ],
"name" : "The optional User-specified name of the file.",
"id" : "The unique ID for the file.",
"mention_ids" : [ "uuid" ]
} ],
"deadline" : "The due date of the story.",
"tasks" : [ {
"description" : "The Task description.",
"external_id" : "This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.",
"complete" : "True/false boolean indicating whether the Task is completed. Defaults to false.",
"owner_ids" : [ "uuid" ]
} ],
"owner_ids" : [ "uuid" ],
"epic_id" : "The ID of the epic the to be populated."
}
}
update_epic
Update Epic can be used to update numerous fields in the Epic. The only required parameter is Epic ID, which can be found in the Shortcut UI.
Parameters
epic-public-id (required)
The unique ID of the Epic.
Type: integer
$body
Type: object
{
"requested_by_id" : "The ID of the member that requested the epic.",
"milestone_id" : "The ID of the Milestone this Epic is related to.",
"description" : "The Epic's description.",
"labels" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"archived" : "A true/false boolean indicating whether the Epic is in archived state.",
"started_at_override" : "A manual override for the time/date the Epic was started.",
"group_id" : "The ID of the group to associate with the epic.",
"epic_state_id" : "The ID of the Epic State.",
"follower_ids" : [ "uuid" ],
"name" : "The Epic's name.",
"planned_start_date" : "The Epic's planned start date.",
"after_id" : "The ID of the Epic we want to move this Epic after.",
"state" : "`Deprecated` The Epic's state (to do, in progress, or done); will be ignored when `epic_state_id` is set.",
"deadline" : "The Epic's deadline.",
"completed_at_override" : "A manual override for the time/date the Epic was completed.",
"owner_ids" : [ "uuid" ],
"before_id" : "The ID of the Epic we want to move this Epic before."
}
update_epic_comment
This endpoint allows you to update a threaded Comment on an Epic.
Parameters
comment-public-id (required)
The ID of the Comment.
Type: integer
epic-public-id (required)
The ID of the associated Epic.
Type: integer
$body
Type: object
{
"text" : "The updated comment text."
}
update_file
Update File updates the properties of an UploadedFile (but not its content).
Parameters
file-public-id (required)
The unique ID assigned to the file in Shortcut.
Type: integer
$body
Type: object
{
"uploader_id" : "The unique ID assigned to the Member who uploaded the file to Shortcut.",
"updated_at" : "The time/date that the file was last updated.",
"name" : "The name of the file.",
"description" : "The description of the file.",
"created_at" : "The time/date that the file was uploaded.",
"external_id" : "An additional ID that you may wish to assign to the file."
}
update_group
Update Group
Parameters
group-public-id (required)
The unique ID of the Group.
Type: uuid
$body
Type: object
{
"workflow_ids" : [ "integer" ],
"archived" : "Whether or not this Group is archived.",
"mention_name" : "The mention name of this Group.",
"display_icon_id" : "The Icon id for the avatar of this Group.",
"color" : "The color you wish to use for the Group in the system.",
"color_key" : "The color key you wish to use for the Group in the system.",
"member_ids" : [ "uuid" ],
"name" : "The name of this Group.",
"description" : "The description of this Group."
}
update_iteration
Update Iteration
Parameters
iteration-public-id (required)
The unique ID of the Iteration.
Type: integer
$body
Type: object
{
"end_date" : "The date this Iteration ends, e.g. 2019-07-05.",
"follower_ids" : [ "uuid" ],
"group_ids" : [ "uuid" ],
"name" : "The name of this Iteration",
"description" : "The description of the Iteration.",
"labels" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"start_date" : "The date this Iteration begins, e.g. 2019-07-01"
}
update_label
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.
Parameters
label-public-id (required)
The unique ID of the Label you wish to update.
Type: integer
$body
Type: object
{
"archived" : "A true/false boolean indicating if the Label has been archived.",
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The new name of the label.",
"description" : "The new description of the label."
}
update_linked_file
Updated Linked File allows you to update properties of a previously attached Linked-File.
Parameters
linked-file-public-id (required)
The unique identifier of the linked file.
Type: integer
$body
Type: object
{
"uploader_id" : "The UUID of the member that uploaded the file.",
"size" : "The filesize, if the integration provided it.",
"story_id" : "The ID of the linked story.",
"name" : "The name of the file.",
"description" : "The description of the file.",
"thumbnail_url" : "The URL of the thumbnail, if the integration provided it.",
"type" : "The integration type of the file (e.g. google, dropbox, box).",
"url" : "The URL of linked file."
}
update_milestone
Update Milestone can be used to update Milestone properties.
Parameters
milestone-public-id (required)
The ID of the Milestone.
Type: integer
$body
Type: object
{
"started_at_override" : "A manual override for the time/date the Milestone was started.",
"name" : "The name of the Milestone.",
"description" : "The Milestone's description.",
"after_id" : "The ID of the Milestone we want to move this Milestone after.",
"state" : "The workflow state that the Milestone is in.",
"categories" : [ {
"color" : "The hex color to be displayed with the Category (for example, \"#ff0000\").",
"name" : "The name of the new Category.",
"external_id" : "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."
} ],
"completed_at_override" : "A manual override for the time/date the Milestone was completed.",
"before_id" : "The ID of the Milestone we want to move this Milestone before."
}
update_multiple_stories
Update Multiple Stories allows you to make changes to numerous stories at once.
Parameters
$body
Type: object
{
"workflow_state_id" : "The ID of the workflow state to put the stories in.",
"requested_by_id" : "The ID of the member that requested the story.",
"owner_ids_remove" : [ "uuid" ],
"iteration_id" : "The ID of the iteration the story belongs to.",
"story_type" : "The type of story (feature, bug, chore).",
"archived" : "If the Stories should be archived or not.",
"owner_ids_add" : [ "uuid" ],
"group_id" : "The Id of the Group the Stories should belong to.",
"project_id" : "The ID of the Project the Stories should belong to.",
"story_ids" : [ "integer" ],
"move_to" : "One of \"first\" or \"last\". This can be used to move the given story to the first or last position in the workflow state.",
"external_links" : [ "string" ],
"follower_ids_remove" : [ "uuid" ],
"estimate" : "The numeric point estimate of the story. Can also be null, which means unestimated.",
"labels_remove" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"after_id" : "The ID of the story that the stories are to be moved below.",
"follower_ids_add" : [ "uuid" ],
"deadline" : "The due date of the story.",
"epic_id" : "The ID of the epic the story belongs to.",
"labels_add" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"before_id" : "The ID of the story that the stories are to be moved before."
}
update_project
Update Project can be used to change properties of a Project.
Parameters
project-public-id (required)
The unique ID of the Project.
Type: integer
$body
Type: object
{
"days_to_thermometer" : "The number of days before the thermometer appears in the Story summary.",
"archived" : "A true/false boolean indicating whether the Story is in archived state.",
"show_thermometer" : "Configuration to enable or disable thermometers in the Story summary.",
"color" : "The color that represents the Project in the UI.",
"follower_ids" : [ "uuid" ],
"name" : "The Project's name.",
"description" : "The Project's description.",
"team_id" : "The ID of the team the project belongs to.",
"abbreviation" : "The Project abbreviation used in Story summaries. Should be kept to 3 characters at most."
}
update_story
Update Story can be used to update Story properties.
Parameters
story-public-id (required)
The unique identifier of this story.
Type: integer
$body
Type: object
{
"workflow_state_id" : "The ID of the workflow state to put the story in.",
"requested_by_id" : "The ID of the member that requested the story.",
"commit_ids" : [ "integer" ],
"description" : "The description of the story.",
"linked_file_ids" : [ "integer" ],
"story_type" : "The type of story (feature, bug, chore).",
"archived" : "True if the story is archived, otherwise false.",
"project_id" : "The ID of the project the story belongs to.",
"follower_ids" : [ "uuid" ],
"file_ids" : [ "integer" ],
"estimate" : "The numeric point estimate of the story. Can also be null, which means unestimated.",
"after_id" : "The ID of the story we want to move this story after.",
"deadline" : "The due date of the story.",
"pull_request_ids" : [ "integer" ],
"labels" : [ {
"color" : "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"name" : "The name of the new Label.",
"description" : "The description of the new Label.",
"external_id" : "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."
} ],
"iteration_id" : "The ID of the iteration the story belongs to.",
"started_at_override" : "A manual override for the time/date the Story was started.",
"group_id" : "The ID of the group to associate with this story",
"move_to" : "One of \"first\" or \"last\". This can be used to move the given story to the first or last position in the workflow state.",
"external_links" : [ "string" ],
"branch_ids" : [ "integer" ],
"name" : "The title of the story.",
"completed_at_override" : "A manual override for the time/date the Story was completed.",
"owner_ids" : [ "uuid" ],
"epic_id" : "The ID of the epic the story belongs to.",
"before_id" : "The ID of the story we want to move this story before."
}
update_story_comment
Update Comment replaces the text of the existing Comment.
Parameters
comment-public-id (required)
The ID of the Comment
Type: integer
story-public-id (required)
The ID of the Story that the Comment is in.
Type: integer
$body
Type: object
{
"text" : "The updated comment text."
}
update_story_link
Updates the stories and/or the relationship for the given Story Link.
Parameters
story-link-public-id (required)
The unique ID of the Story Link.
Type: integer
$body
Type: object
{
"subject_id" : "The ID of the subject Story.",
"verb" : "The type of link.",
"object_id" : "The ID of the object Story."
}
update_task
Update Task can be used to update Task properties.
Parameters
story-public-id (required)
The unique identifier of the parent Story.
Type: integer
task-public-id (required)
The unique identifier of the Task you wish to update.
Type: integer
$body
Type: object
{
"description" : "The Task's description.",
"after_id" : "Move task after this task ID.",
"complete" : "A true/false boolean indicating whether the task is complete.",
"owner_ids" : [ "uuid" ],
"before_id" : "Move task before this task ID."
}