Iteration 5 endpoints

PUT /api/v3/iterations/enable Enable Iterations

Enables Iterations for the current workspace

operationId: Iteration_enableIterations

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/iterations/enable

DELETE /api/v3/iterations/{iteration-public-id} Delete Iteration

operationId: Iteration_removeById

Parameters

Name	In	Required	Type	Description
iteration-public-id	path	required	integer	The unique ID of the Iteration.

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

DELETE /api/v3/iterations/{iteration-public-id}

GET /api/v3/iterations/{iteration-public-id} Get Iteration

operationId: Iteration_getById

Parameters

Name	In	Required	Type	Description
iteration-public-id	path	required	integer	The unique ID of the Iteration.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/iterations/{iteration-public-id}

PUT /api/v3/iterations/{iteration-public-id} Update Iteration

operationId: Iteration_updateIterationById

Parameters

Name	In	Required	Type	Description
iteration-public-id	path	required	integer	The unique ID of the Iteration.

Request Body

required

application/json

schema UpdateIteration

Property	Type	Required
name	string	optional
labels	array	optional
└ name	string	required
└ color	string	optional
└ description	string	optional
└ external_id	string	optional
end_date	string	optional
group_ids	array	optional
start_date	string	optional
description	string	optional
follower_ids	array	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/iterations/{iteration-public-id}

GET /api/v3/iterations/{iteration-public-id}/stories List Iteration Stories

Get a list of all Stories in an Iteration.

operationId: Iteration_listStories

Parameters

Name	In	Required	Type	Description
iteration-public-id	path	required	integer	The unique ID of the Iteration.
includes_description	query	optional	boolean	A true/false boolean indicating whether to return Stories with their descriptions.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/iterations/{iteration-public-id}/stories

Keyresult 2 endpoints

GET /api/v3/key-results/{key-result-public-id} Get Key Result

Get Key Result returns information about a chosen Key Result.

operationId: KeyResult_getInformation

Parameters

Name	In	Required	Type	Description
key-result-public-id	path	required	string	The ID of the Key Result.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/key-results/{key-result-public-id}

PUT /api/v3/key-results/{key-result-public-id} Update Key Result

Update Key Result allows updating a Key Result’s name or initial, observed, or target values.

operationId: KeyResult_updateValues

Parameters

Name	In	Required	Type	Description
key-result-public-id	path	required	string	The ID of the Key Result.

Request Body

required

application/json

schema UpdateKeyResult

Property	Type	Required
name	string	optional
target_value	object	optional
└ boolean_value	boolean	optional
└ numeric_value	string	optional
observed_value	object	optional
└ boolean_value	boolean	optional
└ numeric_value	string	optional
initial_observed_value	object	optional
└ boolean_value	boolean	optional
└ numeric_value	string	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/key-results/{key-result-public-id}

Label 6 endpoints

GET /api/v3/labels List Labels

List Labels returns a list of all Labels and their attributes.

operationId: Label_list

Parameters

Name	In	Required	Type	Description
slim	query	optional	boolean	A true/false boolean indicating if the slim versions of the Label should be returned.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/labels

POST /api/v3/labels Create Label

Create Label allows you to create a new Label in Shortcut.

operationId: Label_createNew

Request Body

required

Request parameters for creating a Label on a Shortcut Story.

application/json

schema CreateLabelParams

Property	Type	Required
name	string	required
color	string	optional
description	string	optional
external_id	string	optional

Responses

201

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

POST /api/v3/labels

DELETE /api/v3/labels/{label-public-id} Delete Label

Delete Label can be used to delete any Label.

operationId: Label_remove

Parameters

Name	In	Required	Type	Description
label-public-id	path	required	integer	The unique ID of the Label.

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

DELETE /api/v3/labels/{label-public-id}

GET /api/v3/labels/{label-public-id} Get Label

Get Label returns information about the selected Label.

operationId: Label_getInfo

Parameters

Name	In	Required	Type	Description
label-public-id	path	required	integer	The unique ID of the Label.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/labels/{label-public-id}

PUT /api/v3/labels/{label-public-id} 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.

operationId: Label_updateNameById

Parameters

Name	In	Required	Type	Description
label-public-id	path	required	integer	The unique ID of the Label you wish to update.

Request Body

required

application/json

schema UpdateLabel

Property	Type	Required
name	string	optional
color	string	optional
archived	boolean	optional
description	string	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/labels/{label-public-id}

GET /api/v3/labels/{label-public-id}/stories List Label Stories

List all of the Stories with the Label.

operationId: Label_listStories

Parameters

Name	In	Required	Type	Description
label-public-id	path	required	integer	The unique ID of the Label.
includes_description	query	optional	boolean	A true/false boolean indicating whether to return Stories with their descriptions.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/labels/{label-public-id}/stories

Member 3 endpoints

GET /api/v3/member Get Current Member Info

Returns information about the authenticated member.

operationId: Member_getCurrentInfo

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/member

GET /api/v3/members List Members

Returns information about members of the Workspace.

operationId: Member_listWorkspaceMembers

Parameters

Name	In	Required	Type	Description
org-public-id	query	optional	string	The unique ID of the Organization to limit the list to.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/members

GET /api/v3/members/{member-public-id} Get Member

Returns information about a Member.

operationId: Member_getInfo

Parameters

Name	In	Required	Type	Description
member-public-id	path	required	string	The Member’s unique ID.
org-public-id	query	optional	string	The unique ID of the Organization to limit the lookup to.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/members/{member-public-id}

Milestone 5 endpoints

GET /api/v3/milestones List Milestones

List Milestones returns a list of all Milestones and their attributes.

operationId: Milestone_listAllAttributes

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/milestones

POST /api/v3/milestones Create Milestone

Create Milestone allows you to create a new Milestone in Shortcut.

operationId: Milestone_createNew

Request Body

required

application/json

schema CreateMilestone

Property	Type	Required
name	string	required
state	string	optional
categories	array	optional
└ name	string	required
└ color	string	optional
└ external_id	string	optional
description	string	optional
started_at_override	string	optional
completed_at_override	string	optional

Responses

201

Resource

400

Schema mismatch

403 —

404

Resource does not exist

422

Unprocessable

POST /api/v3/milestones

DELETE /api/v3/milestones/{milestone-public-id} Delete Milestone

Delete Milestone can be used to delete any Milestone.

operationId: Milestone_deleteMilestone

Parameters

Name	In	Required	Type	Description
milestone-public-id	path	required	integer	The ID of the Milestone.

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

DELETE /api/v3/milestones/{milestone-public-id}

GET /api/v3/milestones/{milestone-public-id} Get Milestone

Get Milestone returns information about a chosen Milestone.

operationId: Milestone_getInfo

Parameters

Name	In	Required	Type	Description
milestone-public-id	path	required	integer	The ID of the Milestone.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/milestones/{milestone-public-id}

PUT /api/v3/milestones/{milestone-public-id} Update Milestone

Update Milestone can be used to update Milestone properties.

operationId: Milestone_updateProperties

Parameters

Name	In	Required	Type	Description
milestone-public-id	path	required	integer	The ID of the Milestone.

Request Body

required

application/json

schema UpdateMilestone

Property	Type	Required
name	string	optional
state	string	optional
after_id	integer	optional
archived	boolean	optional
before_id	integer	optional
categories	array	optional
└ name	string	required
└ color	string	optional
└ external_id	string	optional
description	string	optional
started_at_override	string	optional
completed_at_override	string	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/milestones/{milestone-public-id}

Objective 5 endpoints

GET /api/v3/objectives List Objectives

List Objectives returns a list of all Objectives and their attributes.

operationId: Objective_listAll

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/objectives

POST /api/v3/objectives Create Objective

Create Objective allows you to create a new Objective in Shortcut.

operationId: Objective_createNewObjective

Request Body

required

application/json

schema CreateObjective

Property	Type	Required
name	string	required
state	string	optional
categories	array	optional
└ name	string	required
└ color	string	optional
└ external_id	string	optional
description	string	optional
started_at_override	string	optional
completed_at_override	string	optional

Responses

201

Resource

400

Schema mismatch

403 —

404

Resource does not exist

422

Unprocessable

POST /api/v3/objectives

DELETE /api/v3/objectives/{objective-public-id} Delete Objective

Delete Objective can be used to delete any Objective.

operationId: Objective_remove

Parameters

Name	In	Required	Type	Description
objective-public-id	path	required	integer	The ID of the Objective.

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

DELETE /api/v3/objectives/{objective-public-id}

GET /api/v3/objectives/{objective-public-id} Get Objective

Get Objective returns information about a chosen Objective.

operationId: Objective_getInfo

Parameters

Name	In	Required	Type	Description
objective-public-id	path	required	integer	The ID of the Objective.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/objectives/{objective-public-id}

PUT /api/v3/objectives/{objective-public-id} Update Objective

Update Objective can be used to update Objective properties.

operationId: Objective_updateProperties

Parameters

Name	In	Required	Type	Description
objective-public-id	path	required	integer	The ID of the Objective.

Request Body

required

application/json

schema UpdateObjective

Property	Type	Required
name	string	optional
state	string	optional
after_id	integer	optional
archived	boolean	optional
before_id	integer	optional
categories	array	optional
└ name	string	required
└ color	string	optional
└ external_id	string	optional
description	string	optional
started_at_override	string	optional
completed_at_override	string	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/objectives/{objective-public-id}

Project 6 endpoints

GET /api/v3/projects List Projects

List Projects returns a list of all Projects and their attributes.

operationId: Project_getAll

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/projects

POST /api/v3/projects Create Project

Create Project is used to create a new Shortcut Project.

operationId: Project_createShortcutProject

Request Body

required

application/json

schema CreateProject

Property	Type	Required
name	string	required
color	string	optional
team_id	integer	required
created_at	string	optional
start_time	string	optional
updated_at	string	optional
description	string	optional
external_id	string	optional
abbreviation	string	optional
follower_ids	array	optional
iteration_length	integer	optional

Responses

201

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

POST /api/v3/projects

DELETE /api/v3/projects/{project-public-id} 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.

operationId: Project_deleteProject

Parameters

Name	In	Required	Type	Description
project-public-id	path	required	integer	The unique ID of the Project.

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

DELETE /api/v3/projects/{project-public-id}

GET /api/v3/projects/{project-public-id} Get Project

Get Project returns information about the selected Project.

operationId: Project_getInformation

Parameters

Name	In	Required	Type	Description
project-public-id	path	required	integer	The unique ID of the Project.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/projects/{project-public-id}

PUT /api/v3/projects/{project-public-id} Update Project

Update Project can be used to change properties of a Project.

operationId: Project_updateProperties

Parameters

Name	In	Required	Type	Description
project-public-id	path	required	integer	The unique ID of the Project.

Request Body

required

application/json

schema UpdateProject

Property	Type	Required
name	string	optional
color	string	optional
team_id	integer	optional
archived	boolean	optional
description	string	optional
abbreviation	string	optional
follower_ids	array	optional
show_thermometer	boolean	optional
days_to_thermometer	integer	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/projects/{project-public-id}

GET /api/v3/projects/{project-public-id}/stories List Stories

List Stories returns a list of all Stories in a selected Project and their attributes.

operationId: Project_listStories

Parameters

Name	In	Required	Type	Description
project-public-id	path	required	integer	The unique ID of the Project.
includes_description	query	optional	boolean	A true/false boolean indicating whether to return Stories with their descriptions.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/projects/{project-public-id}/stories

Repository 2 endpoints

GET /api/v3/repositories List Repositories

List Repositories returns a list of all Repositories and their attributes.

operationId: Repository_listAll

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/repositories

GET /api/v3/repositories/{repo-public-id} Get Repository

Get Repository returns information about the selected Repository.

operationId: Repository_getInformation

Parameters

Name	In	Required	Type	Description
repo-public-id	path	required	integer	The unique ID of the Repository.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/repositories/{repo-public-id}

Search 6 endpoints

GET /api/v3/search 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.

operationId: Search_epicsAndStories

Parameters

Name	In	Required	Type	Description
query	query	required	string	See our help center article on search operators
page_size	query	optional	integer	The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail	query	optional	string	The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”.
next	query	optional	string	The next page token.
entity_types	query	optional	array	A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

200

Resource

400

Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded

404

Resource does not exist

422

Unprocessable

GET /api/v3/search

GET /api/v3/search/iterations Search Iterations

Search Iterations lets you search Iterations based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Iterations 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.

operationId: Search_iterations

Parameters

Name	In	Required	Type	Description
query	query	required	string	See our help center article on search operators
page_size	query	optional	integer	The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail	query	optional	string	The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”.
next	query	optional	string	The next page token.
entity_types	query	optional	array	A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

200

Resource

400

Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded

404

Resource does not exist

422

Unprocessable

GET /api/v3/search/iterations

GET /api/v3/search/milestones Search Milestones

Search Milestones lets you search Milestones based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Milestones 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.

operationId: Search_milestones

Parameters

Name	In	Required	Type	Description
query	query	required	string	See our help center article on search operators
page_size	query	optional	integer	The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail	query	optional	string	The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”.
next	query	optional	string	The next page token.
entity_types	query	optional	array	A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

200

Resource

400

Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded

404

Resource does not exist

422

Unprocessable

GET /api/v3/search/milestones

GET /api/v3/search/objectives Search Objectives

Search Objectives lets you search Objectives based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Objectives 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.

operationId: Search_objectives

Parameters

Name	In	Required	Type	Description
query	query	required	string	See our help center article on search operators
page_size	query	optional	integer	The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail	query	optional	string	The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”.
next	query	optional	string	The next page token.
entity_types	query	optional	array	A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

200

Resource

400

Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded

404

Resource does not exist

422

Unprocessable

GET /api/v3/search/objectives

GET /api/v3/search/stories 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.

operationId: Search_storiesGet

Parameters

Name	In	Required	Type	Description
query	query	required	string	See our help center article on search operators
page_size	query	optional	integer	The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail	query	optional	string	The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”.
next	query	optional	string	The next page token.
entity_types	query	optional	array	A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

200

Resource

400

Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded

404

Resource does not exist

422

Unprocessable

GET /api/v3/search/stories

POST /api/v3/stories/search Search Stories (Old)

Search Stories lets you search Stories based on desired parameters.

operationId: Search_storiesOld

Request Body

required

application/json

schema SearchStories

Property	Type	Required
epic_id	integer	optional
archived	boolean	optional
epic_ids	array	optional
estimate	integer	optional
group_id	string	optional
owner_id	string	optional
group_ids	array	optional
label_ids	array	optional
owner_ids	array	optional
label_name	string	optional
project_id	integer	optional
story_type	string	optional
external_id	string	optional
project_ids	array	optional
deadline_end	string	optional
iteration_id	integer	optional
iteration_ids	array	optional
created_at_end	string	optional
deadline_start	string	optional
updated_at_end	string	optional
…8 more	object	optional

Responses

201

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

POST /api/v3/stories/search

Story 10 endpoints

PUT /api/v3/entity-templates/disable Disable Story Templates

Disables the Story Template feature for the Workspace.

operationId: Story_disableTemplate

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/entity-templates/disable

PUT /api/v3/entity-templates/enable Enable Story Templates

Enables the Story Template feature for the Workspace.

operationId: Story_enableTemplateFeature

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/entity-templates/enable

POST /api/v3/stories Create Story

Create Story is used to add a new story to your Shortcut Workspace.

operationId: Story_addNew

Request Body

required

Request parameters for creating a story.

application/json

schema CreateStoryParams

Property	Type	Required
name	string	required
tasks	array	optional
└ complete	boolean	optional
└ owner_ids	array	optional
└ created_at	string	optional
└ updated_at	string	optional
└ description	string	required
└ external_id	string	optional
labels	array	optional
└ name	string	required
└ color	string	optional
└ description	string	optional
└ external_id	string	optional
epic_id	integer	optional
move_to	string	optional
archived	boolean	optional
comments	array	optional
└ text	string	required
└ author_id	string	optional
└ parent_id	integer	optional
└ created_at	string	optional
└ updated_at	string	optional
└ external_id	string	optional
deadline	string	optional
estimate	integer	optional
file_ids	array	optional
group_id	string	optional
owner_ids	array	optional
created_at	string	optional
project_id	integer	optional
story_type	string	optional
updated_at	string	optional
description	string	optional
external_id	string	optional
story_links	array	optional
└ verb	string	required
└ object_id	integer	optional
└ subject_id	integer	optional
follower_ids	array	optional
…9 more	object	optional

Responses

201

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

POST /api/v3/stories

DELETE /api/v3/stories/bulk Delete Multiple Stories

Delete Multiple Stories allows you to delete multiple archived stories at once.

operationId: Story_deleteMultiple

Request Body

required

application/json

schema DeleteStories

Property	Type	Required
story_ids	array	required

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

DELETE /api/v3/stories/bulk

POST /api/v3/stories/bulk Create Multiple Stories

Create Multiple Stories allows you to create multiple stories in a single request using the same syntax as Create Story.

operationId: Story_createMultiple

Request Body

required

application/json

schema CreateStories

Property	Type	Required
stories	array	required
└ name	string	required
└ tasks	array	optional
└ complete	boolean	optional
└ owner_ids	array	optional
└ created_at	string	optional
└ updated_at	string	optional
└ description	string	required
└ external_id	string	optional
└ labels	array	optional
└ name	string	required
└ color	string	optional
└ description	string	optional
└ external_id	string	optional
└ epic_id	integer	optional
└ move_to	string	optional
└ archived	boolean	optional
└ comments	array	optional
└ text	string	required
└ author_id	string	optional
└ parent_id	integer	optional
└ created_at	string	optional
└ updated_at	string	optional
└ external_id	string	optional
└ deadline	string	optional
└ estimate	integer	optional
└ file_ids	array	optional
└ group_id	string	optional
└ owner_ids	array	optional
└ created_at	string	optional
└ project_id	integer	optional
└ story_type	string	optional
└ updated_at	string	optional
└ description	string	optional
└ external_id	string	optional
└ story_links	array	optional
└ verb	string	required
└ object_id	integer	optional
└ subject_id	integer	optional
└ follower_ids	array	optional
└ …9 more	object	optional

Responses

201

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

POST /api/v3/stories/bulk

PUT /api/v3/stories/bulk Update Multiple Stories

Update Multiple Stories allows you to make changes to numerous stories at once.

operationId: Story_updateMultiple

Request Body

required

application/json

schema UpdateStories

Property	Type	Required
epic_id	integer	optional
move_to	string	optional
after_id	integer	optional
archived	boolean	optional
deadline	string	optional
estimate	integer	optional
group_id	string	optional
before_id	integer	optional
story_ids	array	required
labels_add	array	optional
└ name	string	required
└ color	string	optional
└ description	string	optional
└ external_id	string	optional
project_id	integer	optional
story_type	string	optional
iteration_id	integer	optional
labels_remove	array	optional
└ name	string	required
└ color	string	optional
└ description	string	optional
└ external_id	string	optional
owner_ids_add	array	optional
external_links	array	optional
requested_by_id	string	optional
follower_ids_add	array	optional
owner_ids_remove	array	optional
custom_fields_add	array	optional
└ value	string	optional
└ field_id	string	required
└ value_id	string	required
…3 more	object	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/stories/bulk

POST /api/v3/stories/from-template Create Story From Template

Create Story From Template is used to add a new story derived from a template to your Shortcut Workspace.

operationId: Story_createFromTemplate

Request Body

required

Request parameters for creating a story from a story template. These parameters are merged with the values derived from the template.

application/json

schema CreateStoryFromTemplateParams

Property	Type	Required
name	string	optional
tasks	array	optional
└ complete	boolean	optional
└ owner_ids	array	optional
└ created_at	string	optional
└ updated_at	string	optional
└ description	string	required
└ external_id	string	optional
labels	array	optional
└ name	string	required
└ color	string	optional
└ description	string	optional
└ external_id	string	optional
epic_id	integer	optional
move_to	string	optional
archived	boolean	optional
comments	array	optional
└ text	string	required
└ author_id	string	optional
└ parent_id	integer	optional
└ created_at	string	optional
└ updated_at	string	optional
└ external_id	string	optional
deadline	string	optional
estimate	integer	optional
file_ids	array	optional
group_id	string	optional
owner_ids	array	optional
created_at	string	optional
labels_add	array	optional
└ name	string	required
└ color	string	optional
└ description	string	optional
└ external_id	string	optional
project_id	integer	optional
story_type	string	optional
updated_at	string	optional
description	string	optional
external_id	string	optional
story_links	array	optional
└ verb	string	required
└ object_id	integer	optional
└ subject_id	integer	optional
…23 more	object	optional

Responses

201

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

POST /api/v3/stories/from-template

DELETE /api/v3/stories/{story-public-id} Delete Story

Delete Story can be used to delete any Story.

operationId: Story_remove

Parameters

Name	In	Required	Type	Description
story-public-id	path	required	integer	The ID of the Story.

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

DELETE /api/v3/stories/{story-public-id}

GET /api/v3/stories/{story-public-id} Get Story

Get Story returns information about a chosen Story.

operationId: Story_getInformation

Parameters

Name	In	Required	Type	Description
story-public-id	path	required	integer	The ID of the Story.

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

GET /api/v3/stories/{story-public-id}

PUT /api/v3/stories/{story-public-id} Update Story

Update Story can be used to update Story properties.

operationId: Story_updateProperties

Parameters

Name	In	Required	Type	Description
story-public-id	path	required	integer	The unique identifier of this story.

Request Body

required

application/json

schema UpdateStory

Property	Type	Required
name	string	optional
labels	array	optional
└ name	string	required
└ color	string	optional
└ description	string	optional
└ external_id	string	optional
epic_id	integer	optional
move_to	string	optional
after_id	integer	optional
archived	boolean	optional
deadline	string	optional
estimate	integer	optional
file_ids	array	optional
group_id	string	optional
before_id	integer	optional
owner_ids	array	optional
branch_ids	array	optional
commit_ids	array	optional
project_id	integer	optional
story_type	string	optional
description	string	optional
follower_ids	array	optional
iteration_id	integer	optional
custom_fields	array	optional
└ value	string	optional
└ field_id	string	required
└ value_id	string	required
…7 more	object	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/stories/{story-public-id}