EpicState
{
"type": "object",
"required": [
"description",
"entity_type",
"name",
"global_id",
"type",
"updated_at",
"id",
"position",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Epic State."
},
"name": {
"type": "string",
"description": "The Epic State's name."
},
"type": {
"type": "string",
"description": "The type of Epic State (Unstarted, Started, or Done)"
},
"color": {
"type": "string",
"format": "css-color",
"pattern": "^#[a-fA-F0-9]{6}$",
"minLength": 1,
"description": "The hex color for this Epic State."
},
"position": {
"type": "integer",
"format": "int64",
"description": "The position that the Epic State is in, starting with 0 at the left."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the Epic State was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the Epic State was last updated."
},
"description": {
"type": "string",
"description": "The description of what sort of Epics belong in that Epic State."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
}
},
"description": "Epic State is any of the at least 3 columns. Epic States correspond to one of 3 types: Unstarted, Started, or Done."
}
EpicStats
{
"type": "object",
"required": [
"num_points_done",
"num_related_documents",
"num_stories_unstarted",
"num_stories_total",
"last_story_update",
"num_points_started",
"num_points_unstarted",
"num_stories_started",
"num_stories_unestimated",
"num_stories_backlog",
"num_points_backlog",
"num_points",
"num_stories_done"
],
"properties": {
"num_points": {
"type": "integer",
"format": "int64",
"description": "The total number of points in this Epic."
},
"num_points_done": {
"type": "integer",
"format": "int64",
"description": "The total number of completed points in this Epic."
},
"num_stories_done": {
"type": "integer",
"format": "int64",
"description": "The total number of done Stories in this Epic."
},
"average_lead_time": {
"type": "integer",
"format": "int64",
"description": "The average lead time (in seconds) of completed stories in this Epic."
},
"last_story_update": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The date of the last update of a Story in this Epic."
},
"num_stories_total": {
"type": "integer",
"format": "int64",
"description": "The total number of Stories in this Epic."
},
"average_cycle_time": {
"type": "integer",
"format": "int64",
"description": "The average cycle time (in seconds) of completed stories in this Epic."
},
"num_points_backlog": {
"type": "integer",
"format": "int64",
"description": "The total number of backlog points in this Epic."
},
"num_points_started": {
"type": "integer",
"format": "int64",
"description": "The total number of started points in this Epic."
},
"num_stories_backlog": {
"type": "integer",
"format": "int64",
"description": "The total number of backlog Stories in this Epic."
},
"num_stories_started": {
"type": "integer",
"format": "int64",
"description": "The total number of started Stories in this Epic."
},
"num_points_unstarted": {
"type": "integer",
"format": "int64",
"description": "The total number of unstarted points in this Epic."
},
"num_related_documents": {
"type": "integer",
"format": "int64",
"description": "The total number of documents associated with this Epic."
},
"num_stories_unstarted": {
"type": "integer",
"format": "int64",
"description": "The total number of unstarted Stories in this Epic."
},
"num_stories_unestimated": {
"type": "integer",
"format": "int64",
"description": "The total number of Stories with no point estimate."
}
},
"description": "A group of calculated values for this Epic."
}
EpicWorkflow
{
"type": "object",
"required": [
"entity_type",
"id",
"created_at",
"updated_at",
"default_epic_state_id",
"epic_states"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Epic Workflow."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The date the Epic Workflow was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "The date the Epic Workflow was updated."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"epic_states": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicState"
},
"description": "A map of the Epic States in this Epic Workflow."
},
"default_epic_state_id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the default Epic State that new Epics are assigned by default."
}
},
"description": "Epic Workflow is the array of defined Epic States. Epic Workflow can be queried using the API but must be updated in the Shortcut UI. "
}
ExternalLinkStoryGetStoriesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
FileListFilesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadedFile"
}
}
FileListLinkedFilesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/LinkedFile"
}
}
FileUploadAndAssociateRequest
{
"type": "object",
"required": [
"file0"
],
"properties": {
"file0": {
"type": "string",
"format": "binary",
"description": "A file upload. At least one is required."
},
"file1": {
"type": "string",
"format": "binary",
"description": "Optional additional files."
},
"file2": {
"type": "string",
"format": "binary",
"description": "Optional additional files."
},
"file3": {
"type": "string",
"format": "binary",
"description": "Optional additional files."
},
"story_id": {
"type": "integer",
"format": "int64",
"description": "The story ID that these files will be associated with."
}
}
}
FileUploadAndAssociateResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadedFile"
}
}
Group
{
"type": "object",
"required": [
"app_url",
"description",
"archived",
"entity_type",
"color",
"num_stories_started",
"mention_name",
"name",
"global_id",
"color_key",
"num_stories",
"num_epics_started",
"num_stories_backlog",
"id",
"display_icon",
"member_ids",
"workflow_ids"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The id of the Group."
},
"name": {
"type": "string",
"description": "The name of the Group."
},
"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 Group (for example, \"#ff0000\")."
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Group."
},
"archived": {
"type": "boolean",
"description": "Whether or not the Group is archived."
},
"color_key": {
"enum": [
"blue",
"purple",
"midnight-blue",
"orange",
"yellow-green",
"brass",
"gray",
"fuchsia",
"yellow",
"pink",
"sky-blue",
"green",
"red",
"black",
"slate",
"turquoise"
],
"type": "string",
"nullable": true,
"description": "The color key to be displayed with the Group."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"member_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The Member IDs contain within the Group."
},
"description": {
"type": "string",
"description": "The description of the Group."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"num_stories": {
"type": "integer",
"format": "int64",
"description": "The total number of stories assigned ot the group."
},
"display_icon": {
"$ref": "#/components/schemas/Icon"
},
"mention_name": {
"type": "string",
"pattern": "^[a-z0-9\\-\\_\\.]+$",
"minLength": 1,
"description": "The mention name of the Group."
},
"workflow_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "The Workflow IDs contained within the Group."
},
"num_epics_started": {
"type": "integer",
"format": "int64",
"description": "The number of epics assigned to the group which are in the started workflow state."
},
"num_stories_backlog": {
"type": "integer",
"format": "int64",
"description": "The number of stories assigned to the group which are in a backlog workflow state."
},
"num_stories_started": {
"type": "integer",
"format": "int64",
"description": "The number of stories assigned to the group which are in a started workflow state."
}
},
"description": "A Group."
}
GroupListStoriesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
GroupListTeamsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Group"
}
}
History
{
"type": "object",
"required": [
"changed_at",
"actions",
"id",
"version"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The ID representing the change for the story."
},
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/HistoryActionBranchCreate"
},
{
"$ref": "#/components/schemas/HistoryActionBranchMerge"
},
{
"$ref": "#/components/schemas/HistoryActionBranchPush"
},
{
"$ref": "#/components/schemas/HistoryActionLabelCreate"
},
{
"$ref": "#/components/schemas/HistoryActionLabelUpdate"
},
{
"$ref": "#/components/schemas/HistoryActionLabelDelete"
},
{
"$ref": "#/components/schemas/HistoryActionProjectUpdate"
},
{
"$ref": "#/components/schemas/HistoryActionPullRequest"
},
{
"$ref": "#/components/schemas/HistoryActionStoryCreate"
},
{
"$ref": "#/components/schemas/HistoryActionStoryUpdate"
},
{
"$ref": "#/components/schemas/HistoryActionStoryDelete"
},
{
"$ref": "#/components/schemas/HistoryActionStoryCommentCreate"
},
{
"$ref": "#/components/schemas/HistoryActionStoryLinkCreate"
},
{
"$ref": "#/components/schemas/HistoryActionStoryLinkUpdate"
},
{
"$ref": "#/components/schemas/HistoryActionStoryLinkDelete"
},
{
"$ref": "#/components/schemas/HistoryActionTaskCreate"
},
{
"$ref": "#/components/schemas/HistoryActionTaskUpdate"
},
{
"$ref": "#/components/schemas/HistoryActionTaskDelete"
},
{
"$ref": "#/components/schemas/HistoryActionWorkspace2BulkUpdate"
}
]
},
"description": "An array of actions that were performed for the change."
},
"version": {
"enum": [
"v1"
],
"type": "string",
"description": "The version of the change format."
},
"member_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the member who performed the change."
},
"changed_at": {
"type": "string",
"description": "The date when the change occurred."
},
"primary_id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the primary entity that has changed, if applicable."
},
"references": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/HistoryReferenceBranch"
},
{
"$ref": "#/components/schemas/HistoryReferenceCommit"
},
{
"$ref": "#/components/schemas/HistoryReferenceEpic"
},
{
"$ref": "#/components/schemas/HistoryReferenceGroup"
},
{
"$ref": "#/components/schemas/HistoryReferenceIteration"
},
{
"$ref": "#/components/schemas/HistoryReferenceLabel"
},
{
"$ref": "#/components/schemas/HistoryReferenceProject"
},
{
"$ref": "#/components/schemas/HistoryReferenceStory"
},
{
"$ref": "#/components/schemas/HistoryReferenceStoryTask"
},
{
"$ref": "#/components/schemas/HistoryReferenceCustomFieldEnumValue"
},
{
"$ref": "#/components/schemas/HistoryReferenceWorkflowState"
},
{
"$ref": "#/components/schemas/HistoryReferenceGeneral"
}
]
},
"description": "An array of objects affected by the change. Reference objects provide basic information for the entities reference in the history actions. Some have specific fields, but they always contain an id, entity_type, and a name."
},
"webhook_id": {
"type": "string",
"nullable": true,
"description": "The ID of the webhook that handled the change."
},
"external_id": {
"type": "string",
"description": "The ID of the webhook that handled the change."
}
},
"description": "A history item is a group of actions that represent a transactional change to a Story."
}
HistoryActionBranchCreate
{
"type": "object",
"required": [
"id",
"entity_type",
"name",
"url",
"action"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"url": {
"type": "string",
"description": "The URL from the provider of the VCS Branch that was pushed"
},
"name": {
"type": "string",
"description": "The name of the VCS Branch that was pushed"
},
"action": {
"enum": [
"create"
],
"type": "string",
"description": "The action of the entity referenced."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a VCS Branch being created."
}
HistoryActionBranchMerge
{
"type": "object",
"required": [
"id",
"entity_type",
"name",
"url",
"action"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"url": {
"type": "string",
"description": "The URL from the provider of the VCS Branch that was pushed"
},
"name": {
"type": "string",
"description": "The name of the VCS Branch that was pushed"
},
"action": {
"enum": [
"merge"
],
"type": "string",
"description": "The action of the entity referenced."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a VCS Branch being merged."
}
HistoryActionBranchPush
{
"type": "object",
"required": [
"id",
"entity_type",
"name",
"url",
"action"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"url": {
"type": "string",
"description": "The URL from the provider of the VCS Branch that was pushed"
},
"name": {
"type": "string",
"description": "The name of the VCS Branch that was pushed"
},
"action": {
"enum": [
"push"
],
"type": "string",
"description": "The action of the entity referenced."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a VCS Branch being pushed."
}
HistoryActionLabelCreate
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"app_url",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the Label."
},
"action": {
"enum": [
"create"
],
"type": "string",
"description": "The action of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Label."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Label being created."
}
HistoryActionLabelDelete
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the Label."
},
"action": {
"enum": [
"delete"
],
"type": "string",
"description": "The action of the entity referenced."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Label being deleted."
}
HistoryActionLabelUpdate
{
"type": "object",
"required": [
"id",
"entity_type",
"action"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"action": {
"enum": [
"update"
],
"type": "string",
"description": "The action of the entity referenced."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Label being updated."
}
HistoryActionProjectUpdate
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"app_url",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the Project."
},
"action": {
"enum": [
"update"
],
"type": "string",
"description": "The action of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Project."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Project being updated."
}
HistoryActionPullRequest
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"number",
"title",
"url"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The URL from the provider of the VCS Pull Request."
},
"title": {
"type": "string",
"description": "The title of the Pull Request."
},
"action": {
"enum": [
"open",
"update",
"reopen",
"close",
"sync",
"comment"
],
"type": "string",
"description": "The action of the entity referenced."
},
"number": {
"type": "integer",
"format": "int64",
"description": "The VCS Repository-specific ID for the Pull Request."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing various operations for a Pull Request."
}
HistoryActionStoryCommentCreate
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"app_url",
"text",
"author_id"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"text": {
"type": "string",
"description": "The text of the Story Comment."
},
"action": {
"enum": [
"create"
],
"type": "string",
"description": "The action of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Story Comment."
},
"author_id": {
"type": "string",
"format": "uuid",
"description": "The Member ID of who created the Story Comment."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Story Comment being created."
}
HistoryActionStoryCreate
{
"type": "object",
"required": [
"app_url",
"entity_type",
"story_type",
"name",
"id",
"action"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the Story."
},
"action": {
"enum": [
"create"
],
"type": "string",
"description": "The action of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Story."
},
"blocked": {
"type": "boolean",
"description": "Whether or not the Story is blocked by another Story."
},
"blocker": {
"type": "boolean",
"description": "Whether or not the Story is blocking another Story."
},
"epic_id": {
"type": "integer",
"format": "int64",
"description": "The Epic ID for this Story."
},
"started": {
"type": "boolean",
"description": "Whether or not the Story has been started."
},
"deadline": {
"type": "string",
"description": "The timestamp representing the Story's deadline."
},
"estimate": {
"type": "integer",
"format": "int64",
"description": "The estimate (or point value) for the Story."
},
"group_id": {
"type": "string",
"format": "uuid",
"description": "The Team IDs for the followers of the Story."
},
"task_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "An array of Task IDs on this Story."
},
"completed": {
"type": "boolean",
"description": "Whether or not the Story is completed."
},
"label_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "An array of Labels IDs attached to the Story."
},
"owner_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of Member IDs that are the owners of the Story."
},
"project_id": {
"type": "integer",
"format": "int64",
"description": "The Project ID of the Story is in."
},
"story_type": {
"enum": [
"feature",
"chore",
"bug"
],
"type": "string",
"description": "The type of Story; either feature, bug, or chore."
},
"description": {
"type": "string",
"description": "The description of the Story."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
},
"follower_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of Member IDs for the followers of the Story."
},
"iteration_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The Iteration ID the Story is in."
},
"requested_by_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the Member that requested the Story."
},
"workflow_state_id": {
"type": "integer",
"format": "int64",
"description": "An array of Workflow State IDs attached to the Story."
},
"object_story_link_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "An array of Story IDs that are the object of a Story Link relationship."
},
"custom_field_value_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of Custom Field Enum Value ids on this Story."
},
"subject_story_link_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "An array of Story IDs that are the subject of a Story Link relationship."
}
},
"description": "An action representing a Story being created."
}
HistoryActionStoryDelete
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"name",
"story_type"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the Story."
},
"action": {
"enum": [
"delete"
],
"type": "string",
"description": "The action of the entity referenced."
},
"story_type": {
"enum": [
"feature",
"chore",
"bug"
],
"type": "string",
"description": "The type of Story; either feature, bug, or chore."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Story being deleted."
}
HistoryActionStoryLinkCreate
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"verb",
"subject_id",
"object_id"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"verb": {
"enum": [
"blocks",
"duplicates",
"relates to"
],
"type": "string",
"description": "The verb describing the link's relationship."
},
"action": {
"enum": [
"create"
],
"type": "string",
"description": "The action of the entity referenced."
},
"object_id": {
"type": "integer",
"format": "int64",
"description": "The Story ID of the object Story."
},
"subject_id": {
"type": "integer",
"format": "int64",
"description": "The Story ID of the subject Story."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Story Link being created."
}
HistoryActionStoryLinkDelete
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"verb",
"subject_id",
"object_id"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"verb": {
"enum": [
"blocks",
"duplicates",
"relates to"
],
"type": "string",
"description": "The verb describing the link's relationship."
},
"action": {
"enum": [
"delete"
],
"type": "string",
"description": "The action of the entity referenced."
},
"object_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The Story ID of the object Story."
},
"subject_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The Story ID of the subject Story."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Story Link being deleted."
}
HistoryActionStoryLinkUpdate
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"verb",
"subject_id",
"object_id",
"changes"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"verb": {
"enum": [
"blocks",
"duplicates",
"relates to"
],
"type": "string",
"description": "The verb describing the link's relationship."
},
"action": {
"enum": [
"update"
],
"type": "string",
"description": "The action of the entity referenced."
},
"changes": {
"$ref": "#/components/schemas/HistoryChangesStoryLink"
},
"object_id": {
"type": "integer",
"format": "int64",
"description": "The Story ID of the object Story."
},
"subject_id": {
"type": "integer",
"format": "int64",
"description": "The Story ID of the subject Story."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Story Link being updated."
}
HistoryActionStoryUpdate
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"app_url",
"name",
"story_type"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the Story."
},
"action": {
"enum": [
"update"
],
"type": "string",
"description": "The action of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Story."
},
"changes": {
"$ref": "#/components/schemas/HistoryChangesStory"
},
"story_type": {
"enum": [
"feature",
"chore",
"bug"
],
"type": "string",
"description": "The type of Story; either feature, bug, or chore."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Story being updated."
}
HistoryActionTaskCreate
{
"type": "object",
"required": [
"description",
"entity_type",
"id",
"action",
"complete"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"action": {
"enum": [
"create"
],
"type": "string",
"description": "The action of the entity referenced."
},
"complete": {
"type": "boolean",
"description": "Whether or not the Task is complete."
},
"deadline": {
"type": "string",
"description": "A timestamp that represent's the Task's deadline."
},
"owner_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of Member IDs that represent the Task's owners."
},
"description": {
"type": "string",
"description": "The description of the Task."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
},
"mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of Member IDs that represent who has been mentioned in the Task."
},
"group_mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of Groups IDs that represent which have been mentioned in the Task."
}
},
"description": "An action representing a Task being created."
}
HistoryActionTaskDelete
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"description"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"action": {
"enum": [
"delete"
],
"type": "string",
"description": "The action of the entity referenced."
},
"description": {
"type": "string",
"description": "The description of the Task being deleted."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Task being deleted."
}
HistoryActionTaskUpdate
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"changes",
"description",
"story_id"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the entity referenced."
},
"action": {
"enum": [
"update"
],
"type": "string",
"description": "The action of the entity referenced."
},
"changes": {
"$ref": "#/components/schemas/HistoryChangesTask"
},
"complete": {
"type": "boolean",
"description": "Whether or not the Task is complete."
},
"story_id": {
"type": "integer",
"format": "int64",
"description": "The Story ID that contains the Task."
},
"description": {
"type": "string",
"description": "The description of the Task."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a Task being updated."
}
HistoryActionWorkspace2BulkUpdate
{
"type": "object",
"required": [
"id",
"entity_type",
"action",
"name"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the workspace2 in which the BulkUpdate occurred."
},
"action": {
"enum": [
"bulk-update"
],
"type": "string",
"description": "The action of the entity referenced."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "An action representing a bulk operation within a workspace2."
}
HistoryChangesStory
{
"type": "object",
"properties": {
"name": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"blocked": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"blocker": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"epic_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"started": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"archived": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"deadline": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"estimate": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"group_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewUuid"
},
"task_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"completed": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"label_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"owner_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"branch_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"commit_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"project_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"story_type": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"description": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"mention_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"follower_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"iteration_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"requested_by_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewUuid"
},
"workflow_state_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"object_story_link_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"custom_field_value_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"subject_story_link_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
}
},
"description": "The changes that have occurred as a result of the action."
}
HistoryChangesStoryLink
{
"type": "object",
"properties": {
"verb": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"object_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"subject_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
}
},
"description": "The changes that have occurred as a result of the action."
}
HistoryChangesTask
{
"type": "object",
"properties": {
"complete": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"owner_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"description": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"mention_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
}
},
"description": "The changes that have occurred as a result of the action."
}
HistoryReferenceBranch
{
"type": "object",
"required": [
"id",
"entity_type",
"name",
"url"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The external URL for the Branch."
},
"name": {
"type": "string",
"description": "The name of the entity referenced."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A reference to a VCS Branch."
}
HistoryReferenceCommit
{
"type": "object",
"required": [
"id",
"entity_type",
"message",
"url"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The external URL for the Branch."
},
"message": {
"type": "string",
"description": "The message from the Commit."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A reference to a VCS Commit."
}
HistoryReferenceCustomFieldEnumValue
{
"type": "object",
"required": [
"id",
"entity_type",
"string_value",
"enum_value_enabled",
"field_id",
"field_type",
"field_name",
"field_enabled"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"field_id": {
"type": "string",
"format": "uuid",
"description": "The public-id of the parent custom-field of this enum value."
},
"field_name": {
"type": "string",
"description": "The name as it is displayed to the user of the parent custom-field of this enum value."
},
"field_type": {
"type": "string",
"description": "The type variety of the parent custom-field of this enum value."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
},
"string_value": {
"type": "string",
"nullable": true,
"description": "The custom-field enum value as a string."
},
"field_enabled": {
"type": "boolean",
"description": "Whether or not the custom-field is enabled."
},
"enum_value_enabled": {
"type": "boolean",
"nullable": true,
"description": "Whether or not the custom-field enum value is enabled."
}
},
"description": "A reference to a CustomField value asserted on a Story."
}
HistoryReferenceEpic
{
"type": "object",
"required": [
"id",
"entity_type",
"app_url",
"name"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Epic."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A reference to an Epic."
}
HistoryReferenceGeneral
{
"type": "object",
"required": [
"id",
"entity_type",
"name"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the entity referenced."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A default reference for entity types that don't have extra fields."
}
HistoryReferenceGroup
{
"type": "object",
"required": [
"id",
"entity_type",
"name"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the entity referenced."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A reference to a Group."
}
HistoryReferenceIteration
{
"type": "object",
"required": [
"id",
"entity_type",
"app_url",
"name"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Iteration."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A reference to an Iteration."
}
HistoryReferenceLabel
{
"type": "object",
"required": [
"id",
"entity_type",
"app_url",
"name"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Label."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A reference to an Label."
}
HistoryReferenceProject
{
"type": "object",
"required": [
"id",
"entity_type",
"app_url",
"name"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Project."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A reference to an Project."
}
HistoryReferenceStory
{
"type": "object",
"required": [
"id",
"entity_type",
"app_url",
"name",
"story_type"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the entity referenced."
},
"app_url": {
"type": "string",
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Story."
},
"story_type": {
"enum": [
"feature",
"chore",
"bug"
],
"type": "string",
"description": "If the referenced entity is a Story, either \"bug\", \"chore\", or \"feature\"."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A reference to a Story."
}
HistoryReferenceStoryTask
{
"type": "object",
"required": [
"id",
"entity_type",
"description"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"description": {
"type": "string",
"description": "The description of the Story Task."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A reference to a Story Task."
}
HistoryReferenceWorkflowState
{
"type": "object",
"required": [
"id",
"entity_type",
"type",
"name"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
],
"description": "The ID of the entity referenced."
},
"name": {
"type": "string",
"description": "The name of the entity referenced."
},
"type": {
"enum": [
"started",
"unstarted",
"done"
],
"type": "string",
"description": "Either \"unstarted\", \"started\", or \"done\"."
},
"entity_type": {
"type": "string",
"description": "The type of entity referenced."
}
},
"description": "A references to a Story Workflow State."
}
Icon
{
"type": "object",
"required": [
"entity_type",
"id",
"created_at",
"updated_at",
"url"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The unique ID of the Icon."
},
"url": {
"type": "string",
"description": "The URL of the Icon."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The time/date that the Icon was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "The time/date that the Icon was updated."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
}
},
"description": "Icons are used to attach images to Groups, Workspaces, Members, and Loading screens in the Shortcut web application."
}
Identity
{
"type": "object",
"required": [
"entity_type",
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"nullable": true,
"description": "This is your login in VCS."
},
"type": {
"enum": [
"slack",
"github",
"gitlab",
"bitbucket"
],
"type": "string",
"nullable": true,
"description": "The service this Identity is for."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
}
},
"description": "The Identity of the VCS user that authored the Commit."
}
Iteration
{
"type": "object",
"required": [
"app_url",
"description",
"entity_type",
"labels",
"mention_ids",
"member_mention_ids",
"associated_groups",
"name",
"global_id",
"label_ids",
"updated_at",
"group_mention_ids",
"end_date",
"follower_ids",
"group_ids",
"start_date",
"status",
"id",
"stats",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The ID of the iteration."
},
"name": {
"type": "string",
"description": "The name of the iteration."
},
"stats": {
"$ref": "#/components/schemas/IterationStats"
},
"labels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Label"
},
"description": "An array of labels attached to the iteration."
},
"status": {
"type": "string",
"description": "The status of the iteration. Values are either \"unstarted\", \"started\", or \"done\"."
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Iteration."
},
"end_date": {
"type": "string",
"format": "date-time",
"description": "The date this iteration begins."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"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."
},
"label_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "An array of label ids attached to the iteration."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The instant when this iteration was created."
},
"start_date": {
"type": "string",
"format": "date-time",
"description": "The date this iteration begins."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "The instant when this iteration was last updated."
},
"description": {
"type": "string",
"description": "The description of the iteration."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource"
},
"mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Deprecated: use member_mention_ids."
},
"follower_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of UUIDs for any Members listed as Followers."
},
"associated_groups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IterationAssociatedGroup"
},
"x-doc-skip": true,
"description": "An array containing Group IDs and Group-owned story counts for the Iteration'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 Story description."
},
"member_mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of Member IDs that have been mentioned in the Story description."
}
},
"description": "An Iteration is a defined, time-boxed period of development for a collection of Stories. See https://help.shortcut.com/hc/en-us/articles/360028953452-Iterations-Overview for more information."
}
IterationAssociatedGroup
{
"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 Iteration."
}
},
"x-doc-skip": true
}