Shortcut (version v1.*.*)

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 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."
}