IterationGetAllIterationsResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/IterationSlim"
}
}
IterationListStoriesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
IterationSearchResults
{
"type": "object",
"required": [
"total",
"data",
"next"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IterationSlim"
},
"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 Iteration search query."
}
IterationSlim
{
"type": "object",
"required": [
"app_url",
"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."
},
"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": "IterationSlim represents the same resource as an Iteration, but is more light-weight. Use the [Get Iteration](https://developer.shortcut.com) endpoint to fetch the unabridged payload for an Iteration. "
}
IterationStats
{
"type": "object",
"required": [
"num_points_done",
"num_related_documents",
"num_stories_unstarted",
"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 Iteration."
},
"num_points_done": {
"type": "integer",
"format": "int64",
"description": "The total number of completed points in this Iteration."
},
"num_stories_done": {
"type": "integer",
"format": "int64",
"description": "The total number of done Stories in this Iteration."
},
"average_lead_time": {
"type": "integer",
"format": "int64",
"description": "The average lead time (in seconds) of completed stories in this Iteration."
},
"average_cycle_time": {
"type": "integer",
"format": "int64",
"description": "The average cycle time (in seconds) of completed stories in this Iteration."
},
"num_points_backlog": {
"type": "integer",
"format": "int64",
"description": "The total number of backlog points in this Iteration."
},
"num_points_started": {
"type": "integer",
"format": "int64",
"description": "The total number of started points in this Iteration."
},
"num_stories_backlog": {
"type": "integer",
"format": "int64",
"description": "The total number of backlog Stories in this Iteration."
},
"num_stories_started": {
"type": "integer",
"format": "int64",
"description": "The total number of started Stories in this Iteration."
},
"num_points_unstarted": {
"type": "integer",
"format": "int64",
"description": "The total number of unstarted points in this Iteration."
},
"num_related_documents": {
"type": "integer",
"format": "int64",
"description": "The total number of documents related to an Iteration"
},
"num_stories_unstarted": {
"type": "integer",
"format": "int64",
"description": "The total number of unstarted Stories in this Iteration."
},
"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 Iteration."
}
KeyResult
{
"type": "object",
"required": [
"id",
"name",
"objective_id",
"type",
"initial_observed_value",
"current_observed_value",
"current_target_value",
"progress"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The ID of the Key Result."
},
"name": {
"type": "string",
"description": "The name of the Key Result."
},
"type": {
"enum": [
"percent",
"boolean",
"numeric"
],
"type": "string",
"description": "The type of the Key Result (numeric, percent, or boolean)."
},
"progress": {
"type": "integer",
"format": "int64",
"description": "The integer percentage of progress toward completion of the Key Result."
},
"objective_id": {
"type": "integer",
"format": "int64",
"description": "The Objective to which this Key Result belongs."
},
"current_target_value": {
"$ref": "#/components/schemas/KeyResultValue"
},
"current_observed_value": {
"$ref": "#/components/schemas/KeyResultValue"
},
"initial_observed_value": {
"$ref": "#/components/schemas/KeyResultValue"
}
}
}
KeyResultValue
{
"type": "object",
"properties": {
"boolean_value": {
"type": "boolean",
"description": "The boolean value."
},
"numeric_value": {
"type": "string",
"description": "The numeric value, as a decimal string. No more than two decimal places are allowed."
}
},
"description": "The starting value of the Key Result."
}
Label
{
"type": "object",
"required": [
"app_url",
"description",
"archived",
"entity_type",
"color",
"name",
"global_id",
"updated_at",
"external_id",
"id",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Label."
},
"name": {
"type": "string",
"description": "The name of the Label."
},
"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 Label (for example, \"#ff0000\")."
},
"stats": {
"$ref": "#/components/schemas/LabelStats"
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Label."
},
"archived": {
"type": "boolean",
"description": "A true/false boolean indicating if the Label has been archived."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date that the Label was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date that the Label was updated."
},
"description": {
"type": "string",
"nullable": true,
"description": "The description of the Label."
},
"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 Label has been imported from another tool, the ID in the other tool can be indicated here."
}
},
"description": "A Label can be used to associate and filter Stories and Epics, and also create new Workspaces."
}
LabelListResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Label"
}
}
LabelListStoriesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
LabelSlim
{
"type": "object",
"required": [
"app_url",
"description",
"archived",
"entity_type",
"color",
"name",
"global_id",
"updated_at",
"external_id",
"id",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Label."
},
"name": {
"type": "string",
"description": "The name of the Label."
},
"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 Label (for example, \"#ff0000\")."
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Label."
},
"archived": {
"type": "boolean",
"description": "A true/false boolean indicating if the Label has been archived."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date that the Label was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date that the Label was updated."
},
"description": {
"type": "string",
"nullable": true,
"description": "The description of the Label."
},
"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 Label has been imported from another tool, the ID in the other tool can be indicated here."
}
},
"description": "A Label can be used to associate and filter Stories and Epics, and also create new Workspaces. A slim Label does not include aggregate stats. Fetch the Label using the labels endpoint to retrieve them."
}
LabelStats
{
"type": "object",
"required": [
"num_related_documents",
"num_epics",
"num_stories_unstarted",
"num_stories_total",
"num_epics_unstarted",
"num_epics_in_progress",
"num_points_unstarted",
"num_stories_unestimated",
"num_points_in_progress",
"num_epics_total",
"num_stories_completed",
"num_points_completed",
"num_stories_backlog",
"num_points_total",
"num_stories_in_progress",
"num_points_backlog",
"num_epics_completed"
],
"properties": {
"num_epics": {
"type": "integer",
"format": "int64",
"description": "The total number of Epics with this Label."
},
"num_epics_total": {
"type": "integer",
"format": "int64",
"description": "The total number of Epics associated with this Label."
},
"num_points_total": {
"type": "integer",
"format": "int64",
"description": "The total number of points with this Label."
},
"num_stories_total": {
"type": "integer",
"format": "int64",
"description": "The total number of Stories with this Label."
},
"num_points_backlog": {
"type": "integer",
"format": "int64",
"description": "The total number of backlog points with this Label."
},
"num_epics_completed": {
"type": "integer",
"format": "int64",
"description": "The number of completed Epics associated with this Label."
},
"num_epics_unstarted": {
"type": "integer",
"format": "int64",
"description": "The number of unstarted epics associated with this label."
},
"num_stories_backlog": {
"type": "integer",
"format": "int64",
"description": "The total number of stories backlog Stories with this Label."
},
"num_points_completed": {
"type": "integer",
"format": "int64",
"description": "The total number of completed points with this Label."
},
"num_points_unstarted": {
"type": "integer",
"format": "int64",
"description": "The total number of unstarted points with this Label."
},
"num_epics_in_progress": {
"type": "integer",
"format": "int64",
"description": "The number of in progress epics associated with this label."
},
"num_related_documents": {
"type": "integer",
"format": "int64",
"description": "The total number of Documents associated this Label."
},
"num_stories_completed": {
"type": "integer",
"format": "int64",
"description": "The total number of completed Stories with this Label."
},
"num_stories_unstarted": {
"type": "integer",
"format": "int64",
"description": "The total number of stories unstarted Stories with this Label."
},
"num_points_in_progress": {
"type": "integer",
"format": "int64",
"description": "The total number of in-progress points with this Label."
},
"num_stories_in_progress": {
"type": "integer",
"format": "int64",
"description": "The total number of in-progress Stories with this Label."
},
"num_stories_unestimated": {
"type": "integer",
"format": "int64",
"description": "The total number of Stories with no point estimate with this Label."
}
},
"description": "A group of calculated values for this Label. This is not included if the slim? flag is set to true for the List Labels endpoint."
}
LinkedFile
{
"type": "object",
"required": [
"description",
"entity_type",
"story_ids",
"mention_ids",
"member_mention_ids",
"name",
"thumbnail_url",
"type",
"size",
"uploader_id",
"content_type",
"updated_at",
"group_mention_ids",
"id",
"url",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique identifier for the file."
},
"url": {
"type": "string",
"description": "The URL of the file."
},
"name": {
"type": "string",
"description": "The name of the linked file."
},
"size": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The filesize, if the integration provided it."
},
"type": {
"type": "string",
"description": "The integration type (e.g. google, dropbox, box)."
},
"story_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "The IDs of the stories this file is attached to."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the LinkedFile was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the LinkedFile was updated."
},
"description": {
"type": "string",
"nullable": true,
"description": "The description of the file."
},
"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."
},
"uploader_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the member that uploaded the file."
},
"content_type": {
"type": "string",
"nullable": true,
"description": "The content type of the image (e.g. txt/plain)."
},
"thumbnail_url": {
"type": "string",
"nullable": true,
"description": "The URL of the file thumbnail, if the integration provided it."
},
"group_mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The groups that are mentioned in the description of the file."
},
"member_mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The members that are mentioned in the description of the file."
}
},
"description": "Linked files are stored on a third-party website and linked to one or more Stories. Shortcut currently supports linking files from Google Drive, Dropbox, Box, and by URL."
}
MaxSearchResultsExceededError
{
"type": "object",
"required": [
"error",
"message",
"maximum-results"
],
"properties": {
"error": {
"enum": [
"maximum-results-exceeded"
],
"type": "string",
"description": "The name for this type of error, `maximum-results-exceeded`"
},
"message": {
"type": "string",
"description": "An explanatory message: \"A maximum of 1000 search results are supported.\""
},
"maximum-results": {
"enum": [
1000
],
"type": "integer",
"format": "int64",
"description": "The maximum number of search results supported, `1000`"
}
},
"description": "Error returned when total maximum supported results have been reached."
}
Member
{
"type": "object",
"required": [
"role",
"entity_type",
"disabled",
"global_id",
"state",
"updated_at",
"created_without_invite",
"group_ids",
"id",
"profile",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The Member's ID in Shortcut."
},
"role": {
"type": "string",
"description": "The Member's role in the Workspace."
},
"state": {
"enum": [
"partial",
"full",
"disabled",
"imported"
],
"type": "string",
"description": "The user state, one of partial, full, disabled, or imported. A partial user is disabled, has no means to log in, and is not an import user. A full user is enabled and has a means to log in. A disabled user is disabled and has a means to log in. An import user is disabled, has no means to log in, and is marked as an import user."
},
"profile": {
"$ref": "#/components/schemas/Profile"
},
"disabled": {
"type": "boolean",
"description": "True/false boolean indicating whether the Member has been disabled within the Workspace."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"group_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The Member's group ids"
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Member was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Member was last updated."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"replaced_by": {
"type": "string",
"format": "uuid",
"x-doc-skip": true,
"description": "The id of the member that replaces this one when merged."
},
"created_without_invite": {
"type": "boolean",
"x-doc-skip": true,
"description": "Whether this member was created as a placeholder entity."
}
},
"description": "Details about an individual user within the Workspace."
}
MemberInfo
{
"type": "object",
"required": [
"id",
"name",
"mention_name",
"workspace2"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"workspace2": {
"$ref": "#/components/schemas/BasicWorkspaceInfo"
},
"mention_name": {
"type": "string"
}
}
}
MemberListWorkspaceMembersResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Member"
}
}
Milestone
{
"type": "object",
"required": [
"app_url",
"description",
"archived",
"started",
"entity_type",
"completed_at_override",
"started_at",
"completed_at",
"name",
"global_id",
"completed",
"state",
"started_at_override",
"updated_at",
"categories",
"id",
"key_result_ids",
"position",
"stats",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Milestone."
},
"name": {
"type": "string",
"description": "The name of the Milestone."
},
"state": {
"type": "string",
"description": "The workflow state that the Milestone is in."
},
"stats": {
"$ref": "#/components/schemas/MilestoneStats"
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Milestone."
},
"started": {
"type": "boolean",
"description": "A true/false boolean indicating if the Milestone has been started."
},
"archived": {
"type": "boolean",
"description": "A boolean indicating whether the Milestone has been archived or not."
},
"position": {
"type": "integer",
"format": "int64",
"description": "A number representing the position of the Milestone in relation to every other Milestone within the Workspace."
},
"completed": {
"type": "boolean",
"description": "A true/false boolean indicating if the Milestone has been completed."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
},
"description": "An array of Categories attached to the Milestone."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the Milestone was created."
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Milestone was started."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the Milestone was updated."
},
"description": {
"type": "string",
"description": "The Milestone's description."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"completed_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Milestone was completed."
},
"key_result_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The IDs of the Key Results associated with the Objective."
},
"started_at_override": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "A manual override for the time/date the Milestone was started."
},
"completed_at_override": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "A manual override for the time/date the Milestone was completed."
}
},
"description": "A Milestone is a collection of Epics that represent a release or some other large initiative that you are working on."
}
MilestoneListAllAttributesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Milestone"
}
}
MilestoneStats
{
"type": "object",
"required": [
"num_related_documents"
],
"properties": {
"average_lead_time": {
"type": "integer",
"format": "int64",
"description": "The average lead time (in seconds) of completed stories in this Milestone."
},
"average_cycle_time": {
"type": "integer",
"format": "int64",
"description": "The average cycle time (in seconds) of completed stories in this Milestone."
},
"num_related_documents": {
"type": "integer",
"format": "int64",
"description": "The number of related documents to this Milestone."
}
},
"description": "A group of calculated values for this Milestone."
}
Objective
{
"type": "object",
"required": [
"app_url",
"description",
"archived",
"started",
"entity_type",
"completed_at_override",
"started_at",
"completed_at",
"name",
"global_id",
"completed",
"state",
"started_at_override",
"updated_at",
"categories",
"id",
"key_result_ids",
"position",
"stats",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Objective."
},
"name": {
"type": "string",
"description": "The name of the Objective."
},
"state": {
"type": "string",
"description": "The workflow state that the Objective is in."
},
"stats": {
"$ref": "#/components/schemas/ObjectiveStats"
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Objective."
},
"started": {
"type": "boolean",
"description": "A true/false boolean indicating if the Objective has been started."
},
"archived": {
"type": "boolean",
"description": "A boolean indicating whether the Objective has been archived or not."
},
"position": {
"type": "integer",
"format": "int64",
"description": "A number representing the position of the Objective in relation to every other Objective within the Workspace."
},
"completed": {
"type": "boolean",
"description": "A true/false boolean indicating if the Objectivehas been completed."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
},
"description": "An array of Categories attached to the Objective."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the Objective was created."
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Objective was started."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the Objective was updated."
},
"description": {
"type": "string",
"description": "The Objective's description."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"completed_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Objective was completed."
},
"key_result_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The IDs of the Key Results associated with the Objective."
},
"started_at_override": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "A manual override for the time/date the Objective was started."
},
"completed_at_override": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "A manual override for the time/date the Objective was completed."
}
},
"description": "An Objective is a collection of Epics that represent a release or some other large initiative that you are working on."
}
ObjectiveListAllResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Objective"
}
}
ObjectiveSearchResult
{
"type": "object",
"required": [
"app_url",
"archived",
"started",
"entity_type",
"completed_at_override",
"started_at",
"completed_at",
"name",
"global_id",
"completed",
"state",
"started_at_override",
"updated_at",
"categories",
"id",
"key_result_ids",
"position",
"stats",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Milestone."
},
"name": {
"type": "string",
"description": "The name of the Milestone."
},
"state": {
"type": "string",
"description": "The workflow state that the Milestone is in."
},
"stats": {
"$ref": "#/components/schemas/MilestoneStats"
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Milestone."
},
"started": {
"type": "boolean",
"description": "A true/false boolean indicating if the Milestone has been started."
},
"archived": {
"type": "boolean",
"description": "A boolean indicating whether the Milestone has been archived or not."
},
"position": {
"type": "integer",
"format": "int64",
"description": "A number representing the position of the Milestone in relation to every other Milestone within the Workspace."
},
"completed": {
"type": "boolean",
"description": "A true/false boolean indicating if the Milestone has been completed."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
},
"description": "An array of Categories attached to the Milestone."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the Milestone was created."
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Milestone was started."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the Milestone was updated."
},
"description": {
"type": "string",
"description": "The Milestone's description."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"completed_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Milestone was completed."
},
"key_result_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The IDs of the Key Results associated with the Objective."
},
"started_at_override": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "A manual override for the time/date the Milestone was started."
},
"completed_at_override": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "A manual override for the time/date the Milestone was completed."
}
},
"description": "A Milestone in search results. This is typed differently from Milestone because the details=slim search argument will omit some fields."
}
ObjectiveSearchResults
{
"type": "object",
"required": [
"total",
"data",
"next"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ObjectiveSearchResult"
},
"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 Objective search query."
}
ObjectiveStats
{
"type": "object",
"required": [
"num_related_documents"
],
"properties": {
"average_lead_time": {
"type": "integer",
"format": "int64",
"description": "The average lead time (in seconds) of completed stories in this Objective."
},
"average_cycle_time": {
"type": "integer",
"format": "int64",
"description": "The average cycle time (in seconds) of completed stories in this Objective."
},
"num_related_documents": {
"type": "integer",
"format": "int64",
"description": "The number of related documents to this Objective."
}
},
"description": "A group of calculated values for this Objective."
}
Profile
{
"type": "object",
"required": [
"entity_type",
"deactivated",
"mention_name",
"name",
"gravatar_hash",
"id",
"display_icon",
"is_owner",
"email_address"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The unique identifier of the profile."
},
"name": {
"type": "string",
"nullable": true,
"description": "The Member's name within the Organization."
},
"is_owner": {
"type": "boolean",
"description": "A boolean indicating whether this profile is an owner at their associated organization."
},
"deactivated": {
"type": "boolean",
"description": "A true/false boolean indicating whether the Member has been deactivated within Shortcut."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"display_icon": {
"$ref": "#/components/schemas/Icon"
},
"mention_name": {
"type": "string",
"description": "The Member's username within the Organization."
},
"email_address": {
"type": "string",
"nullable": true,
"description": "The primary email address of the Member with the Organization."
},
"gravatar_hash": {
"type": "string",
"nullable": true,
"description": "This is the gravatar hash associated with email_address."
},
"two_factor_auth_activated": {
"type": "boolean",
"description": "If Two Factor Authentication is activated for this User."
}
},
"description": "A group of Member profile details."
}
Project
{
"type": "object",
"required": [
"app_url",
"description",
"archived",
"entity_type",
"days_to_thermometer",
"color",
"workflow_id",
"name",
"global_id",
"start_time",
"updated_at",
"follower_ids",
"external_id",
"id",
"show_thermometer",
"team_id",
"iteration_length",
"abbreviation",
"stats",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Project."
},
"name": {
"type": "string",
"description": "The name of the Project"
},
"color": {
"type": "string",
"format": "css-color",
"pattern": "^#[a-fA-F0-9]{6}$",
"nullable": true,
"minLength": 1,
"description": "The color associated with the Project in the Shortcut member interface."
},
"stats": {
"$ref": "#/components/schemas/ProjectStats"
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Project."
},
"team_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the team the project belongs to."
},
"archived": {
"type": "boolean",
"description": "True/false boolean indicating whether the Project is in an Archived state."
},
"global_id": {
"type": "string",
"x-doc-skip": true,
"description": "The Global ID of the Project."
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date that the Project was created."
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "The date at which the Project was started."
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date that the Project was last updated."
},
"description": {
"type": "string",
"nullable": true,
"description": "The description of the Project."
},
"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 Project has been imported from another tool, the ID in the other tool can be indicated here."
},
"workflow_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the workflow the project belongs to."
},
"abbreviation": {
"type": "string",
"nullable": true,
"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 listed as Followers."
},
"iteration_length": {
"type": "integer",
"format": "int64",
"description": "The number of weeks per iteration in this Project."
},
"show_thermometer": {
"type": "boolean",
"description": "Configuration to enable or disable thermometers in the Story summary."
},
"days_to_thermometer": {
"type": "integer",
"format": "int64",
"description": "The number of days before the thermometer appears in the Story summary."
}
},
"description": "Projects typically map to teams (such as Frontend, Backend, Mobile, Devops, etc) but can represent any open-ended product, component, or initiative."
}
ProjectGetAllResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Project"
}
}
ProjectListStoriesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
ProjectStats
{
"type": "object",
"required": [
"num_stories",
"num_points",
"num_related_documents"
],
"properties": {
"num_points": {
"type": "integer",
"format": "int64",
"description": "The total number of points in this Project."
},
"num_stories": {
"type": "integer",
"format": "int64",
"description": "The total number of stories in this Project."
},
"num_related_documents": {
"type": "integer",
"format": "int64",
"description": "The total number of documents related to this Project"
}
},
"description": "A group of calculated values for this Project."
}
PullRequest
{
"type": "object",
"required": [
"entity_type",
"closed",
"merged",
"num_added",
"branch_id",
"number",
"branch_name",
"target_branch_name",
"num_commits",
"title",
"updated_at",
"has_overlapping_stories",
"draft",
"id",
"url",
"num_removed",
"num_modified",
"target_branch_id",
"repository_id",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID associated with the pull request in Shortcut."
},
"url": {
"type": "string",
"description": "The URL for the pull request."
},
"draft": {
"type": "boolean",
"description": "True/False boolean indicating whether the VCS pull request is in the draft state."
},
"title": {
"type": "string",
"description": "The title of the pull request."
},
"closed": {
"type": "boolean",
"description": "True/False boolean indicating whether the VCS pull request has been closed."
},
"merged": {
"type": "boolean",
"description": "True/False boolean indicating whether the VCS pull request has been merged."
},
"number": {
"type": "integer",
"format": "int64",
"description": "The pull request's unique number ID in VCS."
},
"branch_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the branch for the particular pull request."
},
"num_added": {
"type": "integer",
"format": "int64",
"description": "Number of lines added in the pull request, according to VCS."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the pull request was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the pull request was created."
},
"vcs_labels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PullRequestLabel"
},
"nullable": true,
"description": "An array of PullRequestLabels attached to the PullRequest."
},
"branch_name": {
"type": "string",
"description": "The name of the branch for the particular pull request."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"num_commits": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The number of commits on the pull request."
},
"num_removed": {
"type": "integer",
"format": "int64",
"description": "Number of lines removed in the pull request, according to VCS."
},
"build_status": {
"type": "string",
"description": "The status of the Continuous Integration workflow for the pull request."
},
"num_modified": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Number of lines modified in the pull request, according to VCS."
},
"repository_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the repository for the particular pull request."
},
"review_status": {
"type": "string",
"description": "The status of the review for the pull request."
},
"target_branch_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the target branch for the particular pull request."
},
"target_branch_name": {
"type": "string",
"description": "The name of the target branch for the particular pull request."
},
"overlapping_stories": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "An array of Story ids that have Pull Requests that change at least one of the same lines this Pull Request changes."
},
"has_overlapping_stories": {
"type": "boolean",
"description": "Boolean indicating that the Pull Request has Stories that have Pull Requests that change at least one of the same lines this Pull Request changes."
}
},
"description": "Corresponds to a VCS Pull Request attached to a Shortcut story."
}
PullRequestLabel
{
"type": "object",
"required": [
"entity_type",
"id",
"color",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the VCS Label."
},
"name": {
"type": "string",
"description": "The name of the VCS label."
},
"color": {
"type": "string",
"format": "css-color",
"pattern": "^#[a-fA-F0-9]{6}$",
"minLength": 1,
"description": "The color of the VCS label."
},
"description": {
"type": "string",
"nullable": true,
"description": "The description of the VCS label."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
}
},
"description": "Corresponds to a VCS Label associated with a Pull Request."
}
RemoveCustomFieldParams
{
"type": "object",
"required": [
"field_id"
],
"properties": {
"field_id": {
"type": "string",
"format": "uuid",
"description": "The unique public ID for the CustomField."
}
}
}
RemoveLabelParams
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"description": "The name of the new Label to remove."
}
},
"description": "Request parameters for removing a Label from a Shortcut Story."
}
Repository
{
"type": "object",
"required": [
"entity_type",
"name",
"type",
"updated_at",
"external_id",
"id",
"url",
"full_name",
"created_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The ID associated to the VCS repository in Shortcut."
},
"url": {
"type": "string",
"nullable": true,
"description": "The URL of the Repository."
},
"name": {
"type": "string",
"nullable": true,
"description": "The shorthand name of the VCS repository."
},
"type": {
"enum": [
"github",
"gitlab",
"bitbucket"
],
"type": "string",
"description": "The VCS provider for the Repository."
},
"full_name": {
"type": "string",
"nullable": true,
"description": "The full name of the VCS repository."
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Repository was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Repository was updated."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"external_id": {
"type": "string",
"nullable": true,
"description": "The VCS unique identifier for the Repository."
}
},
"description": "Repository refers to a VCS repository."
}
RepositoryListAllResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Repository"
}
}
SearchResults
{
"type": "object",
"properties": {
"epics": {
"$ref": "#/components/schemas/EpicSearchResults"
},
"stories": {
"$ref": "#/components/schemas/StorySearchResults"
},
"iterations": {
"$ref": "#/components/schemas/IterationSearchResults"
},
"milestones": {
"$ref": "#/components/schemas/ObjectiveSearchResults"
}
},
"description": "The results of the multi-entity search query."
}
SearchStories
{
"type": "object",
"properties": {
"epic_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The Epic IDs that may be associated with the Stories."
},
"archived": {
"type": "boolean",
"description": "A true/false boolean indicating whether the Story is in archived state."
},
"epic_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "The Epic IDs that may be associated with the Stories.",
"uniqueItems": true
},
"estimate": {
"type": "integer",
"format": "int64",
"description": "The number of estimate points associate with the Stories."
},
"group_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "The Group ID that is associated with the Stories"
},
"owner_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "An array of UUIDs for any Users who may be Owners of the Stories."
},
"group_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The Group IDs that are associated with the Stories",
"uniqueItems": true
},
"label_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "The Label IDs that may be associated with the Stories.",
"uniqueItems": true
},
"owner_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of UUIDs for any Users who may be Owners of the Stories.",
"uniqueItems": true
},
"label_name": {
"type": "string",
"minLength": 1,
"description": "The name of any associated Labels."
},
"project_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The IDs for the Projects the Stories may be assigned to."
},
"story_type": {
"enum": [
"feature",
"chore",
"bug"
],
"type": "string",
"description": "The type of Stories that you want returned."
},
"external_id": {
"type": "string",
"description": "An ID or URL that references an external resource. Useful during imports."
},
"project_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64",
"nullable": true
},
"description": "The IDs for the Projects the Stories may be assigned to.",
"uniqueItems": true
},
"deadline_end": {
"type": "string",
"format": "date-time",
"description": "Stories should have a deadline on or before this date."
},
"iteration_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The Iteration ID that may be associated with the Stories."
},
"iteration_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "The Iteration IDs that may be associated with the Stories.",
"uniqueItems": true
},
"created_at_end": {
"type": "string",
"format": "date-time",
"description": "Stories should have been created on or before this date."
},
"deadline_start": {
"type": "string",
"format": "date-time",
"description": "Stories should have a deadline on or after this date."
},
"updated_at_end": {
"type": "string",
"format": "date-time",
"description": "Stories should have been updated on or before this date."
},
"requested_by_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of any Users who may have requested the Stories."
},
"completed_at_end": {
"type": "string",
"format": "date-time",
"description": "Stories should have been completed on or before this date."
},
"created_at_start": {
"type": "string",
"format": "date-time",
"description": "Stories should have been created on or after this date."
},
"updated_at_start": {
"type": "string",
"format": "date-time",
"description": "Stories should have been updated on or after this date."
},
"workflow_state_id": {
"type": "integer",
"format": "int64",
"description": "The unique IDs of the specific Workflow States that the Stories should be in."
},
"completed_at_start": {
"type": "string",
"format": "date-time",
"description": "Stories should have been completed on or after this date."
},
"includes_description": {
"type": "boolean",
"description": "Whether to include the story description in the response."
},
"workflow_state_types": {
"type": "array",
"items": {
"enum": [
"started",
"backlog",
"unstarted",
"done"
],
"type": "string"
},
"description": "The type of Workflow State the Stories may be in."
}
},
"x-doc-skip": true
}
SearchStoriesOldResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
Story
{
"type": "object",
"required": [
"app_url",
"description",
"archived",
"started",
"story_links",
"entity_type",
"labels",
"mention_ids",
"member_mention_ids",
"story_type",
"linked_files",
"workflow_id",
"completed_at_override",
"started_at",
"completed_at",
"name",
"global_id",
"completed",
"comments",
"blocker",
"branches",
"epic_id",
"story_template_id",
"external_links",
"previous_iteration_ids",
"requested_by_id",
"iteration_id",
"tasks",
"label_ids",
"started_at_override",
"group_id",
"workflow_state_id",
"updated_at",
"pull_requests",
"group_mention_ids",
"follower_ids",
"owner_ids",
"external_id",
"id",
"estimate",
"commits",
"files",
"position",
"blocked",
"project_id",
"deadline",
"stats",
"created_at",
"moved_at"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Story."
},
"name": {
"type": "string",
"description": "The name of the story."
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadedFile"
},
"description": "An array of files attached to the story."
},
"stats": {
"$ref": "#/components/schemas/StoryStats"
},
"tasks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Task"
},
"description": "An array of tasks connected to the story."
},
"labels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LabelSlim"
},
"description": "An array of labels attached to the story."
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Story."
},
"blocked": {
"type": "boolean",
"description": "A true/false boolean indicating if the Story is currently blocked."
},
"blocker": {
"type": "boolean",
"description": "A true/false boolean indicating if the Story is currently a blocker of another story."
},
"commits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Commit"
},
"description": "An array of commits attached to the story."
},
"epic_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The ID of the epic the story belongs to."
},
"started": {
"type": "boolean",
"description": "A true/false boolean indicating if the Story has been started."
},
"archived": {
"type": "boolean",
"description": "True if the story has been archived or not."
},
"branches": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Branch"
},
"description": "An array of Git branches attached to the story."
},
"comments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryComment"
},
"description": "An array of comments attached 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."
},
"group_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "The ID of the group associated with the story."
},
"moved_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Story was last changed workflow-state."
},
"position": {
"type": "integer",
"format": "int64",
"description": "A number representing the position of the story in relation to every other story in the current project."
},
"completed": {
"type": "boolean",
"description": "A true/false boolean indicating if the Story has been completed."
},
"global_id": {
"type": "string",
"x-doc-skip": true
},
"label_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "An array of label ids attached to the story."
},
"lead_time": {
"type": "integer",
"format": "int64",
"description": "The lead time (in seconds) of this story when complete."
},
"owner_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of UUIDs of the owners of this story."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The time/date the Story was created."
},
"cycle_time": {
"type": "integer",
"format": "int64",
"description": "The cycle time (in seconds) of this story when complete."
},
"project_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The ID of the project the story belongs to."
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Story was started."
},
"story_type": {
"type": "string",
"description": "The type of story (feature, bug, chore)."
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Story was updated."
},
"description": {
"type": "string",
"description": "The description of the story."
},
"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 Story 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."
},
"story_links": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TypedStoryLink"
},
"description": "An array of story links attached to the Story."
},
"synced_item": {
"$ref": "#/components/schemas/SyncedItem"
},
"workflow_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the workflow the story belongs to."
},
"completed_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date the Story was completed."
},
"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 story belongs to."
},
"linked_files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LinkedFile"
},
"description": "An array of linked files attached to the story."
},
"custom_fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryCustomField"
},
"description": "An array of CustomField value assertions for the story."
},
"pull_requests": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PullRequest"
},
"description": "An array of Pull/Merge Requests attached to the story."
},
"external_links": {
"type": "array",
"items": {
"type": "string"
},
"description": "An array of external links (strings) associated with a Story"
},
"requested_by_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the Member that requested the story."
},
"group_mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of Group IDs that have been mentioned in the Story description."
},
"story_template_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "The ID of the story template used to create this story, or null if not created using a template."
},
"workflow_state_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the workflow state the story is currently in."
},
"member_mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of Member IDs that have been mentioned in the Story description."
},
"started_at_override": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "A manual override for the time/date the Story was started."
},
"completed_at_override": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "A manual override for the time/date the Story was completed."
},
"previous_iteration_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "The IDs of the iteration the story belongs to."
},
"unresolved_blocker_comments": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "The IDs of any unresolved blocker comments on the Story."
}
},
"description": "Stories are the standard unit of work in Shortcut and represent individual features, bugs, and chores."
}
StoryAddReactionResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryReaction"
}
}
StoryComment
{
"type": "object",
"required": [
"app_url",
"entity_type",
"deleted",
"story_id",
"mention_ids",
"author_id",
"member_mention_ids",
"updated_at",
"group_mention_ids",
"external_id",
"id",
"position",
"reactions",
"created_at",
"text"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The unique ID of the Comment."
},
"text": {
"type": "string",
"nullable": true,
"description": "The text of the Comment. In the case that the Comment has been deleted, this field can be set to nil."
},
"app_url": {
"type": "string",
"description": "The Shortcut application url for the Comment."
},
"blocker": {
"type": "boolean",
"description": "Marks the comment as a blocker that can be surfaced to permissions or teams mentioned in the comment. Can only be used on a top-level comment."
},
"deleted": {
"type": "boolean",
"description": "True/false boolean indicating whether the Comment has been deleted."
},
"position": {
"type": "integer",
"format": "int64",
"description": "The Comments numerical position in the list from oldest to newest."
},
"story_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the Story on which the Comment appears."
},
"author_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "The unique ID of the Member who is the Comment's author."
},
"parent_id": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The ID of the parent Comment this Comment is threaded under."
},
"reactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryReaction"
},
"x-doc-skip": true,
"description": "A set of Reactions to this Comment."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The time/date when the Comment was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The time/date when the Comment 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 Comment 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."
},
"unblocks_parent": {
"type": "boolean",
"description": "Marks the comment as an unblocker to its blocker parent. Can only be set on a threaded comment who has a parent with `blocker` set."
},
"group_mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The unique IDs of the Group who are mentioned in the Comment."
},
"member_mention_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The unique IDs of the Member who are mentioned in the Comment."
}
},
"description": "A Comment is any note added within the Comment field of a Story."
}
StoryContents
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the story."
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadedFile"
},
"description": "An array of files attached to the story."
},
"tasks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryContentsTask"
},
"description": "An array of tasks connected to the story."
},
"labels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LabelSlim"
},
"description": "An array of labels attached to the story."
},
"epic_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the epic the story belongs to."
},
"deadline": {
"type": "string",
"format": "date-time",
"description": "The due date of the story."
},
"estimate": {
"type": "integer",
"format": "int64",
"description": "The numeric point estimate of the story. Can also be null, which means unestimated."
},
"group_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the group to which the story is assigned."
},
"label_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "An array of label ids attached to the story."
},
"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."
},
"entity_type": {
"type": "string",
"description": "A string description of this resource."
},
"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",
"description": "The ID of the iteration the story belongs to."
},
"linked_files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LinkedFile"
},
"description": "An array of linked files attached to the story."
},
"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 connected to the story."
},
"workflow_state_id": {
"type": "integer",
"format": "int64",
"description": "The ID of the workflow state the story is currently in."
}
},
"description": "A container entity for the attributes this template should populate."
}
StoryContentsTask
{
"type": "object",
"required": [
"description"
],
"properties": {
"complete": {
"type": "boolean",
"description": "True/false boolean indicating whether the Task has been completed."
},
"position": {
"type": "integer",
"format": "int64",
"description": "The number corresponding to the Task's position within a list of Tasks on a Story."
},
"owner_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "An array of UUIDs of the Owners of this Task."
},
"description": {
"type": "string",
"description": "Full text of the Task."
},
"external_id": {
"type": "string",
"nullable": true,
"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."
}
}
}
StoryCreateMultipleResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
StoryCustomField
{
"type": "object",
"required": [
"field_id",
"value_id",
"value"
],
"properties": {
"value": {
"type": "string",
"description": "A string representation of the value, if applicable."
},
"field_id": {
"type": "string",
"format": "uuid",
"description": "The unique public ID for a CustomField."
},
"value_id": {
"type": "string",
"format": "uuid",
"description": "The unique public ID for a CustomFieldEnumValue."
}
}
}
StoryGetHistoryResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/History"
}
}
StoryHistoryChangeAddsRemovesInt
{
"type": "object",
"properties": {
"adds": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "The values that have been added."
},
"removes": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "The values that have been removed"
}
},
"description": "Task IDs that have been added or removed from the Story."
}
StoryHistoryChangeAddsRemovesUuid
{
"type": "object",
"properties": {
"adds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The values that have been added."
},
"removes": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The values that have been removed"
}
},
"description": "Custom Field Enum Value IDs that have been added or removed from the Story."
}
StoryHistoryChangeOldNewBool
{
"type": "object",
"properties": {
"new": {
"type": "boolean",
"description": "The new value."
},
"old": {
"type": "boolean",
"description": "The old value."
}
},
"description": "True if the Story has archived, otherwise false."
}