Shortcut API

Project management for software teams

developer.shortcut.com ↗

Version

3.0

OpenAPI

3.0.0

Endpoints

123

Schemas

192

93

Quality

Updated

3 days ago

Project management project-management agile software

Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://api.app.shortcut.com

Endpoints

Clear filters

GET POST PUT PATCH DELETE

Category 1 endpoints

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

operationId: Category_updateName

Parameters

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

Request Body

required

application/json

schema UpdateCategory

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

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/categories/{category-public-id}

Customfield 1 endpoints

PUT /api/v3/custom-fields/{custom-field-public-id} Update Custom Field

Update Custom Field can be used to update the definition of a Custom Field. The order of items in the ‘values’ collection is interpreted to be their ascending sort order.To delete an existing enum value, simply omit it from the ‘values’ collection. New enum values may be created inline by including an object in the ‘values’ collection having a ‘value’ entry with no ‘id’ (eg. {‘value’: ‘myNewValue’, ‘color_key’: ‘green’}).

operationId: CustomField_updateDefinition

Parameters

Name	In	Required	Type	Description
custom-field-public-id	path	required	string	The unique ID of the CustomField.

Request Body

required

application/json

schema UpdateCustomField

Property	Type	Required
name	string	optional
values	array	optional
└ id	string	optional
└ value	string	optional
└ enabled	boolean	optional
└ color_key	string	optional
enabled	boolean	optional
after_id	string	optional
before_id	string	optional
description	string	optional
icon_set_identifier	string	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

409 —

422

Unprocessable

PUT /api/v3/custom-fields/{custom-field-public-id}

Epic 2 endpoints

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

operationId: Epic_updateDetails

Parameters

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

Request Body

required

application/json

schema UpdateEpic

Property	Type	Required
name	string	optional
state	string	optional
labels	array	optional
└ name	string	required
└ color	string	optional
└ description	string	optional
└ external_id	string	optional
after_id	integer	optional
archived	boolean	optional
deadline	string	optional
group_id	string	optional
before_id	integer	optional
group_ids	array	optional
owner_ids	array	optional
description	string	optional
external_id	string	optional
follower_ids	array	optional
milestone_id	integer	optional
epic_state_id	integer	optional
objective_ids	array	optional
requested_by_id	string	optional
planned_start_date	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/epics/{epic-public-id}

PUT /api/v3/epics/{epic-public-id}/comments/{comment-public-id} Update Epic Comment

This endpoint allows you to update a threaded Comment on an Epic.

operationId: Epic_updateComment

Parameters

Name	In	Required	Type	Description
epic-public-id	path	required	integer	The ID of the associated Epic.
comment-public-id	path	required	integer	The ID of the Comment.

Request Body

required

application/json

schema UpdateComment

Property	Type	Required
text	string	required

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/epics/{epic-public-id}/comments/{comment-public-id}

File 2 endpoints

PUT /api/v3/files/{file-public-id} Update File

Update File updates the properties of an UploadedFile (but not its content).

operationId: File_updateProperties

Parameters

Name	In	Required	Type	Description
file-public-id	path	required	integer	The unique ID assigned to the file in Shortcut.

Request Body

required

application/json

schema UpdateFile

Property	Type	Required
name	string	optional
created_at	string	optional
updated_at	string	optional
description	string	optional
external_id	string	optional
uploader_id	string	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/files/{file-public-id}

PUT /api/v3/linked-files/{linked-file-public-id} Update Linked File

Updated Linked File allows you to update properties of a previously attached Linked-File.

operationId: File_updateLinkedFile

Parameters

Name	In	Required	Type	Description
linked-file-public-id	path	required	integer	The unique identifier of the linked file.

Request Body

required

application/json

schema UpdateLinkedFile

Property	Type	Required
url	string	optional
name	string	optional
size	integer	optional
type	string	optional
story_id	integer	optional
description	string	optional
uploader_id	string	optional
thumbnail_url	string	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/linked-files/{linked-file-public-id}

Group 3 endpoints

PUT /api/v3/groups/disable Disable Groups

Disables Groups for the current workspace2

operationId: Group_disableWorkspace

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/groups/disable

PUT /api/v3/groups/enable Enable Groups

Enables Groups for the current workspace2

operationId: Group_enableWorkspace

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/groups/enable

PUT /api/v3/groups/{group-public-id} Update Group

operationId: Group_updateGroupById

Parameters

Name	In	Required	Type	Description
group-public-id	path	required	string	The unique ID of the Group.

Request Body

required

application/json

schema UpdateGroup

Property	Type	Required
name	string	optional
color	string	optional
archived	boolean	optional
color_key	string	optional
member_ids	array	optional
description	string	optional
mention_name	string	optional
workflow_ids	array	optional
display_icon_id	string	optional

Responses

200

Resource

400

Schema mismatch

403 —

404

Resource does not exist

422

Unprocessable

PUT /api/v3/groups/{group-public-id}

Iteration 3 endpoints

PUT /api/v3/iterations/disable Disable Iterations

Disables Iterations for the current workspace

operationId: Iteration_disableIterations

Responses

204

No Content

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/iterations/disable

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

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}

Keyresult 1 endpoints

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 1 endpoints

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}

Milestone 1 endpoints

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 1 endpoints

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 1 endpoints

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}

Story 7 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

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

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}

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

Update Comment replaces the text of the existing Comment.

operationId: Story_updateCommentText

Parameters

Name	In	Required	Type	Description
story-public-id	path	required	integer	The ID of the Story that the Comment is in.
comment-public-id	path	required	integer	The ID of the Comment

Request Body

required

application/json

schema UpdateStoryComment

Property	Type	Required
text	string	required

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

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

PUT /api/v3/stories/{story-public-id}/tasks/{task-public-id} Update Task

Update Task can be used to update Task properties.

operationId: Story_updateTask

Parameters

Name	In	Required	Type	Description
story-public-id	path	required	integer	The unique identifier of the parent Story.
task-public-id	path	required	integer	The unique identifier of the Task you wish to update.

Request Body

required

application/json

schema UpdateTask

Property	Type	Required
after_id	integer	optional
complete	boolean	optional
before_id	integer	optional
owner_ids	array	optional
description	string	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

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

PUT /api/v3/story-links/{story-link-public-id} Update Story Link

Updates the stories and/or the relationship for the given Story Link.

operationId: Story_updateLinkRelationship

Parameters

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

Request Body

required

application/json

schema UpdateStoryLink

Property	Type	Required
verb	string	optional
object_id	integer	optional
subject_id	integer	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/story-links/{story-link-public-id}

Template 1 endpoints

PUT /api/v3/entity-templates/{entity-template-public-id} Update Entity Template

Update an entity template’s name or its contents.

operationId: Template_updateContents

Parameters

Name	In	Required	Type	Description
entity-template-public-id	path	required	string	The unique ID of the template to be updated.

Request Body

required

Request parameters for changing either a template’s name or any of
the attributes it is designed to pre-populate.

application/json

schema UpdateEntityTemplate

Property	Type	Required
name	string	optional
story_contents	object	optional
└ name	string	optional
└ tasks	array	optional
└ complete	boolean	optional
└ owner_ids	array	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
└ deadline	string	optional
└ estimate	integer	optional
└ file_ids	array	optional
└ group_id	string	optional
└ owner_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
└ external_links	array	optional
└ linked_file_ids	array	optional
└ workflow_state_id	integer	optional

Responses

200

Resource

400

Schema mismatch

404

Resource does not exist

422

Unprocessable

PUT /api/v3/entity-templates/{entity-template-public-id}

Load more endpoints

Schemas

object BaseTaskParams

{
  "type": "object",
  "required": [
    "description"
  ],
  "properties": {
    "complete": {
      "type": "boolean",
      "description": "True/false boolean indicating whether the Task is completed. Defaults to false."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any members you want to add as Owners on this new Task."
    },
    "description": {
      "type": "string",
      "maxLength": 2048,
      "minLength": 1,
      "description": "The Task description."
    },
    "external_id": {
      "type": "string",
      "description": "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."
    }
  },
  "description": "Request parameters for specifying how to pre-populate a task through a template."
}

object BasicWorkspaceInfo

{
  "type": "object",
  "required": [
    "url_slug",
    "estimate_scale"
  ],
  "properties": {
    "url_slug": {
      "type": "string"
    },
    "estimate_scale": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      }
    }
  }
}

object Branch

{
  "type": "object",
  "required": [
    "entity_type",
    "deleted",
    "name",
    "persistent",
    "updated_at",
    "pull_requests",
    "merged_branch_ids",
    "id",
    "url",
    "repository_id",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The unique ID of the Branch."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Branch."
    },
    "name": {
      "type": "string",
      "description": "The name of the Branch."
    },
    "deleted": {
      "type": "boolean",
      "description": "A true/false boolean indicating if the Branch has been deleted."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Branch was created."
    },
    "persistent": {
      "type": "boolean",
      "description": "A true/false boolean indicating if the Branch is persistent; e.g. master."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Branch was updated."
    },
    "entity_type": {
      "type": "string",
      "description": "A string description of this resource."
    },
    "pull_requests": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PullRequest"
      },
      "description": "An array of PullRequests attached to the Branch (there is usually only one)."
    },
    "repository_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the Repository that contains the Branch."
    },
    "merged_branch_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "The IDs of the Branches the Branch has been merged into."
    }
  },
  "description": "Branch refers to a VCS branch. Branches are feature branches associated with Shortcut Stories."
}

object Category

{
  "type": "object",
  "required": [
    "archived",
    "entity_type",
    "color",
    "name",
    "global_id",
    "type",
    "updated_at",
    "external_id",
    "id",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "description": "The unique ID of the Category."
    },
    "name": {
      "type": "string",
      "description": "The name of the Category."
    },
    "type": {
      "type": "string",
      "x-doc-skip": true,
      "description": "The type of entity this Category is associated with; currently Milestone or Objective is the only type of Category."
    },
    "color": {
      "type": "string",
      "format": "css-color",
      "pattern": "^#[a-fA-F0-9]{6}$",
      "nullable": true,
      "minLength": 1,
      "description": "The hex color to be displayed with the Category (for example, \"#ff0000\")."
    },
    "archived": {
      "type": "boolean",
      "description": "A true/false boolean indicating if the Category has been archived."
    },
    "global_id": {
      "type": "string",
      "x-doc-skip": true,
      "description": "The Global ID of the Category."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date that the Category was created."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date that the Category was updated."
    },
    "entity_type": {
      "type": "string",
      "description": "A string description of this resource."
    },
    "external_id": {
      "type": "string",
      "nullable": true,
      "description": "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."
    }
  },
  "description": "A Category can be used to associate Objectives."
}

array CategoryListAllResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Category"
  }
}

array CategoryListMilestonesResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Milestone"
  }
}

array CategoryListObjectivesResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Milestone"
  }
}

object Commit

{
  "type": "object",
  "required": [
    "entity_type",
    "author_id",
    "hash",
    "updated_at",
    "id",
    "url",
    "author_email",
    "timestamp",
    "author_identity",
    "repository_id",
    "created_at",
    "message"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The unique ID of the Commit."
    },
    "url": {
      "type": "string",
      "description": "The URL of the Commit."
    },
    "hash": {
      "type": "string",
      "description": "The Commit hash."
    },
    "message": {
      "type": "string",
      "description": "The Commit message."
    },
    "author_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The ID of the Member that authored the Commit, if known."
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date the Commit was pushed."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date the Commit was created."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Commit was updated."
    },
    "entity_type": {
      "type": "string",
      "description": "A string description of this resource."
    },
    "author_email": {
      "type": "string",
      "description": "The email address of the VCS user that authored the Commit."
    },
    "repository_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the Repository that contains the Commit."
    },
    "author_identity": {
      "$ref": "#/components/schemas/Identity"
    }
  },
  "description": "Commit refers to a VCS commit and all associated details."
}

object CreateCategory

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "The name of the new Category."
    },
    "type": {
      "x-doc-skip": true,
      "description": "The type of entity this Category is associated with; currently Milestone or Objective is the only type of Category."
    },
    "color": {
      "type": "string",
      "format": "css-color",
      "pattern": "^#[a-fA-F0-9]{6}$",
      "minLength": 1,
      "description": "The hex color to be displayed with the Category (for example, \"#ff0000\")."
    },
    "external_id": {
      "type": "string",
      "minLength": 1,
      "description": "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."
    }
  },
  "x-doc-skip": true
}

object CreateCategoryParams

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "The name of the new Category."
    },
    "color": {
      "type": "string",
      "format": "css-color",
      "pattern": "^#[a-fA-F0-9]{6}$",
      "minLength": 1,
      "description": "The hex color to be displayed with the Category (for example, \"#ff0000\")."
    },
    "external_id": {
      "type": "string",
      "minLength": 1,
      "description": "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."
    }
  },
  "description": "Request parameters for creating a Category with a Objective."
}

object CreateCommentComment

{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 100000,
      "minLength": 1,
      "description": "The comment text."
    },
    "author_id": {
      "type": "string",
      "format": "uuid",
      "description": "The Member ID of the Comment's author. Defaults to the user identified by the API token."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the comment is created, but can be set to reflect another date."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the comment is last updated, but can be set to reflect another date."
    },
    "external_id": {
      "type": "string",
      "description": "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."
    }
  },
  "x-doc-skip": true
}

object CreateEntityTemplate

{
  "type": "object",
  "required": [
    "name",
    "story_contents"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "The name of the new entity template"
    },
    "author_id": {
      "type": "string",
      "format": "uuid",
      "description": "The id of the user creating this template."
    },
    "story_contents": {
      "$ref": "#/components/schemas/CreateStoryContents"
    }
  },
  "description": "Request paramaters for creating an entirely new entity template."
}

object CreateEpic

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1,
      "description": "The Epic's name."
    },
    "state": {
      "enum": [
        "in progress",
        "to do",
        "done"
      ],
      "type": "string",
      "description": "`Deprecated` The Epic's state (to do, in progress, or done); will be ignored when `epic_state_id` is set."
    },
    "labels": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateLabelParams"
      },
      "description": "An array of Labels attached to the Epic."
    },
    "deadline": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The Epic's deadline."
    },
    "group_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "`Deprecated` The ID of the group to associate with the epic. Use `group_ids`."
    },
    "group_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDS for Groups to which this Epic is related."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any members you want to add as Owners on this new Epic."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date it is created but can be set to reflect another date."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date it is created but can be set to reflect another date."
    },
    "description": {
      "type": "string",
      "maxLength": 100000,
      "description": "The Epic's description."
    },
    "external_id": {
      "type": "string",
      "description": "This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here."
    },
    "follower_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any Members you want to add as Followers on this new Epic."
    },
    "milestone_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "`Deprecated` The ID of the Milestone this Epic is related to. Use `objective_ids`."
    },
    "epic_state_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the Epic State."
    },
    "objective_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs for Objectives to which this Epic is related."
    },
    "requested_by_id": {
      "type": "string",
      "format": "uuid",
      "description": "The ID of the member that requested the epic."
    },
    "planned_start_date": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The Epic's planned start date."
    },
    "started_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Epic was started."
    },
    "completed_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Epic was completed."
    }
  },
  "x-doc-skip": true
}

object CreateEpicComment

{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 100000,
      "minLength": 1,
      "description": "The comment text."
    },
    "author_id": {
      "type": "string",
      "format": "uuid",
      "description": "The Member ID of the Comment's author. Defaults to the user identified by the API token."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the comment is created, but can be set to reflect another date."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the comment is last updated, but can be set to reflect another date."
    },
    "external_id": {
      "type": "string",
      "description": "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."
    }
  },
  "x-doc-skip": true
}

object CreateGroup

{
  "type": "object",
  "required": [
    "name",
    "mention_name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 63,
      "minLength": 1,
      "description": "The name of this Group."
    },
    "color": {
      "type": "string",
      "format": "css-color",
      "pattern": "^#[a-fA-F0-9]{6}$",
      "minLength": 1,
      "description": "The color you wish to use for the Group in the system."
    },
    "color_key": {
      "enum": [
        "blue",
        "purple",
        "midnight-blue",
        "orange",
        "yellow-green",
        "brass",
        "gray",
        "fuchsia",
        "yellow",
        "pink",
        "sky-blue",
        "green",
        "red",
        "black",
        "slate",
        "turquoise"
      ],
      "type": "string",
      "description": "The color key you wish to use for the Group in the system."
    },
    "member_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "The Member ids to add to this Group.",
      "uniqueItems": true
    },
    "description": {
      "type": "string",
      "description": "The description of the Group."
    },
    "mention_name": {
      "type": "string",
      "maxLength": 63,
      "minLength": 1,
      "description": "The mention name of this Group."
    },
    "workflow_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "The Workflow ids to add to the Group."
    },
    "display_icon_id": {
      "type": "string",
      "format": "uuid",
      "description": "The Icon id for the avatar of this Group."
    }
  }
}

object CreateIteration

{
  "type": "object",
  "required": [
    "name",
    "start_date",
    "end_date"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1,
      "description": "The name of this Iteration."
    },
    "labels": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateLabelParams"
      },
      "description": "An array of Labels attached to the Iteration."
    },
    "end_date": {
      "type": "string",
      "minLength": 1,
      "description": "The date this Iteration ends, e.g. 2019-07-01."
    },
    "group_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI."
    },
    "start_date": {
      "type": "string",
      "minLength": 1,
      "description": "The date this Iteration begins, e.g. 2019-07-01."
    },
    "description": {
      "type": "string",
      "maxLength": 100000,
      "description": "The description of the Iteration."
    },
    "follower_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any Members you want to add as Followers."
    }
  }
}

object CreateLabelParams

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 128,
      "minLength": 1,
      "description": "The name of the new Label."
    },
    "color": {
      "type": "string",
      "format": "css-color",
      "pattern": "^#[a-fA-F0-9]{6}$",
      "minLength": 1,
      "description": "The hex color to be displayed with the Label (for example, \"#ff0000\")."
    },
    "description": {
      "type": "string",
      "description": "The description of the new Label."
    },
    "external_id": {
      "type": "string",
      "minLength": 1,
      "description": "This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here."
    }
  },
  "description": "Request parameters for creating a Label on a Shortcut Story."
}

object CreateLinkedFile

{
  "type": "object",
  "required": [
    "name",
    "type",
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "pattern": "^https?://.+$",
      "maxLength": 2048,
      "description": "The URL of linked file."
    },
    "name": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1,
      "description": "The name of the file."
    },
    "size": {
      "type": "integer",
      "format": "int64",
      "description": "The filesize, if the integration provided it."
    },
    "type": {
      "enum": [
        "google",
        "url",
        "dropbox",
        "box",
        "onedrive"
      ],
      "type": "string",
      "description": "The integration type of the file (e.g. google, dropbox, box)."
    },
    "story_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the linked story."
    },
    "description": {
      "type": "string",
      "description": "The description of the file."
    },
    "uploader_id": {
      "type": "string",
      "format": "uuid",
      "description": "The UUID of the member that uploaded the file."
    },
    "content_type": {
      "type": "string",
      "description": "The content type of the image (e.g. txt/plain)."
    },
    "thumbnail_url": {
      "type": "string",
      "pattern": "^https?://.+$",
      "maxLength": 2048,
      "description": "The URL of the thumbnail, if the integration provided it."
    }
  },
  "x-doc-skip": true
}

object CreateMilestone

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1,
      "description": "The name of the Milestone."
    },
    "state": {
      "enum": [
        "in progress",
        "to do",
        "done"
      ],
      "type": "string",
      "description": "The workflow state that the Milestone is in."
    },
    "categories": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateCategoryParams"
      },
      "description": "An array of IDs of Categories attached to the Milestone."
    },
    "description": {
      "type": "string",
      "maxLength": 100000,
      "description": "The Milestone's description."
    },
    "started_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Milestone was started."
    },
    "completed_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Milestone was completed."
    }
  },
  "x-doc-skip": true
}

object CreateObjective

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1,
      "description": "The name of the Objective."
    },
    "state": {
      "enum": [
        "in progress",
        "to do",
        "done"
      ],
      "type": "string",
      "description": "The workflow state that the Objective is in."
    },
    "categories": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateCategoryParams"
      },
      "description": "An array of IDs of Categories attached to the Objective."
    },
    "description": {
      "type": "string",
      "maxLength": 100000,
      "description": "The Objective's description."
    },
    "started_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Objective was started."
    },
    "completed_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Objective was completed."
    }
  },
  "x-doc-skip": true
}

object CreateOrDeleteStoryReaction

{
  "type": "object",
  "required": [
    "emoji"
  ],
  "properties": {
    "emoji": {
      "type": "string",
      "description": "The emoji short-code to add / remove. E.g. `:thumbsup::skin-tone-4:`."
    }
  },
  "x-doc-skip": true
}

object CreateProject

{
  "type": "object",
  "required": [
    "name",
    "team_id"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 128,
      "minLength": 1,
      "description": "The name of the Project."
    },
    "color": {
      "type": "string",
      "format": "css-color",
      "pattern": "^#[a-fA-F0-9]{6}$",
      "minLength": 1,
      "description": "The color you wish to use for the Project in the system."
    },
    "team_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the team the project belongs to."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date it is created but can be set to reflect another date."
    },
    "start_time": {
      "type": "string",
      "format": "date-time",
      "description": "The date at which the Project was started."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date it is created but can be set to reflect another date."
    },
    "description": {
      "type": "string",
      "maxLength": 100000,
      "description": "The Project description."
    },
    "external_id": {
      "type": "string",
      "description": "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."
    },
    "abbreviation": {
      "type": "string",
      "description": "The Project abbreviation used in Story summaries. Should be kept to 3 characters at most."
    },
    "follower_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any members you want to add as Owners on this new Epic."
    },
    "iteration_length": {
      "type": "integer",
      "format": "int64",
      "description": "The number of weeks per iteration in this Project."
    }
  },
  "x-doc-skip": true
}

object CreateStories

{
  "type": "object",
  "required": [
    "stories"
  ],
  "properties": {
    "stories": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateStoryParams"
      },
      "description": "An array of stories to be created."
    }
  },
  "x-doc-skip": true
}

object CreateStoryComment

{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 100000,
      "description": "The comment text."
    },
    "author_id": {
      "type": "string",
      "format": "uuid",
      "description": "The Member ID of the Comment's author. Defaults to the user identified by the API token."
    },
    "parent_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the Comment that this comment is threaded under."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the comment is created, but can be set to reflect another date."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the comment is last updated, but can be set to reflect another date."
    },
    "external_id": {
      "type": "string",
      "description": "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."
    }
  },
  "x-doc-skip": true
}

object CreateStoryCommentParams

{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 100000,
      "description": "The comment text."
    },
    "author_id": {
      "type": "string",
      "format": "uuid",
      "description": "The Member ID of the Comment's author. Defaults to the user identified by the API token."
    },
    "parent_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the Comment that this comment is threaded under."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the comment is created, but can be set to reflect another date."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the comment is last updated, but can be set to reflect another date."
    },
    "external_id": {
      "type": "string",
      "description": "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."
    }
  },
  "description": "Request parameters for creating a Comment on a Shortcut Story."
}

object CreateStoryContents

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the story."
    },
    "tasks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BaseTaskParams"
      },
      "description": "An array of tasks to be populated by the template."
    },
    "labels": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateLabelParams"
      },
      "description": "An array of labels to be populated by the template."
    },
    "epic_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the epic the to be populated."
    },
    "deadline": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The due date of the story."
    },
    "estimate": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The numeric point estimate to be populated."
    },
    "file_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of the attached file IDs to be populated.",
      "uniqueItems": true
    },
    "group_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The ID of the group to be populated."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs of the owners of this story."
    },
    "project_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the project the story belongs to."
    },
    "story_type": {
      "type": "string",
      "description": "The type of story (feature, bug, chore)."
    },
    "description": {
      "type": "string",
      "description": "The description of the story."
    },
    "follower_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any Members listed as Followers."
    },
    "iteration_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the iteration the to be populated."
    },
    "custom_fields": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CustomFieldValueParams"
      },
      "description": "An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField."
    },
    "external_links": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of external links to be populated."
    },
    "linked_file_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of the linked file IDs to be populated.",
      "uniqueItems": true
    },
    "workflow_state_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the workflow state to be populated."
    }
  },
  "description": "A map of story attributes this template populates."
}

object CreateStoryFromTemplateParams

{
  "type": "object",
  "required": [
    "story_template_id"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 512,
      "minLength": 1,
      "description": "The name of the story. Must be provided if the template does not provide a name."
    },
    "tasks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateTaskParams"
      },
      "description": "An array of tasks connected to the story."
    },
    "labels": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateLabelParams"
      },
      "description": "An array of labels attached to the story."
    },
    "epic_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the epic the story belongs to."
    },
    "move_to": {
      "enum": [
        "last",
        "first"
      ],
      "type": "string",
      "description": "One of \"first\" or \"last\". This can be used to move the given story to the first or last position in the workflow state."
    },
    "archived": {
      "type": "boolean",
      "description": "Controls the story's archived state."
    },
    "comments": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateStoryCommentParams"
      },
      "description": "An array of comments to add to the story."
    },
    "deadline": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The due date of the story."
    },
    "estimate": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The numeric point estimate of the story. Can also be null, which means unestimated."
    },
    "file_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs of files attached to the story.",
      "uniqueItems": true
    },
    "group_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The id of the group to associate with this story."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs of the owners of this story.",
      "uniqueItems": true
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date the Story was created."
    },
    "labels_add": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateLabelParams"
      },
      "description": "An array of labels attached to the story in addition to the labels provided by the template. Cannot be used in conjunction with `labels`.",
      "uniqueItems": true
    },
    "project_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the project the story belongs to."
    },
    "story_type": {
      "enum": [
        "feature",
        "chore",
        "bug"
      ],
      "type": "string",
      "description": "The type of story (feature, bug, chore)."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date the Story was updated."
    },
    "description": {
      "type": "string",
      "maxLength": 100000,
      "description": "The description of the story."
    },
    "external_id": {
      "type": "string",
      "description": "This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here."
    },
    "story_links": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateStoryLinkParams"
      },
      "description": "An array of story links attached to the story."
    },
    "file_ids_add": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs of files attached to the story in addition to files from the template. Cannot be used in conjunction with `file_ids`.",
      "uniqueItems": true
    },
    "follower_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs of the followers of this story.",
      "uniqueItems": true
    },
    "iteration_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the iteration the story belongs to."
    },
    "custom_fields": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CustomFieldValueParams"
      },
      "description": "A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField."
    },
    "labels_remove": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/RemoveLabelParams"
      },
      "description": "An array of labels to remove from the labels provided by the template. Cannot be used in conjunction with `labels`.",
      "uniqueItems": true
    },
    "owner_ids_add": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "The UUIDs of the new owners to be added in addition to owners from the template. Cannot be used in conjunction with `owners`.",
      "uniqueItems": true
    },
    "external_links": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of External Links associated with this story."
    },
    "file_ids_remove": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs of files removed from files from the template. Cannot be used in conjunction with `file_ids`.",
      "uniqueItems": true
    },
    "linked_file_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs of linked files attached to the story.",
      "uniqueItems": true
    },
    "requested_by_id": {
      "type": "string",
      "format": "uuid",
      "description": "The ID of the member that requested the story."
    },
    "follower_ids_add": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "The UUIDs of the new followers to be added in addition to followers from the template. Cannot be used in conjunction with `follower_ids.`",
      "uniqueItems": true
    },
    "owner_ids_remove": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "The UUIDs of the new owners to be removed from owners from the template. Cannot be used in conjunction with `owners`.",
      "uniqueItems": true
    },
    "custom_fields_add": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CustomFieldValueParams"
      },
      "description": "A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. These will be added to any fields provided by the template. Cannot be used in conjunction with `custom_fields`.",
      "uniqueItems": true
    },
    "story_template_id": {
      "type": "string",
      "format": "uuid",
      "description": "The id of the story template used to create this story."
    },
    "workflow_state_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the workflow state the story will be in."
    },
    "external_links_add": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of External Links associated with this story. These will be added to any links provided by the template. Cannot be used in conjunction with `external_links`.",
      "uniqueItems": true
    },
    "follower_ids_remove": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "The UUIDs of the new followers to be removed from followers from the template. Cannot be used in conjunction with `follower_ids`.",
      "uniqueItems": true
    },
    "linked_file_ids_add": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs of linked files attached to the story in addition to files from the template. Cannot be used in conjunction with `linked_files`.",
      "uniqueItems": true
    },
    "started_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Story was started."
    },
    "custom_fields_remove": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/RemoveCustomFieldParams"
      },
      "description": "A map specifying a CustomField ID. These will be removed from any fields provided by the template. Cannot be used in conjunction with `custom_fields`.",
      "uniqueItems": true
    },
    "completed_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Story was completed."
    },
    "external_links_remove": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of External Links associated with this story. These will be removed from any links provided by the template. Cannot be used in conjunction with `external_links`.",
      "uniqueItems": true
    },
    "linked_file_ids_remove": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs of linked files removed from files from the template. Cannot be used in conjunction with `linked_files.`",
      "uniqueItems": true
    }
  },
  "description": "Request parameters for creating a story from a story template. These parameters are merged with the values derived from the template."
}

object CreateStoryLink

{
  "type": "object",
  "required": [
    "verb",
    "subject_id",
    "object_id"
  ],
  "properties": {
    "verb": {
      "enum": [
        "blocks",
        "duplicates",
        "relates to"
      ],
      "type": "string",
      "description": "The type of link."
    },
    "object_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the object Story."
    },
    "subject_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the subject Story."
    }
  },
  "x-doc-skip": true
}

object CreateStoryLinkParams

{
  "type": "object",
  "required": [
    "verb"
  ],
  "properties": {
    "verb": {
      "enum": [
        "blocks",
        "duplicates",
        "relates to"
      ],
      "type": "string",
      "description": "How the subject Story acts on the object Story. This can be \"blocks\", \"duplicates\", or \"relates to\"."
    },
    "object_id": {
      "type": "integer",
      "format": "int64",
      "description": "The unique ID of the Story defined as object."
    },
    "subject_id": {
      "type": "integer",
      "format": "int64",
      "description": "The unique ID of the Story defined as subject."
    }
  },
  "description": "Request parameters for creating a Story Link within a Story."
}

object CreateStoryParams

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 512,
      "minLength": 1,
      "description": "The name of the story."
    },
    "tasks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateTaskParams"
      },
      "description": "An array of tasks connected to the story."
    },
    "labels": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateLabelParams"
      },
      "description": "An array of labels attached to the story."
    },
    "epic_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the epic the story belongs to."
    },
    "move_to": {
      "enum": [
        "last",
        "first"
      ],
      "type": "string",
      "description": "One of \"first\" or \"last\". This can be used to move the given story to the first or last position in the workflow state."
    },
    "archived": {
      "type": "boolean",
      "description": "Controls the story's archived state."
    },
    "comments": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateStoryCommentParams"
      },
      "description": "An array of comments to add to the story."
    },
    "deadline": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The due date of the story."
    },
    "estimate": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The numeric point estimate of the story. Can also be null, which means unestimated."
    },
    "file_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs of files attached to the story.",
      "uniqueItems": true
    },
    "group_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The id of the group to associate with this story."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs of the owners of this story.",
      "uniqueItems": true
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date the Story was created."
    },
    "project_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the project the story belongs to."
    },
    "story_type": {
      "enum": [
        "feature",
        "chore",
        "bug"
      ],
      "type": "string",
      "description": "The type of story (feature, bug, chore)."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date the Story was updated."
    },
    "description": {
      "type": "string",
      "maxLength": 100000,
      "description": "The description of the story."
    },
    "external_id": {
      "type": "string",
      "description": "This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here."
    },
    "story_links": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateStoryLinkParams"
      },
      "description": "An array of story links attached to the story."
    },
    "follower_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs of the followers of this story.",
      "uniqueItems": true
    },
    "iteration_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "The ID of the iteration the story belongs to."
    },
    "custom_fields": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CustomFieldValueParams"
      },
      "description": "A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField."
    },
    "external_links": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of External Links associated with this story."
    },
    "linked_file_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs of linked files attached to the story.",
      "uniqueItems": true
    },
    "requested_by_id": {
      "type": "string",
      "format": "uuid",
      "description": "The ID of the member that requested the story."
    },
    "story_template_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The id of the story template used to create this story, if applicable. This is just an association; no content from the story template is inherited by the story simply by setting this field."
    },
    "workflow_state_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the workflow state the story will be in."
    },
    "started_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Story was started."
    },
    "completed_at_override": {
      "type": "string",
      "format": "date-time",
      "description": "A manual override for the time/date the Story was completed."
    }
  },
  "description": "Request parameters for creating a story."
}

object CreateTask

{
  "type": "object",
  "required": [
    "description"
  ],
  "properties": {
    "complete": {
      "type": "boolean",
      "description": "True/false boolean indicating whether the Task is completed. Defaults to false."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any members you want to add as Owners on this new Task."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the Task is created but can be set to reflect another creation time/date."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date."
    },
    "description": {
      "type": "string",
      "maxLength": 2048,
      "minLength": 1,
      "description": "The Task description."
    },
    "external_id": {
      "type": "string",
      "description": "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."
    }
  },
  "x-doc-skip": true
}

object CreateTaskParams

{
  "type": "object",
  "required": [
    "description"
  ],
  "properties": {
    "complete": {
      "type": "boolean",
      "description": "True/false boolean indicating whether the Task is completed. Defaults to false."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any members you want to add as Owners on this new Task."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the Task is created but can be set to reflect another creation time/date."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date."
    },
    "description": {
      "type": "string",
      "maxLength": 2048,
      "minLength": 1,
      "description": "The Task description."
    },
    "external_id": {
      "type": "string",
      "description": "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."
    }
  },
  "description": "Request parameters for creating a Task on a Story."
}

object CustomField

{
  "type": "object",
  "required": [
    "entity_type",
    "name",
    "updated_at",
    "id",
    "field_type",
    "position",
    "enabled",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The unique public ID for the CustomField."
    },
    "name": {
      "type": "string",
      "maxLength": 63,
      "minLength": 1,
      "description": "The name of the Custom Field."
    },
    "values": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CustomFieldEnumValue"
      },
      "description": "A collection of legal values for a CustomField."
    },
    "enabled": {
      "type": "boolean",
      "description": "When true, the CustomField can be applied to entities in the Workspace."
    },
    "position": {
      "type": "integer",
      "format": "int64",
      "description": "An integer indicating the position of this Custom Field with respect to the other CustomField"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The instant when this CustomField was created."
    },
    "field_type": {
      "enum": [
        "enum"
      ],
      "type": "string",
      "description": "The type of Custom Field, eg. 'enum'."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "The instant when this CustomField was last updated."
    },
    "description": {
      "type": "string",
      "maxLength": 512,
      "minLength": 1,
      "description": "A string description of the CustomField"
    },
    "entity_type": {
      "enum": [
        "custom-field"
      ],
      "type": "string",
      "description": "A string description of this resource."
    },
    "story_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "x-doc-skip": true,
      "description": "The types of stories this CustomField is scoped to."
    },
    "canonical_name": {
      "type": "string",
      "description": "The canonical name for a Shortcut-defined field."
    },
    "fixed_position": {
      "type": "boolean",
      "x-doc-skip": true,
      "description": "When true, the CustomFieldEnumValues may not be reordered."
    },
    "icon_set_identifier": {
      "type": "string",
      "maxLength": 63,
      "minLength": 1,
      "description": "A string that represents the icon that corresponds to this custom field."
    }
  }
}

object CustomFieldEnumValue

{
  "type": "object",
  "required": [
    "id",
    "value",
    "position",
    "color_key",
    "entity_type",
    "enabled"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The unique public ID for the Custom Field."
    },
    "value": {
      "type": "string",
      "maxLength": 63,
      "minLength": 1,
      "description": "A string value within the domain of this Custom Field."
    },
    "enabled": {
      "type": "boolean",
      "x-doc-skip": true,
      "description": "When true, the CustomFieldEnumValue can be selected for the CustomField."
    },
    "position": {
      "type": "integer",
      "format": "int64",
      "description": "An integer indicating the position of this Value with respect to the other CustomFieldEnumValues in the enumeration."
    },
    "color_key": {
      "type": "string",
      "nullable": true,
      "description": "A color key associated with this CustomFieldEnumValue."
    },
    "entity_type": {
      "enum": [
        "custom-field-enum-value"
      ],
      "type": "string",
      "description": "A string description of this resource."
    }
  }
}

array CustomFieldListResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/CustomField"
  }
}

object CustomFieldValueParams

{
  "type": "object",
  "required": [
    "field_id",
    "value_id"
  ],
  "properties": {
    "value": {
      "type": "string",
      "description": "A literal value for the CustomField. Currently ignored."
    },
    "field_id": {
      "type": "string",
      "format": "uuid",
      "description": "The unique public ID for the CustomField."
    },
    "value_id": {
      "type": "string",
      "format": "uuid",
      "description": "The unique public ID for the CustomFieldEnumValue."
    }
  }
}

object DataConflictError

{
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "enum": [
        "data-conflict-error"
      ],
      "type": "string"
    },
    "message": {
      "type": "string",
      "description": "An explanatory message: \"The update failed due to a data conflict. Please refresh and try again.\""
    }
  },
  "x-doc-skip": true,
  "description": "Error returned when Datomic tx fails due to Datomc :db.error/cas-failed error"
}

object DeleteStories

{
  "type": "object",
  "required": [
    "story_ids"
  ],
  "properties": {
    "story_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs of Stories to delete.",
      "uniqueItems": true
    }
  },
  "x-doc-skip": true
}

object EntityTemplate

{
  "type": "object",
  "required": [
    "entity_type",
    "id",
    "created_at",
    "updated_at",
    "name",
    "author_id",
    "last_used_at",
    "story_contents"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The unique identifier for the entity template."
    },
    "name": {
      "type": "string",
      "description": "The template's name."
    },
    "author_id": {
      "type": "string",
      "format": "uuid",
      "description": "The unique ID of the member who created the template."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date when the entity template was created."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "The time/date when the entity template was last updated."
    },
    "entity_type": {
      "type": "string",
      "description": "A string description of this resource."
    },
    "last_used_at": {
      "type": "string",
      "format": "date-time",
      "description": "The last time that someone created an entity using this template."
    },
    "story_contents": {
      "$ref": "#/components/schemas/StoryContents"
    }
  },
  "description": "An entity template can be used to prefill various fields when creating new stories."
}

object Epic

{
  "type": "object",
  "required": [
    "app_url",
    "description",
    "archived",
    "started",
    "entity_type",
    "labels",
    "mention_ids",
    "member_mention_ids",
    "associated_groups",
    "project_ids",
    "stories_without_projects",
    "completed_at_override",
    "productboard_plugin_id",
    "started_at",
    "completed_at",
    "objective_ids",
    "name",
    "global_id",
    "completed",
    "comments",
    "productboard_url",
    "planned_start_date",
    "state",
    "milestone_id",
    "requested_by_id",
    "epic_state_id",
    "label_ids",
    "started_at_override",
    "group_id",
    "updated_at",
    "group_mention_ids",
    "productboard_id",
    "follower_ids",
    "group_ids",
    "owner_ids",
    "external_id",
    "id",
    "position",
    "productboard_name",
    "deadline",
    "stats",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "description": "The unique ID of the Epic."
    },
    "name": {
      "type": "string",
      "description": "The name of the Epic."
    },
    "state": {
      "type": "string",
      "description": "`Deprecated` The workflow state that the Epic is in."
    },
    "stats": {
      "$ref": "#/components/schemas/EpicStats"
    },
    "labels": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LabelSlim"
      },
      "description": "An array of Labels attached to the Epic."
    },
    "app_url": {
      "type": "string",
      "description": "The Shortcut application url for the Epic."
    },
    "started": {
      "type": "boolean",
      "description": "A true/false boolean indicating if the Epic has been started."
    },
    "archived": {
      "type": "boolean",
      "description": "True/false boolean that indicates whether the Epic is archived or not."
    },
    "comments": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ThreadedComment"
      },
      "description": "A nested array of threaded comments."
    },
    "deadline": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The Epic's deadline."
    },
    "group_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "`Deprecated` The ID of the group to associate with the epic. Use `group_ids`."
    },
    "position": {
      "type": "integer",
      "format": "int64",
      "description": "The Epic's relative position in the Epic workflow state."
    },
    "completed": {
      "type": "boolean",
      "description": "A true/false boolean indicating if the Epic has been completed."
    },
    "global_id": {
      "type": "string",
      "x-doc-skip": true
    },
    "group_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDS for Groups to which this Epic is related."
    },
    "label_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of Label ids attached to the Epic."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any members you want to add as Owners on this new Epic."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was created."
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was started."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was updated."
    },
    "description": {
      "type": "string",
      "description": "The Epic's description."
    },
    "entity_type": {
      "type": "string",
      "description": "A string description of this resource."
    },
    "external_id": {
      "type": "string",
      "nullable": true,
      "description": "This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here."
    },
    "mention_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Deprecated: use member_mention_ids."
    },
    "project_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "The IDs of Projects related to this Epic."
    },
    "completed_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was completed."
    },
    "follower_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any Members you want to add as Followers on this Epic."
    },
    "milestone_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`."
    },
    "epic_state_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the Epic State."
    },
    "objective_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs for Objectives to which this epic is related."
    },
    "productboard_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The ID of the associated productboard feature."
    },
    "requested_by_id": {
      "type": "string",
      "format": "uuid",
      "description": "The ID of the Member that requested the epic."
    },
    "productboard_url": {
      "type": "string",
      "nullable": true,
      "description": "The URL of the associated productboard feature."
    },
    "associated_groups": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/EpicAssociatedGroup"
      },
      "description": "An array containing Group IDs and Group-owned story counts for the Epic's associated groups."
    },
    "group_mention_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of Group IDs that have been mentioned in the Epic description."
    },
    "productboard_name": {
      "type": "string",
      "nullable": true,
      "description": "The name of the associated productboard feature."
    },
    "member_mention_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of Member IDs that have been mentioned in the Epic description."
    },
    "planned_start_date": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The Epic's planned start date."
    },
    "started_at_override": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "A manual override for the time/date the Epic was started."
    },
    "completed_at_override": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "A manual override for the time/date the Epic was completed."
    },
    "productboard_plugin_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The ID of the associated productboard integration."
    },
    "stories_without_projects": {
      "type": "integer",
      "format": "int64",
      "description": "The number of stories in this epic which are not associated with a project."
    }
  },
  "description": "An Epic is a collection of stories that together might make up a release, a objective, or some other large initiative that you are working on."
}

object EpicAssociatedGroup

{
  "type": "object",
  "required": [
    "group_id"
  ],
  "properties": {
    "group_id": {
      "type": "string",
      "format": "uuid",
      "description": "The Group ID of the associated group."
    },
    "associated_stories_count": {
      "type": "integer",
      "format": "int64",
      "description": "The number of stories this Group owns in the Epic."
    }
  },
  "x-doc-skip": true
}

array EpicGetAllEpicCommentsResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/ThreadedComment"
  }
}

array EpicListAllAttributesResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/EpicSlim"
  }
}

array EpicListEpicsResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/EpicSlim"
  }
}

array EpicListMilestoneEpicsResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/EpicSlim"
  }
}

array EpicListObjectiveEpicsResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/EpicSlim"
  }
}

array EpicListStoriesResponse

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/StorySlim"
  }
}

object EpicSearchResult

{
  "type": "object",
  "required": [
    "app_url",
    "archived",
    "started",
    "entity_type",
    "labels",
    "mention_ids",
    "member_mention_ids",
    "associated_groups",
    "project_ids",
    "stories_without_projects",
    "completed_at_override",
    "productboard_plugin_id",
    "started_at",
    "completed_at",
    "objective_ids",
    "name",
    "global_id",
    "completed",
    "productboard_url",
    "planned_start_date",
    "state",
    "milestone_id",
    "requested_by_id",
    "epic_state_id",
    "label_ids",
    "started_at_override",
    "group_id",
    "updated_at",
    "group_mention_ids",
    "productboard_id",
    "follower_ids",
    "group_ids",
    "owner_ids",
    "external_id",
    "id",
    "position",
    "productboard_name",
    "deadline",
    "stats",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "description": "The unique ID of the Epic."
    },
    "name": {
      "type": "string",
      "description": "The name of the Epic."
    },
    "state": {
      "type": "string",
      "description": "`Deprecated` The workflow state that the Epic is in."
    },
    "stats": {
      "$ref": "#/components/schemas/EpicStats"
    },
    "labels": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LabelSlim"
      },
      "description": "An array of Labels attached to the Epic."
    },
    "app_url": {
      "type": "string",
      "description": "The Shortcut application url for the Epic."
    },
    "started": {
      "type": "boolean",
      "description": "A true/false boolean indicating if the Epic has been started."
    },
    "archived": {
      "type": "boolean",
      "description": "True/false boolean that indicates whether the Epic is archived or not."
    },
    "comments": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ThreadedComment"
      },
      "description": "A nested array of threaded comments."
    },
    "deadline": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The Epic's deadline."
    },
    "group_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "`Deprecated` The ID of the group to associate with the epic. Use `group_ids`."
    },
    "position": {
      "type": "integer",
      "format": "int64",
      "description": "The Epic's relative position in the Epic workflow state."
    },
    "completed": {
      "type": "boolean",
      "description": "A true/false boolean indicating if the Epic has been completed."
    },
    "global_id": {
      "type": "string",
      "x-doc-skip": true
    },
    "group_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDS for Groups to which this Epic is related."
    },
    "label_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of Label ids attached to the Epic."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any members you want to add as Owners on this new Epic."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was created."
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was started."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was updated."
    },
    "description": {
      "type": "string",
      "description": "The Epic's description."
    },
    "entity_type": {
      "type": "string",
      "description": "A string description of this resource."
    },
    "external_id": {
      "type": "string",
      "nullable": true,
      "description": "This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here."
    },
    "mention_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Deprecated: use member_mention_ids."
    },
    "project_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "The IDs of Projects related to this Epic."
    },
    "completed_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was completed."
    },
    "follower_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any Members you want to add as Followers on this Epic."
    },
    "milestone_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`."
    },
    "epic_state_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the Epic State."
    },
    "objective_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs for Objectives to which this epic is related."
    },
    "productboard_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The ID of the associated productboard feature."
    },
    "requested_by_id": {
      "type": "string",
      "format": "uuid",
      "description": "The ID of the Member that requested the epic."
    },
    "productboard_url": {
      "type": "string",
      "nullable": true,
      "description": "The URL of the associated productboard feature."
    },
    "associated_groups": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/EpicAssociatedGroup"
      },
      "description": "An array containing Group IDs and Group-owned story counts for the Epic's associated groups."
    },
    "group_mention_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of Group IDs that have been mentioned in the Epic description."
    },
    "productboard_name": {
      "type": "string",
      "nullable": true,
      "description": "The name of the associated productboard feature."
    },
    "member_mention_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of Member IDs that have been mentioned in the Epic description."
    },
    "planned_start_date": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The Epic's planned start date."
    },
    "started_at_override": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "A manual override for the time/date the Epic was started."
    },
    "completed_at_override": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "A manual override for the time/date the Epic was completed."
    },
    "productboard_plugin_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The ID of the associated productboard integration."
    },
    "stories_without_projects": {
      "type": "integer",
      "format": "int64",
      "description": "The number of stories in this epic which are not associated with a project."
    }
  },
  "description": "An Epic in search results. This is typed differently from Epic because the details=slim search argument will omit some fields."
}

object EpicSearchResults

{
  "type": "object",
  "required": [
    "total",
    "data",
    "next"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/EpicSearchResult"
      },
      "description": "A list of search results."
    },
    "next": {
      "type": "string",
      "nullable": true,
      "description": "The URL path and query string for the next page of search results."
    },
    "total": {
      "type": "integer",
      "format": "int64",
      "description": "The total number of matches for the search query. The first 1000 matches can be paged through via the API."
    }
  },
  "description": "The results of the Epic search query."
}

object EpicSlim

{
  "type": "object",
  "required": [
    "app_url",
    "archived",
    "started",
    "entity_type",
    "labels",
    "mention_ids",
    "member_mention_ids",
    "associated_groups",
    "project_ids",
    "stories_without_projects",
    "completed_at_override",
    "productboard_plugin_id",
    "started_at",
    "completed_at",
    "objective_ids",
    "name",
    "global_id",
    "completed",
    "productboard_url",
    "planned_start_date",
    "state",
    "milestone_id",
    "requested_by_id",
    "epic_state_id",
    "label_ids",
    "started_at_override",
    "group_id",
    "updated_at",
    "group_mention_ids",
    "productboard_id",
    "follower_ids",
    "group_ids",
    "owner_ids",
    "external_id",
    "id",
    "position",
    "productboard_name",
    "deadline",
    "stats",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "description": "The unique ID of the Epic."
    },
    "name": {
      "type": "string",
      "description": "The name of the Epic."
    },
    "state": {
      "type": "string",
      "description": "`Deprecated` The workflow state that the Epic is in."
    },
    "stats": {
      "$ref": "#/components/schemas/EpicStats"
    },
    "labels": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LabelSlim"
      },
      "description": "An array of Labels attached to the Epic."
    },
    "app_url": {
      "type": "string",
      "description": "The Shortcut application url for the Epic."
    },
    "started": {
      "type": "boolean",
      "description": "A true/false boolean indicating if the Epic has been started."
    },
    "archived": {
      "type": "boolean",
      "description": "True/false boolean that indicates whether the Epic is archived or not."
    },
    "deadline": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The Epic's deadline."
    },
    "group_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "`Deprecated` The ID of the group to associate with the epic. Use `group_ids`."
    },
    "position": {
      "type": "integer",
      "format": "int64",
      "description": "The Epic's relative position in the Epic workflow state."
    },
    "completed": {
      "type": "boolean",
      "description": "A true/false boolean indicating if the Epic has been completed."
    },
    "global_id": {
      "type": "string",
      "x-doc-skip": true
    },
    "group_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDS for Groups to which this Epic is related."
    },
    "label_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of Label ids attached to the Epic."
    },
    "owner_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any members you want to add as Owners on this new Epic."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was created."
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was started."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was updated."
    },
    "description": {
      "type": "string",
      "description": "The Epic's description."
    },
    "entity_type": {
      "type": "string",
      "description": "A string description of this resource."
    },
    "external_id": {
      "type": "string",
      "nullable": true,
      "description": "This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here."
    },
    "mention_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Deprecated: use member_mention_ids."
    },
    "project_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "The IDs of Projects related to this Epic."
    },
    "completed_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The time/date the Epic was completed."
    },
    "follower_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of UUIDs for any Members you want to add as Followers on this Epic."
    },
    "milestone_id": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`."
    },
    "epic_state_id": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the Epic State."
    },
    "objective_ids": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "description": "An array of IDs for Objectives to which this epic is related."
    },
    "productboard_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The ID of the associated productboard feature."
    },
    "requested_by_id": {
      "type": "string",
      "format": "uuid",
      "description": "The ID of the Member that requested the epic."
    },
    "productboard_url": {
      "type": "string",
      "nullable": true,
      "description": "The URL of the associated productboard feature."
    },
    "associated_groups": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/EpicAssociatedGroup"
      },
      "description": "An array containing Group IDs and Group-owned story counts for the Epic's associated groups."
    },
    "group_mention_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of Group IDs that have been mentioned in the Epic description."
    },
    "productboard_name": {
      "type": "string",
      "nullable": true,
      "description": "The name of the associated productboard feature."
    },
    "member_mention_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "An array of Member IDs that have been mentioned in the Epic description."
    },
    "planned_start_date": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "The Epic's planned start date."
    },
    "started_at_override": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "A manual override for the time/date the Epic was started."
    },
    "completed_at_override": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "A manual override for the time/date the Epic was completed."
    },
    "productboard_plugin_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "The ID of the associated productboard integration."
    },
    "stories_without_projects": {
      "type": "integer",
      "format": "int64",
      "description": "The number of stories in this epic which are not associated with a project."
    }
  },
  "description": "EpicSlim represents the same resource as an Epic but is more light-weight, including all Epic fields except the comments array. The description string can be optionally included. Use the [Get Epic](https://developer.shortcut.com) endpoint to fetch the unabridged payload for an Epic."
}

Load more schemas

Versions

Version	Endpoints	Schemas	Ingested	Status
3.0	123	192	2026-05-11	current
3.0	123	192	2026-04-16