shortcut-openapi.json•538 kB
{
"openapi": "3.0.0",
"security": [
{
"api_token": []
}
],
"paths": {
"/api/v3/categories": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listCategories",
"description": "List Categories returns a list of all Categories and their attributes.",
"summary": "List Categories"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCategory"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Category"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createCategory",
"description": "Create Category allows you to create a new Category in Shortcut.",
"summary": "Create Category"
}
},
"/api/v3/categories/{category-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "category-public-id",
"description": "The unique ID of the Category.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Category"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getCategory",
"description": "Get Category returns information about the selected Category.",
"summary": "Get Category"
},
"put": {
"parameters": [
{
"in": "path",
"name": "category-public-id",
"description": "The unique ID of the Category you wish to update.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateCategory"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Category"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateCategory",
"description": "Update Category allows you to replace a Category name with another name. If you try to name a Category something that already exists, you will receive a 422 response.",
"summary": "Update Category"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "category-public-id",
"description": "The unique ID of the Category.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteCategory",
"description": "Delete Category can be used to delete any Category.",
"summary": "Delete Category"
}
},
"/api/v3/categories/{category-public-id}/milestones": {
"get": {
"parameters": [
{
"in": "path",
"name": "category-public-id",
"description": "The unique ID of the Category.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Milestone"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listCategoryMilestones",
"description": "List Category Milestones returns a list of all Milestones with the Category.",
"summary": "List Category Milestones"
}
},
"/api/v3/categories/{category-public-id}/objectives": {
"get": {
"parameters": [
{
"in": "path",
"name": "category-public-id",
"description": "The unique ID of the Category.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Milestone"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listCategoryObjectives",
"description": "Returns a list of all Objectives with the Category.",
"summary": "List Category Objectives"
}
},
"/api/v3/custom-fields": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomField"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listCustomFields",
"summary": "List Custom Fields"
}
},
"/api/v3/custom-fields/{custom-field-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "custom-field-public-id",
"description": "The unique ID of the CustomField.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomField"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getCustomField",
"summary": "Get Custom Field"
},
"put": {
"parameters": [
{
"in": "path",
"name": "custom-field-public-id",
"description": "The unique ID of the CustomField.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateCustomField"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomField"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DataConflictError"
}
}
}
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateCustomField",
"description": "Update Custom Field can be used to update the definition of a Custom Field. The order of items in the 'values' collection is interpreted to be their ascending sort order.To delete an existing enum value, simply omit it from the 'values' collection. New enum values may be created inline by including an object in the 'values' collection having a 'value' entry with no 'id' (eg. {'value': 'myNewValue', 'color_key': 'green'}).",
"summary": "Update Custom Field"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "custom-field-public-id",
"description": "The unique ID of the CustomField.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteCustomField",
"summary": "Delete Custom Field"
}
},
"/api/v3/documents": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocSlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisabledFeatureError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listDocs",
"description": "List Docs returns a list of Doc that the current user can read.",
"summary": "List Docs"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDoc"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocSlim"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisabledFeatureError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createDoc",
"description": "Creates a new Doc.",
"summary": "Create Doc"
}
},
"/api/v3/entity-templates": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityTemplate"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listEntityTemplates",
"description": "List all the entity templates for the Workspace.",
"summary": "List Entity Templates"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEntityTemplate"
}
}
},
"description": "Request parameters for creating an entirely new entity template.",
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityTemplate"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createEntityTemplate",
"description": "Create a new entity template for the Workspace.",
"summary": "Create Entity Template"
}
},
"/api/v3/entity-templates/disable": {
"put": {
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "disableStoryTemplates",
"description": "Disables the Story Template feature for the Workspace.",
"summary": "Disable Story Templates"
}
},
"/api/v3/entity-templates/enable": {
"put": {
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "enableStoryTemplates",
"description": "Enables the Story Template feature for the Workspace.",
"summary": "Enable Story Templates"
}
},
"/api/v3/entity-templates/{entity-template-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "entity-template-public-id",
"description": "The unique ID of the entity template.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityTemplate"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getEntityTemplate",
"description": "Get Entity Template returns information about a given entity template.",
"summary": "Get Entity Template"
},
"put": {
"parameters": [
{
"in": "path",
"name": "entity-template-public-id",
"description": "The unique ID of the template to be updated.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateEntityTemplate"
}
}
},
"description": "Request parameters for changing either a template's name or any of\n the attributes it is designed to pre-populate.",
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityTemplate"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateEntityTemplate",
"description": "Update an entity template's name or its contents.",
"summary": "Update Entity Template"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "entity-template-public-id",
"description": "The unique ID of the entity template.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteEntityTemplate",
"summary": "Delete Entity Template"
}
},
"/api/v3/epic-workflow": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EpicWorkflow"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getEpicWorkflow",
"description": "Returns the Epic Workflow for the Workspace.",
"summary": "Get Epic Workflow"
}
},
"/api/v3/epics": {
"get": {
"parameters": [
{
"in": "query",
"name": "includes_description",
"description": "A true/false boolean indicating whether to return Epics with their descriptions.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicSlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listEpics",
"description": "List Epics returns a list of all Epics and their attributes.",
"summary": "List Epics"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEpic"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Epic"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createEpic",
"description": "Create Epic allows you to create a new Epic in Shortcut.",
"summary": "Create Epic"
}
},
"/api/v3/epics/paginated": {
"get": {
"parameters": [
{
"in": "query",
"name": "includes_description",
"description": "A true/false boolean indicating whether to return Epics with their descriptions.",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "page",
"description": "The page number to return, starting with 1. Defaults to 1.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "page_size",
"description": "The number of Epics to return per page. Minimum 1, maximum 250, default 10.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EpicPaginatedResults"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listEpicsPaginated",
"description": "List Epics with pagination returns a paginated list of Epics and their attributes.",
"summary": "List Epics Paginated"
}
},
"/api/v3/epics/{epic-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The unique ID of the Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Epic"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getEpic",
"description": "Get Epic returns information about the selected Epic.",
"summary": "Get Epic"
},
"put": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The unique ID of the Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateEpic"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Epic"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateEpic",
"description": "Update Epic can be used to update numerous fields in the Epic. The only required parameter is Epic ID, which can be found in the Shortcut UI.",
"summary": "Update Epic"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The unique ID of the Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteEpic",
"description": "Delete Epic can be used to delete the Epic. The only required parameter is Epic ID.",
"summary": "Delete Epic"
}
},
"/api/v3/epics/{epic-public-id}/comments": {
"get": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The unique ID of the Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ThreadedComment"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listEpicComments",
"description": "Get a list of all Comments on an Epic.",
"summary": "List Epic Comments"
},
"post": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The ID of the associated Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEpicComment"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadedComment"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createEpicComment",
"description": "This endpoint allows you to create a threaded Comment on an Epic.",
"summary": "Create Epic Comment"
}
},
"/api/v3/epics/{epic-public-id}/comments/{comment-public-id}": {
"post": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The ID of the associated Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the parent Epic Comment.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCommentComment"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadedComment"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createEpicCommentComment",
"description": "This endpoint allows you to create a nested Comment reply to an existing Epic Comment.",
"summary": "Create Epic Comment Comment"
},
"get": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The ID of the associated Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the Comment.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadedComment"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getEpicComment",
"description": "This endpoint returns information about the selected Epic Comment.",
"summary": "Get Epic Comment"
},
"put": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The ID of the associated Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the Comment.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateComment"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadedComment"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateEpicComment",
"description": "This endpoint allows you to update a threaded Comment on an Epic.",
"summary": "Update Epic Comment"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The ID of the associated Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the Comment.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteEpicComment",
"description": "This endpoint allows you to delete a Comment from an Epic.",
"summary": "Delete Epic Comment"
}
},
"/api/v3/epics/{epic-public-id}/health": {
"get": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The unique ID of the Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getEpicHealth",
"description": "Get the current health for the specified Epic.",
"summary": "Get Epic Health"
},
"post": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The unique ID of the Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateEpicHealth"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createEpicHealth",
"description": "Create a new health status for the specified Epic.",
"summary": "Create Epic Health"
}
},
"/api/v3/epics/{epic-public-id}/health-history": {
"get": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The unique ID of the Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Health"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listEpicHealths",
"description": "List the history of health statuses for the specified Epic, most recent first.",
"summary": "List Epic Healths"
}
},
"/api/v3/epics/{epic-public-id}/stories": {
"get": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The unique ID of the Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "includes_description",
"description": "A true/false boolean indicating whether to return Stories with their descriptions.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listEpicStories",
"description": "Get a list of all Stories in an Epic.",
"summary": "List Epic Stories"
}
},
"/api/v3/epics/{epic-public-id}/unlink-productboard": {
"post": {
"parameters": [
{
"in": "path",
"name": "epic-public-id",
"description": "The unique ID of the Epic.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "unlinkProductboardFromEpic",
"description": "This endpoint allows you to unlink a productboard epic.",
"summary": "Unlink Productboard from Epic"
}
},
"/api/v3/external-link/stories": {
"get": {
"parameters": [
{
"in": "query",
"name": "external_link",
"description": "The external link associated with one or more stories.",
"required": true,
"schema": {
"type": "string",
"maxLength": 2048,
"pattern": "^https?://.+$"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getExternalLinkStories",
"description": "Get Stories which have a given External Link associated with them.",
"summary": "Get External Link Stories"
}
},
"/api/v3/files": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadedFile"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listFiles",
"description": "List Files returns a list of all UploadedFiles in the workspace.",
"summary": "List Files"
},
"post": {
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"story_id": {
"description": "The story ID that these files will be associated with.",
"type": "integer",
"format": "int64"
},
"file0": {
"description": "A file upload. At least one is required.",
"type": "string",
"format": "binary"
},
"file1": {
"description": "Optional additional files.",
"type": "string",
"format": "binary"
},
"file2": {
"description": "Optional additional files.",
"type": "string",
"format": "binary"
},
"file3": {
"description": "Optional additional files.",
"type": "string",
"format": "binary"
}
},
"required": [
"file0"
]
}
}
}
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadedFile"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "uploadFiles",
"description": "Upload Files uploads one or many files and optionally associates them with a story.\n Use the multipart/form-data content-type to upload.\n Each `file` key should contain a separate file.\n Each UploadedFile's name comes from the Content-Disposition header \"filename\" directive for that field.",
"summary": "Upload Files"
}
},
"/api/v3/files/{file-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "file-public-id",
"description": "The File’s unique ID.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadedFile"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getFile",
"description": "Get File returns information about the selected UploadedFile.",
"summary": "Get File"
},
"put": {
"parameters": [
{
"in": "path",
"name": "file-public-id",
"description": "The unique ID assigned to the file in Shortcut.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateFile"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadedFile"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateFile",
"description": "Update File updates the properties of an UploadedFile (but not its content).",
"summary": "Update File"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "file-public-id",
"description": "The File’s unique ID.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteFile",
"description": "Delete File deletes a previously uploaded file.",
"summary": "Delete File"
}
},
"/api/v3/groups": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Group"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listGroups",
"description": "A group in our API maps to a \"Team\" within the Shortcut Product. A Team is a collection of Users that can be associated to Stories, Epics, and Iterations within Shortcut.",
"summary": "List Groups"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateGroup"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Group"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnusableEntitlementError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createGroup",
"summary": "Create Group"
}
},
"/api/v3/groups/{group-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "group-public-id",
"description": "The unique ID of the Group.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Group"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getGroup",
"summary": "Get Group"
},
"put": {
"parameters": [
{
"in": "path",
"name": "group-public-id",
"description": "The unique ID of the Group.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateGroup"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Group"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnusableEntitlementError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateGroup",
"summary": "Update Group"
}
},
"/api/v3/groups/{group-public-id}/stories": {
"get": {
"parameters": [
{
"in": "path",
"name": "group-public-id",
"description": "The unique ID of the Group.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "limit",
"description": "The maximum number of results to return. (Defaults to 1000, max 1000)",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "offset",
"description": "The offset at which to begin returning results. (Defaults to 0)",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listGroupStories",
"description": "List the Stories assigned to the Group. (By default, limited to 1,000).",
"summary": "List Group Stories"
}
},
"/api/v3/health/{health-public-id}": {
"put": {
"parameters": [
{
"in": "path",
"name": "health-public-id",
"description": "The unique ID of the Health record.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateHealth"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateHealth",
"description": "Update an existing health status by its ID.",
"summary": "Update Health"
}
},
"/api/v3/integrations/webhook": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateGenericIntegration"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createGenericIntegration",
"summary": "Create Generic Integration"
}
},
"/api/v3/integrations/webhook/{integration-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "integration-public-id",
"description": "",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getGenericIntegration",
"summary": "Get Generic Integration"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "integration-public-id",
"description": "",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteGenericIntegration",
"summary": "Delete Generic Integration"
}
},
"/api/v3/iterations": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IterationSlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listIterations",
"summary": "List Iterations"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateIteration"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Iteration"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createIteration",
"summary": "Create Iteration"
}
},
"/api/v3/iterations/disable": {
"put": {
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "disableIterations",
"description": "Disables Iterations for the current workspace",
"summary": "Disable Iterations"
}
},
"/api/v3/iterations/enable": {
"put": {
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "enableIterations",
"description": "Enables Iterations for the current workspace",
"summary": "Enable Iterations"
}
},
"/api/v3/iterations/{iteration-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "iteration-public-id",
"description": "The unique ID of the Iteration.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Iteration"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getIteration",
"summary": "Get Iteration"
},
"put": {
"parameters": [
{
"in": "path",
"name": "iteration-public-id",
"description": "The unique ID of the Iteration.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateIteration"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Iteration"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateIteration",
"summary": "Update Iteration"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "iteration-public-id",
"description": "The unique ID of the Iteration.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteIteration",
"summary": "Delete Iteration"
}
},
"/api/v3/iterations/{iteration-public-id}/stories": {
"get": {
"parameters": [
{
"in": "path",
"name": "iteration-public-id",
"description": "The unique ID of the Iteration.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "includes_description",
"description": "A true/false boolean indicating whether to return Stories with their descriptions.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listIterationStories",
"description": "Get a list of all Stories in an Iteration.",
"summary": "List Iteration Stories"
}
},
"/api/v3/key-results/{key-result-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "key-result-public-id",
"description": "The ID of the Key Result.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KeyResult"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getKeyResult",
"description": "Get Key Result returns information about a chosen Key Result.",
"summary": "Get Key Result"
},
"put": {
"parameters": [
{
"in": "path",
"name": "key-result-public-id",
"description": "The ID of the Key Result.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateKeyResult"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KeyResult"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateKeyResult",
"description": "Update Key Result allows updating a Key Result's name or initial, observed, or target values.",
"summary": "Update Key Result"
}
},
"/api/v3/labels": {
"get": {
"parameters": [
{
"in": "query",
"name": "slim",
"description": "A true/false boolean indicating if the slim versions of the Label should be returned.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Label"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listLabels",
"description": "List Labels returns a list of all Labels and their attributes.",
"summary": "List Labels"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateLabelParams"
}
}
},
"description": "Request parameters for creating a Label on a Shortcut Story.",
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Label"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createLabel",
"description": "Create Label allows you to create a new Label in Shortcut.",
"summary": "Create Label"
}
},
"/api/v3/labels/{label-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "label-public-id",
"description": "The unique ID of the Label.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Label"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getLabel",
"description": "Get Label returns information about the selected Label.",
"summary": "Get Label"
},
"put": {
"parameters": [
{
"in": "path",
"name": "label-public-id",
"description": "The unique ID of the Label you wish to update.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLabel"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Label"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateLabel",
"description": "Update Label allows you to replace a Label name with another name. If you try to name a Label something that already exists, you will receive a 422 response.",
"summary": "Update Label"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "label-public-id",
"description": "The unique ID of the Label.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteLabel",
"description": "Delete Label can be used to delete any Label.",
"summary": "Delete Label"
}
},
"/api/v3/labels/{label-public-id}/epics": {
"get": {
"parameters": [
{
"in": "path",
"name": "label-public-id",
"description": "The unique ID of the Label.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicSlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listLabelEpics",
"description": "List all of the Epics with the Label.",
"summary": "List Label Epics"
}
},
"/api/v3/labels/{label-public-id}/stories": {
"get": {
"parameters": [
{
"in": "path",
"name": "label-public-id",
"description": "The unique ID of the Label.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "includes_description",
"description": "A true/false boolean indicating whether to return Stories with their descriptions.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listLabelStories",
"description": "List all of the Stories with the Label.",
"summary": "List Label Stories"
}
},
"/api/v3/linked-files": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LinkedFile"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listLinkedFiles",
"description": "List Linked Files returns a list of all Linked-Files and their attributes.",
"summary": "List Linked Files"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateLinkedFile"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LinkedFile"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createLinkedFile",
"description": "Create Linked File allows you to create a new Linked File in Shortcut.",
"summary": "Create Linked File"
}
},
"/api/v3/linked-files/{linked-file-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "linked-file-public-id",
"description": "The unique identifier of the linked file.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LinkedFile"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getLinkedFile",
"description": "Get File returns information about the selected Linked File.",
"summary": "Get Linked File"
},
"put": {
"parameters": [
{
"in": "path",
"name": "linked-file-public-id",
"description": "The unique identifier of the linked file.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLinkedFile"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LinkedFile"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateLinkedFile",
"description": "Updated Linked File allows you to update properties of a previously attached Linked-File.",
"summary": "Update Linked File"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "linked-file-public-id",
"description": "The unique identifier of the linked file.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteLinkedFile",
"description": "Delete Linked File can be used to delete any previously attached Linked-File.",
"summary": "Delete Linked File"
}
},
"/api/v3/member": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemberInfo"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getCurrentMemberInfo",
"description": "Returns information about the authenticated member.",
"summary": "Get Current Member Info"
}
},
"/api/v3/members": {
"get": {
"parameters": [
{
"in": "query",
"name": "org-public-id",
"description": "The unique ID of the Organization to limit the list to.",
"required": false,
"x-doc-skip": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "disabled",
"description": "Filter members by their disabled state. If true, return only disabled members. If false, return only enabled members.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Member"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listMembers",
"description": "Returns information about members of the Workspace.",
"summary": "List Members"
}
},
"/api/v3/members/{member-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "member-public-id",
"description": "The Member's unique ID.",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "org-public-id",
"description": "The unique ID of the Organization to limit the lookup to.",
"required": false,
"x-doc-skip": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Member"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getMember",
"description": "Returns information about a Member.",
"summary": "Get Member"
}
},
"/api/v3/milestones": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Milestone"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listMilestones",
"description": "(Deprecated: Use 'List Objectives') List Milestones returns a list of all Milestones and their attributes.",
"summary": "List Milestones"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateMilestone"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Milestone"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnusableEntitlementError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createMilestone",
"description": "(Deprecated: Use 'Create Objective') Create Milestone allows you to create a new Milestone in Shortcut.",
"summary": "Create Milestone"
}
},
"/api/v3/milestones/{milestone-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "milestone-public-id",
"description": "The ID of the Milestone.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Milestone"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getMilestone",
"description": "(Deprecated: Use 'Get Objective') Get Milestone returns information about a chosen Milestone.",
"summary": "Get Milestone"
},
"put": {
"parameters": [
{
"in": "path",
"name": "milestone-public-id",
"description": "The ID of the Milestone.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateMilestone"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Milestone"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateMilestone",
"description": "(Deprecated: Use 'Update Objective') Update Milestone can be used to update Milestone properties.",
"summary": "Update Milestone"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "milestone-public-id",
"description": "The ID of the Milestone.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteMilestone",
"description": "(Deprecated: Use 'Delete Objective') Delete Milestone can be used to delete any Milestone.",
"summary": "Delete Milestone"
}
},
"/api/v3/milestones/{milestone-public-id}/epics": {
"get": {
"parameters": [
{
"in": "path",
"name": "milestone-public-id",
"description": "The ID of the Milestone.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicSlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listMilestoneEpics",
"description": "(Deprecated: Use 'List Objective Epics') List all of the Epics within the Milestone.",
"summary": "List Milestone Epics"
}
},
"/api/v3/objectives": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Objective"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listObjectives",
"description": "List Objectives returns a list of all Objectives and their attributes.",
"summary": "List Objectives"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateObjective"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Objective"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnusableEntitlementError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createObjective",
"description": "Create Objective allows you to create a new Objective in Shortcut.",
"summary": "Create Objective"
}
},
"/api/v3/objectives/{objective-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "objective-public-id",
"description": "The ID of the Objective.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Objective"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getObjective",
"description": "Get Objective returns information about a chosen Objective.",
"summary": "Get Objective"
},
"put": {
"parameters": [
{
"in": "path",
"name": "objective-public-id",
"description": "The ID of the Objective.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateObjective"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Objective"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateObjective",
"description": "Update Objective can be used to update Objective properties.",
"summary": "Update Objective"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "objective-public-id",
"description": "The ID of the Objective.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteObjective",
"description": "Delete Objective can be used to delete any Objective.",
"summary": "Delete Objective"
}
},
"/api/v3/objectives/{objective-public-id}/epics": {
"get": {
"parameters": [
{
"in": "path",
"name": "objective-public-id",
"description": "The ID of the Objective.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicSlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listObjectiveEpics",
"description": "List all of the Epics within the Objective.",
"summary": "List Objective Epics"
}
},
"/api/v3/projects": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Project"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listProjects",
"description": "List Projects returns a list of all Projects and their attributes.",
"summary": "List Projects"
},
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateProject"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createProject",
"description": "Create Project is used to create a new Shortcut Project.",
"summary": "Create Project"
}
},
"/api/v3/projects/{project-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "project-public-id",
"description": "The unique ID of the Project.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getProject",
"description": "Get Project returns information about the selected Project.",
"summary": "Get Project"
},
"put": {
"parameters": [
{
"in": "path",
"name": "project-public-id",
"description": "The unique ID of the Project.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateProject"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateProject",
"description": "Update Project can be used to change properties of a Project.",
"summary": "Update Project"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "project-public-id",
"description": "The unique ID of the Project.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteProject",
"description": "Delete Project can be used to delete a Project. Projects can only be deleted if all associated Stories are moved or deleted. In the case that the Project cannot be deleted, you will receive a 422 response.",
"summary": "Delete Project"
}
},
"/api/v3/projects/{project-public-id}/stories": {
"get": {
"parameters": [
{
"in": "path",
"name": "project-public-id",
"description": "The unique ID of the Project.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "includes_description",
"description": "A true/false boolean indicating whether to return Stories with their descriptions.",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listStories",
"description": "List Stories returns a list of all Stories in a selected Project and their attributes.",
"summary": "List Stories"
}
},
"/api/v3/repositories": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Repository"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listRepositories",
"description": "List Repositories returns a list of all Repositories and their attributes.",
"summary": "List Repositories"
}
},
"/api/v3/repositories/{repo-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "repo-public-id",
"description": "The unique ID of the Repository.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Repository"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getRepository",
"description": "Get Repository returns information about the selected Repository.",
"summary": "Get Repository"
}
},
"/api/v3/search": {
"get": {
"parameters": [
{
"in": "query",
"name": "query",
"description": "See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"in": "query",
"name": "page_size",
"description": "The number of search results to include in a page. Minimum of 1 and maximum of 250.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "detail",
"description": "The amount of detail included in each result item.\n \"full\" will include all descriptions and comments and more fields on\n related items such as pull requests, branches and tasks.\n \"slim\" omits larger fulltext fields such as descriptions and comments\n and only references related items by id.\n The default is \"full\".",
"required": false,
"schema": {
"type": "string",
"enum": [
"full",
"slim"
]
}
},
{
"in": "query",
"name": "next",
"description": "The next page token.",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "entity_types",
"description": "A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.",
"required": false,
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"story",
"milestone",
"epic",
"iteration",
"objective"
]
}
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResults"
}
}
}
},
"400": {
"description": "**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded ",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaxSearchResultsExceededError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "search",
"description": "Search lets you search Epics and Stories based on desired parameters. Since ordering of the results can change over time (due to search ranking decay, new Epics and Stories being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.",
"summary": "Search"
}
},
"/api/v3/search/epics": {
"get": {
"parameters": [
{
"in": "query",
"name": "query",
"description": "See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"in": "query",
"name": "page_size",
"description": "The number of search results to include in a page. Minimum of 1 and maximum of 250.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "detail",
"description": "The amount of detail included in each result item.\n \"full\" will include all descriptions and comments and more fields on\n related items such as pull requests, branches and tasks.\n \"slim\" omits larger fulltext fields such as descriptions and comments\n and only references related items by id.\n The default is \"full\".",
"required": false,
"schema": {
"type": "string",
"enum": [
"full",
"slim"
]
}
},
{
"in": "query",
"name": "next",
"description": "The next page token.",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "entity_types",
"description": "A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.",
"required": false,
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"story",
"milestone",
"epic",
"iteration",
"objective"
]
}
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EpicSearchResults"
}
}
}
},
"400": {
"description": "**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded ",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaxSearchResultsExceededError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "searchEpics",
"description": "Search Epics lets you search Epics based on desired parameters. Since ordering of stories can change over time (due to search ranking decay, new Epics being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.",
"summary": "Search Epics"
}
},
"/api/v3/search/iterations": {
"get": {
"parameters": [
{
"in": "query",
"name": "query",
"description": "See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"in": "query",
"name": "page_size",
"description": "The number of search results to include in a page. Minimum of 1 and maximum of 250.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "detail",
"description": "The amount of detail included in each result item.\n \"full\" will include all descriptions and comments and more fields on\n related items such as pull requests, branches and tasks.\n \"slim\" omits larger fulltext fields such as descriptions and comments\n and only references related items by id.\n The default is \"full\".",
"required": false,
"schema": {
"type": "string",
"enum": [
"full",
"slim"
]
}
},
{
"in": "query",
"name": "next",
"description": "The next page token.",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "entity_types",
"description": "A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.",
"required": false,
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"story",
"milestone",
"epic",
"iteration",
"objective"
]
}
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IterationSearchResults"
}
}
}
},
"400": {
"description": "**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded ",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaxSearchResultsExceededError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "searchIterations",
"description": "Search Iterations lets you search Iterations based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Iterations being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.",
"summary": "Search Iterations"
}
},
"/api/v3/search/milestones": {
"get": {
"parameters": [
{
"in": "query",
"name": "query",
"description": "See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"in": "query",
"name": "page_size",
"description": "The number of search results to include in a page. Minimum of 1 and maximum of 250.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "detail",
"description": "The amount of detail included in each result item.\n \"full\" will include all descriptions and comments and more fields on\n related items such as pull requests, branches and tasks.\n \"slim\" omits larger fulltext fields such as descriptions and comments\n and only references related items by id.\n The default is \"full\".",
"required": false,
"schema": {
"type": "string",
"enum": [
"full",
"slim"
]
}
},
{
"in": "query",
"name": "next",
"description": "The next page token.",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "entity_types",
"description": "A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.",
"required": false,
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"story",
"milestone",
"epic",
"iteration",
"objective"
]
}
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ObjectiveSearchResults"
}
}
}
},
"400": {
"description": "**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded ",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaxSearchResultsExceededError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "searchMilestones",
"description": "Search Milestones lets you search Milestones based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Milestones being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.",
"summary": "Search Milestones"
}
},
"/api/v3/search/objectives": {
"get": {
"parameters": [
{
"in": "query",
"name": "query",
"description": "See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"in": "query",
"name": "page_size",
"description": "The number of search results to include in a page. Minimum of 1 and maximum of 250.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "detail",
"description": "The amount of detail included in each result item.\n \"full\" will include all descriptions and comments and more fields on\n related items such as pull requests, branches and tasks.\n \"slim\" omits larger fulltext fields such as descriptions and comments\n and only references related items by id.\n The default is \"full\".",
"required": false,
"schema": {
"type": "string",
"enum": [
"full",
"slim"
]
}
},
{
"in": "query",
"name": "next",
"description": "The next page token.",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "entity_types",
"description": "A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.",
"required": false,
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"story",
"milestone",
"epic",
"iteration",
"objective"
]
}
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ObjectiveSearchResults"
}
}
}
},
"400": {
"description": "**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded ",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaxSearchResultsExceededError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "searchObjectives",
"description": "Search Objectives lets you search Objectives based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Objectives being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.",
"summary": "Search Objectives"
}
},
"/api/v3/search/stories": {
"get": {
"parameters": [
{
"in": "query",
"name": "query",
"description": "See our help center article on [search operators](https://help.shortcut.com/hc/en-us/articles/360000046646-Search-Operators)",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"in": "query",
"name": "page_size",
"description": "The number of search results to include in a page. Minimum of 1 and maximum of 250.",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "query",
"name": "detail",
"description": "The amount of detail included in each result item.\n \"full\" will include all descriptions and comments and more fields on\n related items such as pull requests, branches and tasks.\n \"slim\" omits larger fulltext fields such as descriptions and comments\n and only references related items by id.\n The default is \"full\".",
"required": false,
"schema": {
"type": "string",
"enum": [
"full",
"slim"
]
}
},
{
"in": "query",
"name": "next",
"description": "The next page token.",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "entity_types",
"description": "A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.",
"required": false,
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"story",
"milestone",
"epic",
"iteration",
"objective"
]
}
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StorySearchResults"
}
}
}
},
"400": {
"description": "**Either:** (1) Schema mismatch **or** (2) Maximum of 1000 search results exceeded ",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaxSearchResultsExceededError"
}
}
}
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "searchStories",
"description": "Search Stories lets you search Stories based on desired parameters. Since ordering of stories can change over time (due to search ranking decay, new stories being created), the `next` value from the previous response can be used as the path and query string for the next page to ensure stable ordering.",
"summary": "Search Stories"
}
},
"/api/v3/stories": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateStoryParams"
}
}
},
"description": "Request parameters for creating a story.",
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Story"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createStory",
"description": "Create Story is used to add a new story to your Shortcut Workspace.\n This endpoint requires that either **workflow_state_id** or **project_id** be provided, but will reject the request if both or neither are specified. The workflow_state_id has been marked as required and is the recommended field to specify because we are in the process of sunsetting Projects in Shortcut.",
"summary": "Create Story"
}
},
"/api/v3/stories/bulk": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateStories"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createMultipleStories",
"description": "Create Multiple Stories allows you to create multiple stories in a single request using the same syntax as [Create Story](https://developer.shortcut.com/api/rest/v3#create-story).",
"summary": "Create Multiple Stories"
},
"put": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateStories"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateMultipleStories",
"description": "Update Multiple Stories allows you to make changes to numerous stories at once.",
"summary": "Update Multiple Stories"
},
"delete": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteStories"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteMultipleStories",
"description": "Delete Multiple Stories allows you to delete multiple archived stories at once.",
"summary": "Delete Multiple Stories"
}
},
"/api/v3/stories/from-template": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateStoryFromTemplateParams"
}
}
},
"description": "Request parameters for creating a story from a story template. These parameters are merged with the values derived from the template.",
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Story"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createStoryFromTemplate",
"description": "Create Story From Template is used to add a new story derived from a template to your Shortcut Workspace.",
"summary": "Create Story From Template"
}
},
"/api/v3/stories/search": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchStories"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySlim"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "searchStoriesOld",
"description": "Search Stories lets you search Stories based on desired parameters.",
"summary": "Search Stories (Old)"
}
},
"/api/v3/stories/{story-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Story"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getStory",
"description": "Get Story returns information about a chosen Story.",
"summary": "Get Story"
},
"put": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The unique identifier of this story.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateStory"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Story"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateStory",
"description": "Update Story can be used to update Story properties.",
"summary": "Update Story"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteStory",
"description": "Delete Story can be used to delete any Story.",
"summary": "Delete Story"
}
},
"/api/v3/stories/{story-public-id}/comments": {
"get": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story that the Comment is in.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryComment"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listStoryComment",
"description": "Lists Comments associated with a Story",
"summary": "List Story Comment"
},
"post": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story that the Comment is in.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateStoryComment"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoryComment"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createStoryComment",
"description": "Create Comment allows you to create a Comment on any Story.",
"summary": "Create Story Comment"
}
},
"/api/v3/stories/{story-public-id}/comments/{comment-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story that the Comment is in.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the Comment.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoryComment"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getStoryComment",
"description": "Get Comment is used to get Comment information.",
"summary": "Get Story Comment"
},
"put": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story that the Comment is in.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the Comment",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateStoryComment"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoryComment"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateStoryComment",
"description": "Update Comment replaces the text of the existing Comment.",
"summary": "Update Story Comment"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story that the Comment is in.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the Comment.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteStoryComment",
"description": "Delete a Comment from any story.",
"summary": "Delete Story Comment"
}
},
"/api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions": {
"post": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story that the Comment is in.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the Comment.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"$ref": "#/components/requestBodies/CreateOrDeleteStoryReaction"
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryReaction"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createStoryReaction",
"description": "Create a reaction to a story comment.",
"summary": "Create Story Reaction"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story that the Comment is in.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the Comment.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"$ref": "#/components/requestBodies/CreateOrDeleteStoryReaction"
},
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteStoryReaction",
"description": "Delete a reaction from any story comment.",
"summary": "Delete Story Reaction"
}
},
"/api/v3/stories/{story-public-id}/comments/{comment-public-id}/unlink-from-slack": {
"post": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story to unlink.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "comment-public-id",
"description": "The ID of the Comment to unlink.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoryComment"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "unlinkCommentThreadFromSlack",
"description": "Unlinks a Comment from its linked Slack thread (Comment replies and Slack replies will no longer be synced)",
"summary": "Unlink Comment thread from Slack"
}
},
"/api/v3/stories/{story-public-id}/history": {
"get": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/History"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "storyHistory",
"summary": "Story History"
}
},
"/api/v3/stories/{story-public-id}/tasks": {
"post": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The ID of the Story that the Task will be in.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTask"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Task"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createTask",
"description": "Create Task is used to create a new task in a Story.",
"summary": "Create Task"
}
},
"/api/v3/stories/{story-public-id}/tasks/{task-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The unique ID of the Story this Task is associated with.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "task-public-id",
"description": "The unique ID of the Task.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Task"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getTask",
"description": "Returns information about a chosen Task.",
"summary": "Get Task"
},
"put": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The unique identifier of the parent Story.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "task-public-id",
"description": "The unique identifier of the Task you wish to update.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTask"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Task"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateTask",
"description": "Update Task can be used to update Task properties.",
"summary": "Update Task"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "story-public-id",
"description": "The unique ID of the Story this Task is associated with.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"in": "path",
"name": "task-public-id",
"description": "The unique ID of the Task.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteTask",
"description": "Delete Task can be used to delete any previously created Task on a Story.",
"summary": "Delete Task"
}
},
"/api/v3/story-links": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateStoryLink"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoryLink"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "createStoryLink",
"description": "Story Links (called Story Relationships in the UI) allow you create semantic relationships between two stories. The parameters read like an active voice grammatical sentence: subject -> verb -> object.\n\nThe subject story acts on the object Story; the object story is the direct object of the sentence.\n\nThe subject story \"blocks\", \"duplicates\", or \"relates to\" the object story. Examples:\n- \"story 5 blocks story 6” -- story 6 is now \"blocked\" until story 5 is moved to a Done workflow state.\n- \"story 2 duplicates story 1” -- Story 2 represents the same body of work as Story 1 (and should probably be archived).\n- \"story 7 relates to story 3”",
"summary": "Create Story Link"
}
},
"/api/v3/story-links/{story-link-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "story-link-public-id",
"description": "The unique ID of the Story Link.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoryLink"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getStoryLink",
"description": "Returns the stories and their relationship for the given Story Link.",
"summary": "Get Story Link"
},
"put": {
"parameters": [
{
"in": "path",
"name": "story-link-public-id",
"description": "The unique ID of the Story Link.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateStoryLink"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoryLink"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "updateStoryLink",
"description": "Updates the stories and/or the relationship for the given Story Link.",
"summary": "Update Story Link"
},
"delete": {
"parameters": [
{
"in": "path",
"name": "story-link-public-id",
"description": "The unique ID of the Story Link.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "deleteStoryLink",
"description": "Removes the relationship between the stories for the given Story Link.",
"summary": "Delete Story Link"
}
},
"/api/v3/workflows": {
"get": {
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Workflow"
}
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "listWorkflows",
"description": "Returns a list of all Workflows in the Workspace.",
"summary": "List Workflows"
}
},
"/api/v3/workflows/{workflow-public-id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "workflow-public-id",
"description": "The ID of the Workflow.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Workflow"
}
}
}
},
"400": {
"description": "Schema mismatch"
},
"404": {
"description": "Resource does not exist"
},
"422": {
"description": "Unprocessable"
}
},
"operationId": "getWorkflow",
"description": "Get Workflow returns information about a chosen Workflow.",
"summary": "Get Workflow"
}
}
},
"info": {
"title": "Shortcut API",
"version": "3.0",
"description": "Shortcut API"
},
"servers": [
{
"url": "https://api.app.shortcut.com"
}
],
"components": {
"requestBodies": {
"CreateOrDeleteStoryReaction": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOrDeleteStoryReaction"
}
}
},
"required": true
}
},
"securitySchemes": {
"api_token": {
"type": "apiKey",
"in": "header",
"name": "Shortcut-Token"
}
},
"schemas": {
"BaseTaskParams": {
"description": "Request parameters for specifying how to pre-populate a task through a template.",
"type": "object",
"properties": {
"description": {
"maxLength": 2048,
"minLength": 1,
"description": "The Task description.",
"type": "string"
},
"complete": {
"description": "True/false boolean indicating whether the Task is completed. Defaults to false.",
"type": "boolean"
},
"owner_ids": {
"description": "An array of UUIDs for any members you want to add as Owners on this new Task.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"maxLength": 128,
"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.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"description"
]
},
"BasicWorkspaceInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"default_workflow_id": {
"type": "integer",
"format": "int64"
},
"estimate_scale": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"name": {
"type": "string"
},
"url_slug": {
"type": "string"
},
"utc_offset": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"created_at",
"default_workflow_id",
"estimate_scale",
"name",
"url_slug",
"utc_offset"
]
},
"Branch": {
"description": "Branch refers to a VCS branch. Branches are feature branches associated with Shortcut Stories.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"deleted": {
"description": "A true/false boolean indicating if the Branch has been deleted.",
"type": "boolean"
},
"name": {
"description": "The name of the Branch.",
"type": "string"
},
"persistent": {
"description": "This field is deprecated, and will always be false.",
"type": "boolean"
},
"updated_at": {
"description": "The time/date the Branch was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"pull_requests": {
"description": "An array of PullRequests attached to the Branch (there is usually only one).",
"type": "array",
"items": {
"$ref": "#/components/schemas/PullRequest"
}
},
"merged_branch_ids": {
"description": "The IDs of the Branches the Branch has been merged into.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"id": {
"description": "The unique ID of the Branch.",
"type": "integer",
"format": "int64",
"nullable": true
},
"url": {
"description": "The URL of the Branch.",
"type": "string"
},
"repository_id": {
"description": "The ID of the Repository that contains the Branch.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date the Branch was created.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"entity_type",
"deleted",
"name",
"persistent",
"updated_at",
"pull_requests",
"merged_branch_ids",
"id",
"url",
"repository_id",
"created_at"
]
},
"Category": {
"description": "A Category can be used to associate Objectives.",
"type": "object",
"properties": {
"archived": {
"description": "A true/false boolean indicating if the Category has been archived.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"color": {
"description": "The hex color to be displayed with the Category (for example, \"#ff0000\").",
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"minLength": 1,
"type": "string",
"nullable": true
},
"name": {
"description": "The name of the Category.",
"type": "string"
},
"global_id": {
"description": "The Global ID of the Category.",
"x-doc-skip": true,
"type": "string"
},
"type": {
"description": "The type of entity this Category is associated with; currently Milestone or Objective is the only type of Category.",
"x-doc-skip": true,
"type": "string"
},
"updated_at": {
"description": "The time/date that the Category was updated.",
"type": "string",
"format": "date-time"
},
"external_id": {
"description": "This field can be set to another unique ID. In the case that the Category has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Category.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date that the Category was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"archived",
"entity_type",
"color",
"name",
"global_id",
"type",
"updated_at",
"external_id",
"id",
"created_at"
]
},
"Commit": {
"description": "Commit refers to a VCS commit and all associated details.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"author_id": {
"description": "The ID of the Member that authored the Commit, if known.",
"type": "string",
"format": "uuid",
"nullable": true
},
"hash": {
"description": "The Commit hash.",
"type": "string"
},
"updated_at": {
"description": "The time/date the Commit was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"id": {
"description": "The unique ID of the Commit.",
"type": "integer",
"format": "int64",
"nullable": true
},
"url": {
"description": "The URL of the Commit.",
"type": "string"
},
"author_email": {
"description": "The email address of the VCS user that authored the Commit.",
"type": "string"
},
"timestamp": {
"description": "The time/date the Commit was pushed.",
"type": "string",
"format": "date-time"
},
"author_identity": {
"$ref": "#/components/schemas/Identity"
},
"repository_id": {
"description": "The ID of the Repository that contains the Commit.",
"type": "integer",
"format": "int64",
"nullable": true
},
"created_at": {
"description": "The time/date the Commit was created.",
"type": "string",
"format": "date-time"
},
"message": {
"description": "The Commit message.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"entity_type",
"author_id",
"hash",
"updated_at",
"id",
"url",
"author_email",
"timestamp",
"author_identity",
"repository_id",
"created_at",
"message"
]
},
"CreateCategory": {
"x-doc-skip": true,
"type": "object",
"properties": {
"name": {
"maxLength": 128,
"minLength": 1,
"description": "The name of the new Category.",
"type": "string"
},
"color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"description": "The hex color to be displayed with the Category (for example, \"#ff0000\").",
"minLength": 1,
"type": "string"
},
"external_id": {
"maxLength": 128,
"minLength": 1,
"description": "This field can be set to another unique ID. In the case that the Category has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string"
},
"type": {
"description": "The type of entity this Category is associated with; currently Milestone or Objective is the only type of Category.",
"x-doc-skip": true
}
},
"additionalProperties": false,
"required": [
"name"
]
},
"CreateCategoryParams": {
"description": "Request parameters for creating a Category with a Objective.",
"type": "object",
"properties": {
"name": {
"maxLength": 128,
"minLength": 1,
"description": "The name of the new Category.",
"type": "string"
},
"color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"description": "The hex color to be displayed with the Category (for example, \"#ff0000\").",
"minLength": 1,
"type": "string"
},
"external_id": {
"maxLength": 128,
"minLength": 1,
"description": "This field can be set to another unique ID. In the case that the Category has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name"
]
},
"CreateCommentComment": {
"x-doc-skip": true,
"type": "object",
"properties": {
"text": {
"maxLength": 100000,
"description": "The comment text.",
"minLength": 1,
"type": "string"
},
"author_id": {
"description": "The Member ID of the Comment's author. Defaults to the user identified by the API token.",
"type": "string",
"format": "uuid"
},
"created_at": {
"description": "Defaults to the time/date the comment is created, but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "Defaults to the time/date the comment is last updated, but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"external_id": {
"maxLength": 128,
"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.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
},
"CreateDoc": {
"type": "object",
"properties": {
"title": {
"maxLength": 256,
"minLength": 1,
"description": "The title for the new document",
"type": "string"
},
"content": {
"description": "The content for the new document",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"title",
"content"
]
},
"CreateEntityTemplate": {
"description": "Request parameters for creating an entirely new entity template.",
"type": "object",
"properties": {
"name": {
"maxLength": 128,
"minLength": 1,
"description": "The name of the new entity template",
"type": "string"
},
"author_id": {
"description": "The id of the user creating this template.",
"type": "string",
"format": "uuid"
},
"story_contents": {
"$ref": "#/components/schemas/CreateStoryContents"
}
},
"additionalProperties": false,
"required": [
"name",
"story_contents"
]
},
"CreateEpic": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 100000,
"description": "The Epic's description.",
"type": "string"
},
"labels": {
"description": "An array of Labels attached to the Epic.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"completed_at_override": {
"description": "A manual override for the time/date the Epic was completed.",
"type": "string",
"format": "date-time"
},
"objective_ids": {
"description": "An array of IDs for Objectives to which this Epic is related.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"name": {
"maxLength": 256,
"minLength": 1,
"description": "The Epic's name.",
"type": "string"
},
"planned_start_date": {
"description": "The Epic's planned start date.",
"type": "string",
"format": "date-time",
"nullable": true
},
"state": {
"description": "`Deprecated` The Epic's state (to do, in progress, or done); will be ignored when `epic_state_id` is set.",
"type": "string",
"enum": [
"in progress",
"to do",
"done"
]
},
"milestone_id": {
"description": "`Deprecated` The ID of the Milestone this Epic is related to. Use `objective_ids`.",
"type": "integer",
"format": "int64",
"nullable": true
},
"requested_by_id": {
"description": "The ID of the member that requested the epic.",
"type": "string",
"format": "uuid"
},
"epic_state_id": {
"description": "The ID of the Epic State.",
"type": "integer",
"format": "int64"
},
"started_at_override": {
"description": "A manual override for the time/date the Epic was started.",
"type": "string",
"format": "date-time"
},
"group_id": {
"description": "`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.",
"type": "string",
"format": "uuid",
"nullable": true
},
"updated_at": {
"description": "Defaults to the time/date it is created but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"follower_ids": {
"description": "An array of UUIDs for any Members you want to add as Followers on this new Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_ids": {
"description": "An array of UUIDS for Groups to which this Epic is related.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"converted_from_story_id": {
"description": "The ID of the Story that was converted to an Epic.",
"type": "integer",
"format": "int64",
"nullable": true
},
"owner_ids": {
"description": "An array of UUIDs for any members you want to add as Owners on this new Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"maxLength": 128,
"description": "This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string"
},
"deadline": {
"description": "The Epic's deadline.",
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"description": "Defaults to the time/date it is created but can be set to reflect another date.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"name"
]
},
"CreateEpicComment": {
"x-doc-skip": true,
"type": "object",
"properties": {
"text": {
"maxLength": 100000,
"description": "The comment text.",
"minLength": 1,
"type": "string"
},
"author_id": {
"description": "The Member ID of the Comment's author. Defaults to the user identified by the API token.",
"type": "string",
"format": "uuid"
},
"created_at": {
"description": "Defaults to the time/date the comment is created, but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "Defaults to the time/date the comment is last updated, but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"external_id": {
"maxLength": 128,
"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.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
},
"CreateEpicHealth": {
"x-doc-skip": true,
"type": "object",
"properties": {
"status": {
"description": "The health status of the Epic.",
"type": "string",
"enum": [
"At Risk",
"On Track",
"Off Track",
"No Health"
]
},
"text": {
"description": "The description of the Health status.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"status"
]
},
"CreateGenericIntegration": {
"type": "object",
"properties": {
"webhook_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"type": "string"
},
"secret": {
"maxLength": 128,
"minLength": 1,
"type": "string"
}
},
"additionalProperties": false,
"required": [
"webhook_url"
]
},
"CreateGroup": {
"type": "object",
"properties": {
"description": {
"maxLength": 4096,
"description": "The description of the Group.",
"type": "string"
},
"member_ids": {
"description": "The Member ids to add to this Group.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"workflow_ids": {
"description": "The Workflow ids to add to the Group.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"name": {
"maxLength": 63,
"minLength": 1,
"description": "The name of this Group.",
"type": "string"
},
"mention_name": {
"maxLength": 63,
"minLength": 1,
"description": "The mention name of this Group.",
"type": "string"
},
"color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"description": "The color you wish to use for the Group in the system.",
"minLength": 1,
"type": "string"
},
"color_key": {
"description": "The color key you wish to use for the Group in the system.",
"type": "string",
"enum": [
"blue",
"purple",
"midnight-blue",
"orange",
"yellow-green",
"brass",
"gray",
"fuchsia",
"yellow",
"pink",
"sky-blue",
"green",
"red",
"black",
"slate",
"turquoise"
]
},
"display_icon_id": {
"description": "The Icon id for the avatar of this Group.",
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"required": [
"name",
"mention_name"
]
},
"CreateIteration": {
"type": "object",
"properties": {
"follower_ids": {
"description": "An array of UUIDs for any Members you want to add as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_ids": {
"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.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"labels": {
"description": "An array of Labels attached to the Iteration.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"description": {
"maxLength": 100000,
"description": "The description of the Iteration.",
"type": "string"
},
"name": {
"maxLength": 256,
"minLength": 1,
"description": "The name of this Iteration.",
"type": "string"
},
"start_date": {
"minLength": 1,
"description": "The date this Iteration begins, e.g. 2019-07-01.",
"type": "string"
},
"end_date": {
"minLength": 1,
"description": "The date this Iteration ends, e.g. 2019-07-01.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name",
"start_date",
"end_date"
]
},
"CreateLabelParams": {
"description": "Request parameters for creating a Label on a Shortcut Story.",
"type": "object",
"properties": {
"name": {
"maxLength": 128,
"minLength": 1,
"description": "The name of the new Label.",
"type": "string"
},
"description": {
"maxLength": 1024,
"description": "The description of the new Label.",
"type": "string"
},
"color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"description": "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"minLength": 1,
"type": "string"
},
"external_id": {
"maxLength": 128,
"minLength": 1,
"description": "This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name"
]
},
"CreateLinkedFile": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 512,
"description": "The description of the file.",
"type": "string"
},
"story_id": {
"description": "The ID of the linked story.",
"type": "integer",
"format": "int64"
},
"name": {
"maxLength": 256,
"minLength": 1,
"description": "The name of the file.",
"type": "string"
},
"thumbnail_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The URL of the thumbnail, if the integration provided it.",
"type": "string"
},
"type": {
"description": "The integration type of the file (e.g. google, dropbox, box).",
"type": "string",
"enum": [
"google",
"url",
"dropbox",
"box",
"onedrive"
]
},
"size": {
"description": "The filesize, if the integration provided it.",
"type": "integer",
"format": "int64"
},
"uploader_id": {
"description": "The UUID of the member that uploaded the file.",
"type": "string",
"format": "uuid"
},
"content_type": {
"maxLength": 128,
"description": "The content type of the image (e.g. txt/plain).",
"type": "string"
},
"url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The URL of linked file.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name",
"type",
"url"
]
},
"CreateMilestone": {
"x-doc-skip": true,
"type": "object",
"properties": {
"name": {
"maxLength": 256,
"minLength": 1,
"description": "The name of the Milestone.",
"type": "string"
},
"description": {
"maxLength": 100000,
"description": "The Milestone's description.",
"type": "string"
},
"state": {
"description": "The workflow state that the Milestone is in.",
"type": "string",
"enum": [
"in progress",
"to do",
"done"
]
},
"started_at_override": {
"description": "A manual override for the time/date the Milestone was started.",
"type": "string",
"format": "date-time"
},
"completed_at_override": {
"description": "A manual override for the time/date the Milestone was completed.",
"type": "string",
"format": "date-time"
},
"categories": {
"description": "An array of IDs of Categories attached to the Milestone.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateCategoryParams"
}
}
},
"additionalProperties": false,
"required": [
"name"
]
},
"CreateObjective": {
"x-doc-skip": true,
"type": "object",
"properties": {
"name": {
"maxLength": 256,
"minLength": 1,
"description": "The name of the Objective.",
"type": "string"
},
"description": {
"maxLength": 100000,
"description": "The Objective's description.",
"type": "string"
},
"state": {
"description": "The workflow state that the Objective is in.",
"type": "string",
"enum": [
"in progress",
"to do",
"done"
]
},
"started_at_override": {
"description": "A manual override for the time/date the Objective was started.",
"type": "string",
"format": "date-time"
},
"completed_at_override": {
"description": "A manual override for the time/date the Objective was completed.",
"type": "string",
"format": "date-time"
},
"categories": {
"description": "An array of IDs of Categories attached to the Objective.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateCategoryParams"
}
}
},
"additionalProperties": false,
"required": [
"name"
]
},
"CreateOrDeleteStoryReaction": {
"x-doc-skip": true,
"type": "object",
"properties": {
"emoji": {
"description": "The emoji short-code to add / remove. E.g. `:thumbsup::skin-tone-4:`.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"emoji"
]
},
"CreateProject": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 100000,
"description": "The Project description.",
"type": "string"
},
"color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"description": "The color you wish to use for the Project in the system.",
"minLength": 1,
"type": "string"
},
"name": {
"maxLength": 128,
"minLength": 1,
"description": "The name of the Project.",
"type": "string"
},
"start_time": {
"description": "The date at which the Project was started.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "Defaults to the time/date it is created but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"follower_ids": {
"description": "An array of UUIDs for any members you want to add as Owners on this new Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"maxLength": 128,
"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.",
"type": "string"
},
"team_id": {
"description": "The ID of the team the project belongs to.",
"type": "integer",
"format": "int64"
},
"iteration_length": {
"description": "The number of weeks per iteration in this Project.",
"type": "integer",
"format": "int64"
},
"abbreviation": {
"maxLength": 63,
"description": "The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.",
"type": "string"
},
"created_at": {
"description": "Defaults to the time/date it is created but can be set to reflect another date.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"name",
"team_id"
]
},
"CreateStories": {
"x-doc-skip": true,
"type": "object",
"properties": {
"stories": {
"description": "An array of stories to be created.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateStoryParams"
}
}
},
"additionalProperties": false,
"required": [
"stories"
]
},
"CreateStoryComment": {
"x-doc-skip": true,
"type": "object",
"properties": {
"text": {
"maxLength": 100000,
"description": "The comment text.",
"type": "string"
},
"author_id": {
"description": "The Member ID of the Comment's author. Defaults to the user identified by the API token.",
"type": "string",
"format": "uuid"
},
"created_at": {
"description": "Defaults to the time/date the comment is created, but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "Defaults to the time/date the comment is last updated, but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"external_id": {
"maxLength": 1024,
"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.",
"type": "string"
},
"parent_id": {
"description": "The ID of the Comment that this comment is threaded under.",
"type": "integer",
"format": "int64",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"text"
]
},
"CreateStoryCommentParams": {
"description": "Request parameters for creating a Comment on a Shortcut Story.",
"type": "object",
"properties": {
"text": {
"maxLength": 100000,
"description": "The comment text.",
"type": "string"
},
"author_id": {
"description": "The Member ID of the Comment's author. Defaults to the user identified by the API token.",
"type": "string",
"format": "uuid"
},
"created_at": {
"description": "Defaults to the time/date the comment is created, but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "Defaults to the time/date the comment is last updated, but can be set to reflect another date.",
"type": "string",
"format": "date-time"
},
"external_id": {
"maxLength": 1024,
"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.",
"type": "string"
},
"parent_id": {
"description": "The ID of the Comment that this comment is threaded under.",
"type": "integer",
"format": "int64",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"text"
]
},
"CreateStoryContents": {
"description": "A map of story attributes this template populates.",
"type": "object",
"properties": {
"description": {
"description": "The description of the story.",
"type": "string"
},
"labels": {
"description": "An array of labels to be populated by the template.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string"
},
"custom_fields": {
"description": "An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldValueParams"
}
},
"file_ids": {
"description": "An array of the attached file IDs to be populated.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"name": {
"maxLength": 512,
"description": "The name of the story.",
"type": "string"
},
"epic_id": {
"description": "The ID of the epic the to be populated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"external_links": {
"description": "An array of external links to be populated.",
"type": "array",
"items": {
"type": "string"
}
},
"sub_tasks": {
"description": "An array of sub-tasks connected to the story",
"x-doc-skip": true,
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateSubTaskParams"
}
},
"iteration_id": {
"description": "The ID of the iteration the to be populated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"tasks": {
"description": "An array of tasks to be populated by the template.",
"type": "array",
"items": {
"$ref": "#/components/schemas/BaseTaskParams"
}
},
"group_id": {
"description": "The ID of the group to be populated.",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The ID of the workflow state to be populated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"follower_ids": {
"description": "An array of UUIDs for any Members listed as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"estimate": {
"description": "The numeric point estimate to be populated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"project_id": {
"description": "The ID of the project the story belongs to.",
"type": "integer",
"format": "int64"
},
"linked_file_ids": {
"description": "An array of the linked file IDs to be populated.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"CreateStoryFromTemplateParams": {
"description": "Request parameters for creating a story from a story template. These parameters are merged with the values derived from the template.",
"type": "object",
"properties": {
"description": {
"maxLength": 100000,
"description": "The description of the story.",
"type": "string"
},
"archived": {
"description": "Controls the story's archived state.",
"type": "boolean"
},
"story_links": {
"description": "An array of story links attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateStoryLinkParams"
}
},
"labels": {
"description": "An array of labels attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"external_links_add": {
"description": "An array of External Links associated with this story. These will be added to any links provided by the template. Cannot be used in conjunction with `external_links`.",
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string",
"enum": [
"feature",
"chore",
"bug"
]
},
"custom_fields": {
"description": "A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldValueParams"
}
},
"move_to": {
"description": "One of \"first\" or \"last\". This can be used to move the given story to the first or last position in the workflow state.",
"type": "string",
"enum": [
"last",
"first"
]
},
"file_ids": {
"description": "An array of IDs of files attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"source_task_id": {
"description": "Given this story was converted from a task in another story, this is the original task ID that was converted to this story.",
"type": "integer",
"format": "int64",
"nullable": true
},
"completed_at_override": {
"description": "A manual override for the time/date the Story was completed.",
"type": "string",
"format": "date-time"
},
"name": {
"maxLength": 512,
"minLength": 1,
"description": "The name of the story. Must be provided if the template does not provide a name.",
"type": "string"
},
"file_ids_add": {
"description": "An array of IDs of files attached to the story in addition to files from the template. Cannot be used in conjunction with `file_ids`.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"file_ids_remove": {
"description": "An array of IDs of files removed from files from the template. Cannot be used in conjunction with `file_ids`.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"comments": {
"description": "An array of comments to add to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateStoryCommentParams"
}
},
"follower_ids_add": {
"description": "The UUIDs of the new followers to be added in addition to followers from the template. Cannot be used in conjunction with `follower_ids.`",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"epic_id": {
"description": "The ID of the epic the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"story_template_id": {
"description": "The id of the story template used to create this story.",
"type": "string",
"format": "uuid"
},
"external_links": {
"description": "An array of External Links associated with this story.",
"type": "array",
"items": {
"type": "string"
}
},
"follower_ids_remove": {
"description": "The UUIDs of the new followers to be removed from followers from the template. Cannot be used in conjunction with `follower_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"sub_tasks": {
"description": "A list of either params to create a new sub-task or link an existing story as a sub-task",
"x-doc-skip": true,
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/LinkSubTaskParams"
},
{
"$ref": "#/components/schemas/CreateSubTaskParams"
}
]
}
},
"linked_file_ids_remove": {
"description": "An array of IDs of linked files removed from files from the template. Cannot be used in conjunction with `linked_files.`",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"requested_by_id": {
"description": "The ID of the member that requested the story.",
"type": "string",
"format": "uuid"
},
"iteration_id": {
"description": "The ID of the iteration the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"custom_fields_remove": {
"description": "A map specifying a CustomField ID. These will be removed from any fields provided by the template. Cannot be used in conjunction with `custom_fields`.",
"type": "array",
"items": {
"$ref": "#/components/schemas/RemoveCustomFieldParams"
},
"uniqueItems": true
},
"tasks": {
"description": "An array of tasks connected to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateTaskParams"
}
},
"started_at_override": {
"description": "A manual override for the time/date the Story was started.",
"type": "string",
"format": "date-time"
},
"labels_add": {
"description": "An array of labels attached to the story in addition to the labels provided by the template. Cannot be used in conjunction with `labels`.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
},
"uniqueItems": true
},
"group_id": {
"description": "The id of the group to associate with this story.",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The ID of the workflow state the story will be in.",
"type": "integer",
"format": "int64"
},
"updated_at": {
"description": "The time/date the Story was updated.",
"type": "string",
"format": "date-time"
},
"follower_ids": {
"description": "An array of UUIDs of the followers of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"external_id": {
"maxLength": 1024,
"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.",
"type": "string"
},
"parent_story_id": {
"description": "The id of the parent story to associate with this story.",
"type": "integer",
"format": "int64",
"nullable": true
},
"estimate": {
"description": "The numeric point estimate of the story. Can also be null, which means unestimated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"owner_ids_remove": {
"description": "The UUIDs of the new owners to be removed from owners from the template. Cannot be used in conjunction with `owners`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"custom_fields_add": {
"description": "A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. These will be added to any fields provided by the template. Cannot be used in conjunction with `custom_fields`.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldValueParams"
},
"uniqueItems": true
},
"project_id": {
"description": "The ID of the project the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"linked_file_ids_add": {
"description": "An array of IDs of linked files attached to the story in addition to files from the template. Cannot be used in conjunction with `linked_files`.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"linked_file_ids": {
"description": "An array of IDs of linked files attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"labels_remove": {
"description": "An array of labels to remove from the labels provided by the template. Cannot be used in conjunction with `labels`.",
"type": "array",
"items": {
"$ref": "#/components/schemas/RemoveLabelParams"
},
"uniqueItems": true
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time",
"nullable": true
},
"owner_ids_add": {
"description": "The UUIDs of the new owners to be added in addition to owners from the template. Cannot be used in conjunction with `owners`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"created_at": {
"description": "The time/date the Story was created.",
"type": "string",
"format": "date-time"
},
"external_links_remove": {
"description": "An array of External Links associated with this story. These will be removed from any links provided by the template. Cannot be used in conjunction with `external_links`.",
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
}
},
"additionalProperties": false,
"required": [
"story_template_id"
]
},
"CreateStoryLink": {
"x-doc-skip": true,
"type": "object",
"properties": {
"verb": {
"description": "The type of link.",
"type": "string",
"enum": [
"blocks",
"duplicates",
"relates to"
]
},
"subject_id": {
"description": "The ID of the subject Story.",
"type": "integer",
"format": "int64"
},
"object_id": {
"description": "The ID of the object Story.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"verb",
"subject_id",
"object_id"
]
},
"CreateStoryLinkParams": {
"description": "Request parameters for creating a Story Link within a Story.",
"type": "object",
"properties": {
"subject_id": {
"description": "The unique ID of the Story defined as subject.",
"type": "integer",
"format": "int64"
},
"verb": {
"description": "How the subject Story acts on the object Story. This can be \"blocks\", \"duplicates\", or \"relates to\".",
"type": "string",
"enum": [
"blocks",
"duplicates",
"relates to"
]
},
"object_id": {
"description": "The unique ID of the Story defined as object.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"verb"
]
},
"CreateStoryParams": {
"description": "Request parameters for creating a story.",
"type": "object",
"properties": {
"description": {
"maxLength": 100000,
"description": "The description of the story.",
"type": "string"
},
"archived": {
"description": "Controls the story's archived state.",
"type": "boolean"
},
"story_links": {
"description": "An array of story links attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateStoryLinkParams"
}
},
"labels": {
"description": "An array of labels attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string",
"enum": [
"feature",
"chore",
"bug"
]
},
"custom_fields": {
"description": "A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldValueParams"
}
},
"move_to": {
"description": "One of \"first\" or \"last\". This can be used to move the given story to the first or last position in the workflow state.",
"type": "string",
"enum": [
"last",
"first"
]
},
"file_ids": {
"description": "An array of IDs of files attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"source_task_id": {
"description": "Given this story was converted from a task in another story, this is the original task ID that was converted to this story.",
"type": "integer",
"format": "int64",
"nullable": true
},
"completed_at_override": {
"description": "A manual override for the time/date the Story was completed.",
"type": "string",
"format": "date-time"
},
"name": {
"maxLength": 512,
"minLength": 1,
"description": "The name of the story.",
"type": "string"
},
"comments": {
"description": "An array of comments to add to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateStoryCommentParams"
}
},
"epic_id": {
"description": "The ID of the epic the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"story_template_id": {
"description": "The id of the story template used to create this story, if applicable. This is just an association; no content from the story template is inherited by the story simply by setting this field.",
"type": "string",
"format": "uuid",
"nullable": true
},
"external_links": {
"description": "An array of External Links associated with this story.",
"type": "array",
"items": {
"type": "string"
}
},
"sub_tasks": {
"description": "A list of either params to create a new sub-task or link an existing story as a sub-task",
"x-doc-skip": true,
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/LinkSubTaskParams"
},
{
"$ref": "#/components/schemas/CreateSubTaskParams"
}
]
}
},
"requested_by_id": {
"description": "The ID of the member that requested the story.",
"type": "string",
"format": "uuid"
},
"iteration_id": {
"description": "The ID of the iteration the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"tasks": {
"description": "An array of tasks connected to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateTaskParams"
}
},
"started_at_override": {
"description": "A manual override for the time/date the Story was started.",
"type": "string",
"format": "date-time"
},
"group_id": {
"description": "The id of the group to associate with this story.",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The ID of the workflow state the story will be in.",
"type": "integer",
"format": "int64"
},
"updated_at": {
"description": "The time/date the Story was updated.",
"type": "string",
"format": "date-time"
},
"follower_ids": {
"description": "An array of UUIDs of the followers of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"external_id": {
"maxLength": 1024,
"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.",
"type": "string"
},
"parent_story_id": {
"description": "The id of the parent story to associate with this story.",
"type": "integer",
"format": "int64",
"nullable": true
},
"estimate": {
"description": "The numeric point estimate of the story. Can also be null, which means unestimated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"project_id": {
"description": "The ID of the project the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"linked_file_ids": {
"description": "An array of IDs of linked files attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"description": "The time/date the Story was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"name"
]
},
"CreateSubTaskParams": {
"x-doc-skip": true,
"type": "object",
"properties": {
"name": {
"maxLength": 512,
"minLength": 1,
"description": "The name of the SubTask.",
"type": "string"
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"workflow_state_id": {
"description": "The ID of the workflow state the story will be in.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"name"
]
},
"CreateTask": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 2048,
"minLength": 1,
"description": "The Task description.",
"type": "string"
},
"complete": {
"description": "True/false boolean indicating whether the Task is completed. Defaults to false.",
"type": "boolean"
},
"owner_ids": {
"description": "An array of UUIDs for any members you want to add as Owners on this new Task.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"maxLength": 128,
"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.",
"type": "string"
},
"created_at": {
"description": "Defaults to the time/date the Task is created but can be set to reflect another creation time/date.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"description"
]
},
"CreateTaskParams": {
"description": "Request parameters for creating a Task on a Story.",
"type": "object",
"properties": {
"description": {
"maxLength": 2048,
"minLength": 1,
"description": "The Task description.",
"type": "string"
},
"complete": {
"description": "True/false boolean indicating whether the Task is completed. Defaults to false.",
"type": "boolean"
},
"owner_ids": {
"description": "An array of UUIDs for any members you want to add as Owners on this new Task.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"maxLength": 128,
"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.",
"type": "string"
},
"created_at": {
"description": "Defaults to the time/date the Task is created but can be set to reflect another creation time/date.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"description"
]
},
"CustomField": {
"type": "object",
"properties": {
"description": {
"maxLength": 512,
"minLength": 1,
"description": "A string description of the CustomField",
"type": "string"
},
"icon_set_identifier": {
"maxLength": 63,
"minLength": 1,
"description": "A string that represents the icon that corresponds to this custom field.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string",
"enum": [
"custom-field"
]
},
"story_types": {
"description": "The types of stories this CustomField is scoped to.",
"x-doc-skip": true,
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"maxLength": 63,
"minLength": 1,
"description": "The name of the Custom Field.",
"type": "string"
},
"fixed_position": {
"description": "When true, the CustomFieldEnumValues may not be reordered.",
"x-doc-skip": true,
"type": "boolean"
},
"updated_at": {
"description": "The instant when this CustomField was last updated.",
"type": "string",
"format": "date-time"
},
"id": {
"description": "The unique public ID for the CustomField.",
"type": "string",
"format": "uuid"
},
"values": {
"description": "A collection of legal values for a CustomField.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldEnumValue"
}
},
"field_type": {
"description": "The type of Custom Field, eg. 'enum'.",
"type": "string",
"enum": [
"enum"
]
},
"position": {
"description": "An integer indicating the position of this Custom Field with respect to the other CustomField",
"type": "integer",
"format": "int64"
},
"canonical_name": {
"description": "The canonical name for a Shortcut-defined field.",
"type": "string"
},
"enabled": {
"description": "When true, the CustomField can be applied to entities in the Workspace.",
"type": "boolean"
},
"created_at": {
"description": "The instant when this CustomField was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"entity_type",
"name",
"updated_at",
"id",
"field_type",
"position",
"enabled",
"created_at"
]
},
"CustomFieldEnumValue": {
"type": "object",
"properties": {
"id": {
"description": "The unique public ID for the Custom Field.",
"type": "string",
"format": "uuid"
},
"value": {
"maxLength": 63,
"minLength": 1,
"description": "A string value within the domain of this Custom Field.",
"type": "string"
},
"position": {
"description": "An integer indicating the position of this Value with respect to the other CustomFieldEnumValues in the enumeration.",
"type": "integer",
"format": "int64"
},
"color_key": {
"description": "A color key associated with this CustomFieldEnumValue.",
"type": "string",
"nullable": true
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string",
"enum": [
"custom-field-enum-value"
]
},
"enabled": {
"description": "When true, the CustomFieldEnumValue can be selected for the CustomField.",
"x-doc-skip": true,
"type": "boolean"
}
},
"additionalProperties": false,
"required": [
"id",
"value",
"position",
"color_key",
"entity_type",
"enabled"
]
},
"CustomFieldValueParams": {
"type": "object",
"properties": {
"field_id": {
"description": "The unique public ID for the CustomField.",
"type": "string",
"format": "uuid"
},
"value_id": {
"description": "The unique public ID for the CustomFieldEnumValue.",
"type": "string",
"format": "uuid"
},
"value": {
"description": "A literal value for the CustomField. Currently ignored.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"field_id",
"value_id"
]
},
"DataConflictError": {
"description": "Error returned when Datomic tx fails due to Datomc :db.error/cas-failed error",
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"data-conflict-error"
]
},
"message": {
"description": "An explanatory message: \"The update failed due to a data conflict. Please refresh and try again.\"",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"error",
"message"
]
},
"DeleteStories": {
"x-doc-skip": true,
"type": "object",
"properties": {
"story_ids": {
"description": "An array of IDs of Stories to delete.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
}
},
"additionalProperties": false,
"required": [
"story_ids"
]
},
"DisabledFeatureError": {
"type": "object",
"properties": {
"feature_tag": {
"description": "The feature that is disabled",
"type": "string"
},
"message": {
"description": "The message explaining the error",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"feature_tag",
"message"
]
},
"DocSlim": {
"type": "object",
"properties": {
"id": {
"description": "The public id of the Doc",
"type": "string",
"format": "uuid"
},
"title": {
"description": "The Docs Title",
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"id",
"title"
]
},
"EntityTemplate": {
"description": "An entity template can be used to prefill various fields when creating new stories.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"id": {
"description": "The unique identifier for the entity template.",
"type": "string",
"format": "uuid"
},
"created_at": {
"description": "The time/date when the entity template was created.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "The time/date when the entity template was last updated.",
"type": "string",
"format": "date-time"
},
"name": {
"description": "The template's name.",
"type": "string"
},
"author_id": {
"description": "The unique ID of the member who created the template.",
"type": "string",
"format": "uuid"
},
"last_used_at": {
"description": "The last time that someone created an entity using this template.",
"type": "string",
"format": "date-time"
},
"story_contents": {
"$ref": "#/components/schemas/StoryContents"
}
},
"additionalProperties": false,
"required": [
"entity_type",
"id",
"created_at",
"updated_at",
"name",
"author_id",
"last_used_at",
"story_contents"
]
},
"Epic": {
"description": "An Epic is a collection of stories that together might make up a release, a objective, or some other large initiative that you are working on.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Epic.",
"type": "string"
},
"description": {
"description": "The Epic's description.",
"type": "string"
},
"archived": {
"description": "True/false boolean that indicates whether the Epic is archived or not.",
"type": "boolean"
},
"started": {
"description": "A true/false boolean indicating if the Epic has been started.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"labels": {
"description": "An array of Labels attached to the Epic.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LabelSlim"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"member_mention_ids": {
"description": "An array of Member IDs that have been mentioned in the Epic description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"associated_groups": {
"description": "An array containing Group IDs and Group-owned story counts for the Epic's associated groups.",
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicAssociatedGroup"
}
},
"project_ids": {
"description": "The IDs of Projects related to this Epic.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"stories_without_projects": {
"description": "The number of stories in this epic which are not associated with a project.",
"type": "integer",
"format": "int64"
},
"completed_at_override": {
"description": "A manual override for the time/date the Epic was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"productboard_plugin_id": {
"description": "The ID of the associated productboard integration.",
"type": "string",
"format": "uuid",
"nullable": true
},
"started_at": {
"description": "The time/date the Epic was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"description": "The time/date the Epic was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"objective_ids": {
"description": "An array of IDs for Objectives to which this epic is related.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"name": {
"description": "The name of the Epic.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"completed": {
"description": "A true/false boolean indicating if the Epic has been completed.",
"type": "boolean"
},
"comments": {
"description": "A nested array of threaded comments.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ThreadedComment"
}
},
"productboard_url": {
"description": "The URL of the associated productboard feature.",
"type": "string",
"nullable": true
},
"planned_start_date": {
"description": "The Epic's planned start date.",
"type": "string",
"format": "date-time",
"nullable": true
},
"state": {
"description": "`Deprecated` The workflow state that the Epic is in.",
"type": "string"
},
"milestone_id": {
"description": "`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`.",
"type": "integer",
"format": "int64",
"nullable": true
},
"requested_by_id": {
"description": "The ID of the Member that requested the epic.",
"type": "string",
"format": "uuid"
},
"epic_state_id": {
"description": "The ID of the Epic State.",
"type": "integer",
"format": "int64"
},
"label_ids": {
"description": "An array of Label ids attached to the Epic.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"started_at_override": {
"description": "A manual override for the time/date the Epic was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_id": {
"description": "`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.",
"type": "string",
"format": "uuid",
"nullable": true
},
"updated_at": {
"description": "The time/date the Epic was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_mention_ids": {
"description": "An array of Group IDs that have been mentioned in the Epic description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"productboard_id": {
"description": "The ID of the associated productboard feature.",
"type": "string",
"format": "uuid",
"nullable": true
},
"follower_ids": {
"description": "An array of UUIDs for any Members you want to add as Followers on this Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_ids": {
"description": "An array of UUIDS for Groups to which this Epic is related.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs for any members you want to add as Owners on this new Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"description": "This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Epic.",
"type": "integer",
"format": "int64"
},
"health": {
"$ref": "#/components/schemas/Health"
},
"position": {
"description": "The Epic's relative position in the Epic workflow state.",
"type": "integer",
"format": "int64"
},
"productboard_name": {
"description": "The name of the associated productboard feature.",
"type": "string",
"nullable": true
},
"deadline": {
"description": "The Epic's deadline.",
"type": "string",
"format": "date-time",
"nullable": true
},
"stats": {
"$ref": "#/components/schemas/EpicStats"
},
"created_at": {
"description": "The time/date the Epic was created.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"app_url",
"description",
"archived",
"started",
"entity_type",
"labels",
"mention_ids",
"member_mention_ids",
"associated_groups",
"project_ids",
"stories_without_projects",
"completed_at_override",
"productboard_plugin_id",
"started_at",
"completed_at",
"objective_ids",
"name",
"global_id",
"completed",
"comments",
"productboard_url",
"planned_start_date",
"state",
"milestone_id",
"requested_by_id",
"epic_state_id",
"label_ids",
"started_at_override",
"group_id",
"updated_at",
"group_mention_ids",
"productboard_id",
"follower_ids",
"group_ids",
"owner_ids",
"external_id",
"id",
"position",
"productboard_name",
"deadline",
"stats",
"created_at"
]
},
"EpicAssociatedGroup": {
"type": "object",
"properties": {
"group_id": {
"description": "The Group ID of the associated group.",
"type": "string",
"format": "uuid"
},
"associated_stories_count": {
"description": "The number of stories this Group owns in the Epic.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"group_id"
]
},
"EpicPaginatedResults": {
"description": "Results schema for paginated Epic listing.",
"type": "object",
"properties": {
"data": {
"description": "Array of Epic objects on the current page",
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicSlim"
}
},
"next": {
"description": "The next page number if there are more results, or null for the last page",
"type": "integer",
"format": "int64",
"nullable": true
},
"total": {
"description": "The total number of Epics matching the query over all pages",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"data",
"next",
"total"
]
},
"EpicSearchResult": {
"description": "An Epic in search results. This is typed differently from Epic because the details=slim search argument will omit some fields.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Epic.",
"type": "string"
},
"description": {
"description": "The Epic's description.",
"type": "string"
},
"archived": {
"description": "True/false boolean that indicates whether the Epic is archived or not.",
"type": "boolean"
},
"started": {
"description": "A true/false boolean indicating if the Epic has been started.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"labels": {
"description": "An array of Labels attached to the Epic.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LabelSlim"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"member_mention_ids": {
"description": "An array of Member IDs that have been mentioned in the Epic description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"associated_groups": {
"description": "An array containing Group IDs and Group-owned story counts for the Epic's associated groups.",
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicAssociatedGroup"
}
},
"project_ids": {
"description": "The IDs of Projects related to this Epic.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"stories_without_projects": {
"description": "The number of stories in this epic which are not associated with a project.",
"type": "integer",
"format": "int64"
},
"completed_at_override": {
"description": "A manual override for the time/date the Epic was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"productboard_plugin_id": {
"description": "The ID of the associated productboard integration.",
"type": "string",
"format": "uuid",
"nullable": true
},
"started_at": {
"description": "The time/date the Epic was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"description": "The time/date the Epic was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"objective_ids": {
"description": "An array of IDs for Objectives to which this epic is related.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"name": {
"description": "The name of the Epic.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"completed": {
"description": "A true/false boolean indicating if the Epic has been completed.",
"type": "boolean"
},
"comments": {
"description": "A nested array of threaded comments.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ThreadedComment"
}
},
"productboard_url": {
"description": "The URL of the associated productboard feature.",
"type": "string",
"nullable": true
},
"planned_start_date": {
"description": "The Epic's planned start date.",
"type": "string",
"format": "date-time",
"nullable": true
},
"state": {
"description": "`Deprecated` The workflow state that the Epic is in.",
"type": "string"
},
"milestone_id": {
"description": "`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`.",
"type": "integer",
"format": "int64",
"nullable": true
},
"requested_by_id": {
"description": "The ID of the Member that requested the epic.",
"type": "string",
"format": "uuid"
},
"epic_state_id": {
"description": "The ID of the Epic State.",
"type": "integer",
"format": "int64"
},
"label_ids": {
"description": "An array of Label ids attached to the Epic.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"started_at_override": {
"description": "A manual override for the time/date the Epic was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_id": {
"description": "`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.",
"type": "string",
"format": "uuid",
"nullable": true
},
"updated_at": {
"description": "The time/date the Epic was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_mention_ids": {
"description": "An array of Group IDs that have been mentioned in the Epic description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"productboard_id": {
"description": "The ID of the associated productboard feature.",
"type": "string",
"format": "uuid",
"nullable": true
},
"follower_ids": {
"description": "An array of UUIDs for any Members you want to add as Followers on this Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_ids": {
"description": "An array of UUIDS for Groups to which this Epic is related.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs for any members you want to add as Owners on this new Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"description": "This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Epic.",
"type": "integer",
"format": "int64"
},
"health": {
"$ref": "#/components/schemas/Health"
},
"position": {
"description": "The Epic's relative position in the Epic workflow state.",
"type": "integer",
"format": "int64"
},
"productboard_name": {
"description": "The name of the associated productboard feature.",
"type": "string",
"nullable": true
},
"deadline": {
"description": "The Epic's deadline.",
"type": "string",
"format": "date-time",
"nullable": true
},
"stats": {
"$ref": "#/components/schemas/EpicStats"
},
"created_at": {
"description": "The time/date the Epic was created.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"app_url",
"archived",
"started",
"entity_type",
"labels",
"mention_ids",
"member_mention_ids",
"associated_groups",
"project_ids",
"stories_without_projects",
"completed_at_override",
"productboard_plugin_id",
"started_at",
"completed_at",
"objective_ids",
"name",
"global_id",
"completed",
"productboard_url",
"planned_start_date",
"state",
"milestone_id",
"requested_by_id",
"epic_state_id",
"label_ids",
"started_at_override",
"group_id",
"updated_at",
"group_mention_ids",
"productboard_id",
"follower_ids",
"group_ids",
"owner_ids",
"external_id",
"id",
"position",
"productboard_name",
"deadline",
"stats",
"created_at"
]
},
"EpicSearchResults": {
"description": "The results of the Epic search query.",
"type": "object",
"properties": {
"total": {
"description": "The total number of matches for the search query. The first 1000 matches can be paged through via the API.",
"type": "integer",
"format": "int64"
},
"data": {
"description": "A list of search results.",
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicSearchResult"
}
},
"next": {
"description": "The URL path and query string for the next page of search results.",
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"total",
"data",
"next"
]
},
"EpicSlim": {
"description": "EpicSlim represents the same resource as an Epic but is more light-weight, including all Epic fields except the comments array. The description string can be optionally included. Use the [Get Epic](#Get-Epic) endpoint to fetch the unabridged payload for an Epic.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Epic.",
"type": "string"
},
"description": {
"description": "The Epic's description.",
"type": "string"
},
"archived": {
"description": "True/false boolean that indicates whether the Epic is archived or not.",
"type": "boolean"
},
"started": {
"description": "A true/false boolean indicating if the Epic has been started.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"labels": {
"description": "An array of Labels attached to the Epic.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LabelSlim"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"member_mention_ids": {
"description": "An array of Member IDs that have been mentioned in the Epic description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"associated_groups": {
"description": "An array containing Group IDs and Group-owned story counts for the Epic's associated groups.",
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicAssociatedGroup"
}
},
"project_ids": {
"description": "The IDs of Projects related to this Epic.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"stories_without_projects": {
"description": "The number of stories in this epic which are not associated with a project.",
"type": "integer",
"format": "int64"
},
"completed_at_override": {
"description": "A manual override for the time/date the Epic was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"productboard_plugin_id": {
"description": "The ID of the associated productboard integration.",
"type": "string",
"format": "uuid",
"nullable": true
},
"started_at": {
"description": "The time/date the Epic was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"description": "The time/date the Epic was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"objective_ids": {
"description": "An array of IDs for Objectives to which this epic is related.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"name": {
"description": "The name of the Epic.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"completed": {
"description": "A true/false boolean indicating if the Epic has been completed.",
"type": "boolean"
},
"productboard_url": {
"description": "The URL of the associated productboard feature.",
"type": "string",
"nullable": true
},
"planned_start_date": {
"description": "The Epic's planned start date.",
"type": "string",
"format": "date-time",
"nullable": true
},
"state": {
"description": "`Deprecated` The workflow state that the Epic is in.",
"type": "string"
},
"milestone_id": {
"description": "`Deprecated` The ID of the Objective this Epic is related to. Use `objective_ids`.",
"type": "integer",
"format": "int64",
"nullable": true
},
"requested_by_id": {
"description": "The ID of the Member that requested the epic.",
"type": "string",
"format": "uuid"
},
"epic_state_id": {
"description": "The ID of the Epic State.",
"type": "integer",
"format": "int64"
},
"label_ids": {
"description": "An array of Label ids attached to the Epic.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"started_at_override": {
"description": "A manual override for the time/date the Epic was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_id": {
"description": "`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.",
"type": "string",
"format": "uuid",
"nullable": true
},
"updated_at": {
"description": "The time/date the Epic was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_mention_ids": {
"description": "An array of Group IDs that have been mentioned in the Epic description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"productboard_id": {
"description": "The ID of the associated productboard feature.",
"type": "string",
"format": "uuid",
"nullable": true
},
"follower_ids": {
"description": "An array of UUIDs for any Members you want to add as Followers on this Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_ids": {
"description": "An array of UUIDS for Groups to which this Epic is related.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs for any members you want to add as Owners on this new Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"description": "This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Epic.",
"type": "integer",
"format": "int64"
},
"position": {
"description": "The Epic's relative position in the Epic workflow state.",
"type": "integer",
"format": "int64"
},
"productboard_name": {
"description": "The name of the associated productboard feature.",
"type": "string",
"nullable": true
},
"deadline": {
"description": "The Epic's deadline.",
"type": "string",
"format": "date-time",
"nullable": true
},
"stats": {
"$ref": "#/components/schemas/EpicStats"
},
"created_at": {
"description": "The time/date the Epic was created.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"app_url",
"archived",
"started",
"entity_type",
"labels",
"mention_ids",
"member_mention_ids",
"associated_groups",
"project_ids",
"stories_without_projects",
"completed_at_override",
"productboard_plugin_id",
"started_at",
"completed_at",
"objective_ids",
"name",
"global_id",
"completed",
"productboard_url",
"planned_start_date",
"state",
"milestone_id",
"requested_by_id",
"epic_state_id",
"label_ids",
"started_at_override",
"group_id",
"updated_at",
"group_mention_ids",
"productboard_id",
"follower_ids",
"group_ids",
"owner_ids",
"external_id",
"id",
"position",
"productboard_name",
"deadline",
"stats",
"created_at"
]
},
"EpicState": {
"description": "Epic State is any of the at least 3 columns. Epic States correspond to one of 3 types: Unstarted, Started, or Done.",
"type": "object",
"properties": {
"description": {
"description": "The description of what sort of Epics belong in that Epic State.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"description": "The hex color for this Epic State.",
"minLength": 1,
"type": "string"
},
"name": {
"description": "The Epic State's name.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"type": {
"description": "The type of Epic State (Unstarted, Started, or Done)",
"type": "string"
},
"updated_at": {
"description": "When the Epic State was last updated.",
"type": "string",
"format": "date-time"
},
"id": {
"description": "The unique ID of the Epic State.",
"type": "integer",
"format": "int64"
},
"position": {
"description": "The position that the Epic State is in, starting with 0 at the left.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date the Epic State was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"description",
"entity_type",
"name",
"global_id",
"type",
"updated_at",
"id",
"position",
"created_at"
]
},
"EpicStats": {
"description": "A group of calculated values for this Epic.",
"type": "object",
"properties": {
"num_points_done": {
"description": "The total number of completed points in this Epic.",
"type": "integer",
"format": "int64"
},
"num_related_documents": {
"description": "The total number of documents associated with this Epic.",
"type": "integer",
"format": "int64"
},
"num_stories_unstarted": {
"description": "The total number of unstarted Stories in this Epic.",
"type": "integer",
"format": "int64"
},
"num_stories_total": {
"description": "The total number of Stories in this Epic.",
"type": "integer",
"format": "int64"
},
"last_story_update": {
"description": "The date of the last update of a Story in this Epic.",
"type": "string",
"format": "date-time",
"nullable": true
},
"num_points_started": {
"description": "The total number of started points in this Epic.",
"type": "integer",
"format": "int64"
},
"num_points_unstarted": {
"description": "The total number of unstarted points in this Epic.",
"type": "integer",
"format": "int64"
},
"num_stories_started": {
"description": "The total number of started Stories in this Epic.",
"type": "integer",
"format": "int64"
},
"num_stories_unestimated": {
"description": "The total number of Stories with no point estimate.",
"type": "integer",
"format": "int64"
},
"num_stories_backlog": {
"description": "The total number of backlog Stories in this Epic.",
"type": "integer",
"format": "int64"
},
"num_points_backlog": {
"description": "The total number of backlog points in this Epic.",
"type": "integer",
"format": "int64"
},
"num_points": {
"description": "The total number of points in this Epic.",
"type": "integer",
"format": "int64"
},
"num_stories_done": {
"description": "The total number of done Stories in this Epic.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"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"
]
},
"EpicWorkflow": {
"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. ",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"id": {
"description": "The unique ID of the Epic Workflow.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The date the Epic Workflow was created.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "The date the Epic Workflow was updated.",
"type": "string",
"format": "date-time"
},
"default_epic_state_id": {
"description": "The unique ID of the default Epic State that new Epics are assigned by default.",
"type": "integer",
"format": "int64"
},
"epic_states": {
"description": "A map of the Epic States in this Epic Workflow.",
"type": "array",
"items": {
"$ref": "#/components/schemas/EpicState"
}
}
},
"additionalProperties": false,
"required": [
"entity_type",
"id",
"created_at",
"updated_at",
"default_epic_state_id",
"epic_states"
]
},
"Group": {
"description": "A Group.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Group.",
"type": "string"
},
"description": {
"description": "The description of the Group.",
"type": "string"
},
"archived": {
"description": "Whether or not the Group is archived.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"color": {
"description": "The hex color to be displayed with the Group (for example, \"#ff0000\").",
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"minLength": 1,
"type": "string",
"nullable": true
},
"num_stories_started": {
"description": "The number of stories assigned to the group which are in a started workflow state.",
"type": "integer",
"format": "int64"
},
"mention_name": {
"pattern": "^[a-z0-9\\-\\_\\.]+$",
"minLength": 1,
"description": "The mention name of the Group.",
"type": "string"
},
"name": {
"description": "The name of the Group.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"color_key": {
"description": "The color key to be displayed with the Group.",
"type": "string",
"enum": [
"blue",
"purple",
"midnight-blue",
"orange",
"yellow-green",
"brass",
"gray",
"fuchsia",
"yellow",
"pink",
"sky-blue",
"green",
"red",
"black",
"slate",
"turquoise"
],
"nullable": true
},
"num_stories": {
"description": "The total number of stories assigned to the group.",
"type": "integer",
"format": "int64"
},
"num_epics_started": {
"description": "The number of epics assigned to the group which are in the started workflow state.",
"type": "integer",
"format": "int64"
},
"num_stories_backlog": {
"description": "The number of stories assigned to the group which are in a backlog workflow state.",
"type": "integer",
"format": "int64"
},
"id": {
"description": "The id of the Group.",
"type": "string",
"format": "uuid"
},
"display_icon": {
"$ref": "#/components/schemas/Icon"
},
"default_workflow_id": {
"description": "The ID of the default workflow for stories created in this group.",
"type": "integer",
"format": "int64",
"nullable": true
},
"member_ids": {
"description": "The Member IDs contain within the Group.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"workflow_ids": {
"description": "The Workflow IDs contained within the Group.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"additionalProperties": false,
"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"
]
},
"Health": {
"description": "The current health status of the Epic.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"author_id": {
"description": "The ID of the permission who created or updated the Health record.",
"type": "string",
"format": "uuid"
},
"epic_id": {
"description": "The ID of the Epic associated with this Health record.",
"type": "integer",
"format": "int64"
},
"objective_id": {
"description": "The ID of the Objective associated with this Health record.",
"type": "integer",
"format": "int64"
},
"updated_at": {
"description": "The time that the Health record was updated.",
"type": "string",
"format": "date-time"
},
"status": {
"description": "The health status of the Epic or Objective.",
"type": "string",
"enum": [
"At Risk",
"On Track",
"Off Track",
"No Health"
]
},
"id": {
"description": "The unique ID of the Health record.",
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"description": "The time that the Health record was created.",
"type": "string",
"format": "date-time"
},
"text": {
"description": "The text of the Health record.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"entity_type",
"status",
"id"
]
},
"History": {
"description": "A history item is a group of actions that represent a transactional change to a Story.",
"type": "object",
"properties": {
"actor_name": {
"description": "The name of the actor that performed the action, if it can be determined.",
"type": "string"
},
"changed_at": {
"description": "The date when the change occurred.",
"type": "string"
},
"primary_id": {
"description": "The ID of the primary entity that has changed, if applicable.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"references": {
"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.",
"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"
}
]
}
},
"actions": {
"description": "An array of actions that were performed for the change.",
"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"
}
]
}
},
"member_id": {
"description": "The ID of the member who performed the change.",
"type": "string",
"format": "uuid"
},
"external_id": {
"description": "The ID of the webhook that handled the change.",
"type": "string"
},
"id": {
"description": "The ID representing the change for the story.",
"type": "string",
"format": "uuid"
},
"version": {
"description": "The version of the change format.",
"type": "string",
"enum": [
"v1"
]
},
"webhook_id": {
"description": "The ID of the webhook that handled the change.",
"type": "string",
"nullable": true
},
"automation_id": {
"description": "The ID of the automation that performed the change.",
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"required": [
"changed_at",
"actions",
"id",
"version"
]
},
"HistoryActionBranchCreate": {
"description": "An action representing a VCS Branch being created.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"name": {
"description": "The name of the VCS Branch that was pushed",
"type": "string"
},
"url": {
"description": "The URL from the provider of the VCS Branch that was pushed",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"create"
]
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"name",
"url",
"action"
]
},
"HistoryActionBranchMerge": {
"description": "An action representing a VCS Branch being merged.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"name": {
"description": "The name of the VCS Branch that was pushed",
"type": "string"
},
"url": {
"description": "The URL from the provider of the VCS Branch that was pushed",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"merge"
]
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"name",
"url",
"action"
]
},
"HistoryActionBranchPush": {
"description": "An action representing a VCS Branch being pushed.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"name": {
"description": "The name of the VCS Branch that was pushed",
"type": "string"
},
"url": {
"description": "The URL from the provider of the VCS Branch that was pushed",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"push"
]
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"name",
"url",
"action"
]
},
"HistoryActionLabelCreate": {
"description": "An action representing a Label being created.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"create"
]
},
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Label.",
"type": "string"
},
"name": {
"description": "The name of the Label.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"app_url",
"name"
]
},
"HistoryActionLabelDelete": {
"description": "An action representing a Label being deleted.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"delete"
]
},
"name": {
"description": "The name of the Label.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"name"
]
},
"HistoryActionLabelUpdate": {
"description": "An action representing a Label being updated.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"update"
]
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action"
]
},
"HistoryActionProjectUpdate": {
"description": "An action representing a Project being updated.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"update"
]
},
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Project.",
"type": "string"
},
"name": {
"description": "The name of the Project.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"app_url",
"name"
]
},
"HistoryActionPullRequest": {
"description": "An action representing various operations for a Pull Request.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"open",
"update",
"reopen",
"close",
"sync",
"comment"
]
},
"number": {
"description": "The VCS Repository-specific ID for the Pull Request.",
"type": "integer",
"format": "int64"
},
"title": {
"description": "The title of the Pull Request.",
"type": "string"
},
"url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The URL from the provider of the VCS Pull Request.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"number",
"title",
"url"
]
},
"HistoryActionStoryCommentCreate": {
"description": "An action representing a Story Comment being created.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"create"
]
},
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Story Comment.",
"type": "string"
},
"text": {
"description": "The text of the Story Comment.",
"type": "string"
},
"author_id": {
"description": "The Member ID of who created the Story Comment.",
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"app_url",
"text",
"author_id"
]
},
"HistoryActionStoryCreate": {
"description": "An action representing a Story being created.",
"type": "object",
"properties": {
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Story.",
"type": "string"
},
"description": {
"description": "The description of the Story.",
"type": "string"
},
"started": {
"description": "Whether or not the Story has been started.",
"type": "boolean"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"task_ids": {
"description": "An array of Task IDs on this Story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"story_type": {
"description": "The type of Story; either feature, bug, or chore.",
"type": "string",
"enum": [
"feature",
"chore",
"bug"
]
},
"name": {
"description": "The name of the Story.",
"type": "string"
},
"completed": {
"description": "Whether or not the Story is completed.",
"type": "boolean"
},
"blocker": {
"description": "Whether or not the Story is blocking another Story.",
"type": "boolean"
},
"epic_id": {
"description": "The Epic ID for this Story.",
"type": "integer",
"format": "int64"
},
"requested_by_id": {
"description": "The ID of the Member that requested the Story.",
"type": "string",
"format": "uuid"
},
"iteration_id": {
"description": "The Iteration ID the Story is in.",
"type": "integer",
"format": "int64",
"nullable": true
},
"label_ids": {
"description": "An array of Labels IDs attached to the Story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"group_id": {
"description": "The Team IDs for the followers of the Story.",
"type": "string",
"format": "uuid"
},
"workflow_state_id": {
"description": "An array of Workflow State IDs attached to the Story.",
"type": "integer",
"format": "int64"
},
"object_story_link_ids": {
"description": "An array of Story IDs that are the object of a Story Link relationship.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"follower_ids": {
"description": "An array of Member IDs for the followers of the Story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of Member IDs that are the owners of the Story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"custom_field_value_ids": {
"description": "An array of Custom Field Enum Value ids on this Story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"estimate": {
"description": "The estimate (or point value) for the Story.",
"type": "integer",
"format": "int64"
},
"subject_story_link_ids": {
"description": "An array of Story IDs that are the subject of a Story Link relationship.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"create"
]
},
"blocked": {
"description": "Whether or not the Story is blocked by another Story.",
"type": "boolean"
},
"project_id": {
"description": "The Project ID of the Story is in.",
"type": "integer",
"format": "int64"
},
"deadline": {
"description": "The timestamp representing the Story's deadline.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"app_url",
"entity_type",
"story_type",
"name",
"id",
"action"
]
},
"HistoryActionStoryDelete": {
"description": "An action representing a Story being deleted.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"delete"
]
},
"name": {
"description": "The name of the Story.",
"type": "string"
},
"story_type": {
"description": "The type of Story; either feature, bug, or chore.",
"type": "string",
"enum": [
"feature",
"chore",
"bug"
]
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"name",
"story_type"
]
},
"HistoryActionStoryLinkCreate": {
"description": "An action representing a Story Link being created.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"create"
]
},
"verb": {
"description": "The verb describing the link's relationship.",
"type": "string",
"enum": [
"blocks",
"duplicates",
"relates to"
]
},
"subject_id": {
"description": "The Story ID of the subject Story.",
"type": "integer",
"format": "int64"
},
"object_id": {
"description": "The Story ID of the object Story.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"verb",
"subject_id",
"object_id"
]
},
"HistoryActionStoryLinkDelete": {
"description": "An action representing a Story Link being deleted.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"delete"
]
},
"verb": {
"description": "The verb describing the link's relationship.",
"type": "string",
"enum": [
"blocks",
"duplicates",
"relates to"
]
},
"subject_id": {
"description": "The Story ID of the subject Story.",
"type": "integer",
"format": "int64",
"nullable": true
},
"object_id": {
"description": "The Story ID of the object Story.",
"type": "integer",
"format": "int64",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"verb",
"subject_id",
"object_id"
]
},
"HistoryActionStoryLinkUpdate": {
"description": "An action representing a Story Link being updated.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"update"
]
},
"verb": {
"description": "The verb describing the link's relationship.",
"type": "string",
"enum": [
"blocks",
"duplicates",
"relates to"
]
},
"subject_id": {
"description": "The Story ID of the subject Story.",
"type": "integer",
"format": "int64"
},
"object_id": {
"description": "The Story ID of the object Story.",
"type": "integer",
"format": "int64"
},
"changes": {
"$ref": "#/components/schemas/HistoryChangesStoryLink"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"verb",
"subject_id",
"object_id",
"changes"
]
},
"HistoryActionStoryUpdate": {
"description": "An action representing a Story being updated.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"update"
]
},
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Story.",
"type": "string"
},
"changes": {
"$ref": "#/components/schemas/HistoryChangesStory"
},
"name": {
"description": "The name of the Story.",
"type": "string"
},
"story_type": {
"description": "The type of Story; either feature, bug, or chore.",
"type": "string",
"enum": [
"feature",
"chore",
"bug"
]
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"app_url",
"name",
"story_type"
]
},
"HistoryActionTaskCreate": {
"description": "An action representing a Task being created.",
"type": "object",
"properties": {
"description": {
"description": "The description of the Task.",
"type": "string"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"mention_ids": {
"description": "An array of Member IDs that represent who has been mentioned in the Task.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_mention_ids": {
"description": "An array of Groups IDs that represent which have been mentioned in the Task.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of Member IDs that represent the Task's owners.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"create"
]
},
"complete": {
"description": "Whether or not the Task is complete.",
"type": "boolean"
},
"deadline": {
"description": "A timestamp that represent's the Task's deadline.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"description",
"entity_type",
"id",
"action",
"complete"
]
},
"HistoryActionTaskDelete": {
"description": "An action representing a Task being deleted.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"delete"
]
},
"description": {
"description": "The description of the Task being deleted.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"description"
]
},
"HistoryActionTaskUpdate": {
"description": "An action representing a Task being updated.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "integer",
"format": "int64"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"update"
]
},
"changes": {
"$ref": "#/components/schemas/HistoryChangesTask"
},
"complete": {
"description": "Whether or not the Task is complete.",
"type": "boolean"
},
"description": {
"description": "The description of the Task.",
"type": "string"
},
"story_id": {
"description": "The Story ID that contains the Task.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"changes",
"description",
"story_id"
]
},
"HistoryActionWorkspace2BulkUpdate": {
"description": "An action representing a bulk operation within a workspace2.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "string",
"format": "uuid"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"action": {
"description": "The action of the entity referenced.",
"type": "string",
"enum": [
"bulk-update"
]
},
"name": {
"description": "The name of the workspace2 in which the BulkUpdate occurred.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"action",
"name"
]
},
"HistoryChangesStory": {
"description": "The changes that have occurred as a result of the action.",
"type": "object",
"properties": {
"description": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"archived": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"started": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"task_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"mention_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"story_type": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"name": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"completed": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"blocker": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"epic_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"branch_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"commit_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"requested_by_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewUuid"
},
"iteration_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"label_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"group_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewUuid"
},
"workflow_state_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"object_story_link_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"follower_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"owner_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"custom_field_value_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"estimate": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"subject_story_link_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesInt"
},
"blocked": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"project_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"deadline": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
}
},
"additionalProperties": false
},
"HistoryChangesStoryLink": {
"description": "The changes that have occurred as a result of the action.",
"type": "object",
"properties": {
"verb": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"object_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
},
"subject_id": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewInt"
}
},
"additionalProperties": false
},
"HistoryChangesTask": {
"description": "The changes that have occurred as a result of the action.",
"type": "object",
"properties": {
"complete": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewBool"
},
"description": {
"$ref": "#/components/schemas/StoryHistoryChangeOldNewStr"
},
"mention_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
},
"owner_ids": {
"$ref": "#/components/schemas/StoryHistoryChangeAddsRemovesUuid"
}
},
"additionalProperties": false
},
"HistoryReferenceBranch": {
"description": "A reference to a VCS Branch.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"name": {
"description": "The name of the entity referenced.",
"type": "string"
},
"url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The external URL for the Branch.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"name",
"url"
]
},
"HistoryReferenceCommit": {
"description": "A reference to a VCS Commit.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"message": {
"description": "The message from the Commit.",
"type": "string"
},
"url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The external URL for the Branch.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"message",
"url"
]
},
"HistoryReferenceCustomFieldEnumValue": {
"description": "A reference to a CustomField value asserted on a Story.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"string_value": {
"description": "The custom-field enum value as a string.",
"type": "string",
"nullable": true
},
"enum_value_enabled": {
"description": "Whether or not the custom-field enum value is enabled.",
"type": "boolean",
"nullable": true
},
"field_id": {
"description": "The public-id of the parent custom-field of this enum value.",
"type": "string",
"format": "uuid"
},
"field_type": {
"description": "The type variety of the parent custom-field of this enum value.",
"type": "string"
},
"field_name": {
"description": "The name as it is displayed to the user of the parent custom-field of this enum value.",
"type": "string"
},
"field_enabled": {
"description": "Whether or not the custom-field is enabled.",
"type": "boolean"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"string_value",
"enum_value_enabled",
"field_id",
"field_type",
"field_name",
"field_enabled"
]
},
"HistoryReferenceEpic": {
"description": "A reference to an Epic.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Epic.",
"type": "string"
},
"name": {
"description": "The name of the entity referenced.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"app_url",
"name"
]
},
"HistoryReferenceGeneral": {
"description": "A default reference for entity types that don't have extra fields.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"name": {
"description": "The name of the entity referenced.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"name"
]
},
"HistoryReferenceGroup": {
"description": "A reference to a Group.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"type": "string",
"format": "uuid"
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"name": {
"description": "The name of the entity referenced.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"name"
]
},
"HistoryReferenceIteration": {
"description": "A reference to an Iteration.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Iteration.",
"type": "string"
},
"name": {
"description": "The name of the entity referenced.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"app_url",
"name"
]
},
"HistoryReferenceLabel": {
"description": "A reference to an Label.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Label.",
"type": "string"
},
"name": {
"description": "The name of the entity referenced.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"app_url",
"name"
]
},
"HistoryReferenceProject": {
"description": "A reference to an Project.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Project.",
"type": "string"
},
"name": {
"description": "The name of the entity referenced.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"app_url",
"name"
]
},
"HistoryReferenceStory": {
"description": "A reference to a Story.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"app_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The application URL of the Story.",
"type": "string"
},
"name": {
"description": "The name of the entity referenced.",
"type": "string"
},
"story_type": {
"description": "If the referenced entity is a Story, either \"bug\", \"chore\", or \"feature\".",
"type": "string",
"enum": [
"feature",
"chore",
"bug"
]
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"app_url",
"name",
"story_type"
]
},
"HistoryReferenceStoryTask": {
"description": "A reference to a Story Task.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"description": {
"description": "The description of the Story Task.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"description"
]
},
"HistoryReferenceWorkflowState": {
"description": "A references to a Story Workflow State.",
"type": "object",
"properties": {
"id": {
"description": "The ID of the entity referenced.",
"oneOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "string",
"format": "uuid"
}
]
},
"entity_type": {
"description": "The type of entity referenced.",
"type": "string"
},
"type": {
"description": "Either \"backlog\", \"unstarted\", \"started\", or \"done\".",
"type": "string",
"enum": [
"started",
"backlog",
"unstarted",
"done"
]
},
"name": {
"description": "The name of the entity referenced.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"entity_type",
"type",
"name"
]
},
"Icon": {
"description": "Icons are used to attach images to Groups, Workspaces, Members, and Loading screens in the Shortcut web application.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"id": {
"description": "The unique ID of the Icon.",
"type": "string",
"format": "uuid"
},
"created_at": {
"description": "The time/date that the Icon was created.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "The time/date that the Icon was updated.",
"type": "string",
"format": "date-time"
},
"url": {
"description": "The URL of the Icon.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"entity_type",
"id",
"created_at",
"updated_at",
"url"
]
},
"Identity": {
"description": "The Identity of the VCS user that authored the Commit.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"name": {
"description": "This is your login in VCS.",
"type": "string",
"nullable": true
},
"type": {
"description": "The service this Identity is for.",
"type": "string",
"enum": [
"slack",
"github",
"gitlab",
"bitbucket"
],
"nullable": true
}
},
"additionalProperties": false,
"required": [
"entity_type",
"name",
"type"
]
},
"Iteration": {
"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.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Iteration.",
"type": "string"
},
"description": {
"description": "The description of the iteration.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource",
"type": "string"
},
"labels": {
"description": "An array of labels attached to the iteration.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Label"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"member_mention_ids": {
"description": "An array of Member IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"associated_groups": {
"description": "An array containing Group IDs and Group-owned story counts for the Iteration's associated groups.",
"x-doc-skip": true,
"type": "array",
"items": {
"$ref": "#/components/schemas/IterationAssociatedGroup"
}
},
"name": {
"description": "The name of the iteration.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"label_ids": {
"description": "An array of label ids attached to the iteration.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"updated_at": {
"description": "The instant when this iteration was last updated.",
"type": "string",
"format": "date-time"
},
"group_mention_ids": {
"description": "An array of Group IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"end_date": {
"description": "The date this iteration ends.",
"type": "string",
"format": "date-time"
},
"follower_ids": {
"description": "An array of UUIDs for any Members listed as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_ids": {
"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.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"start_date": {
"description": "The date this iteration begins.",
"type": "string",
"format": "date-time"
},
"status": {
"description": "The status of the iteration. Values are either \"unstarted\", \"started\", or \"done\".",
"type": "string"
},
"id": {
"description": "The ID of the iteration.",
"type": "integer",
"format": "int64"
},
"stats": {
"$ref": "#/components/schemas/IterationStats"
},
"created_at": {
"description": "The instant when this iteration was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"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"
]
},
"IterationAssociatedGroup": {
"x-doc-skip": true,
"type": "object",
"properties": {
"group_id": {
"description": "The Group ID of the associated group.",
"type": "string",
"format": "uuid"
},
"associated_stories_count": {
"description": "The number of stories this Group owns in the Iteration.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"group_id"
]
},
"IterationSearchResults": {
"description": "The results of the Iteration search query.",
"type": "object",
"properties": {
"total": {
"description": "The total number of matches for the search query. The first 1000 matches can be paged through via the API.",
"type": "integer",
"format": "int64"
},
"data": {
"description": "A list of search results.",
"type": "array",
"items": {
"$ref": "#/components/schemas/IterationSlim"
}
},
"next": {
"description": "The URL path and query string for the next page of search results.",
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"total",
"data",
"next"
]
},
"IterationSlim": {
"description": "IterationSlim represents the same resource as an Iteration, but is more light-weight. Use the [Get Iteration](#Get-Iteration) endpoint to fetch the unabridged payload for an Iteration. ",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Iteration.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource",
"type": "string"
},
"labels": {
"description": "An array of labels attached to the iteration.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Label"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"member_mention_ids": {
"description": "An array of Member IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"associated_groups": {
"description": "An array containing Group IDs and Group-owned story counts for the Iteration's associated groups.",
"x-doc-skip": true,
"type": "array",
"items": {
"$ref": "#/components/schemas/IterationAssociatedGroup"
}
},
"name": {
"description": "The name of the iteration.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"label_ids": {
"description": "An array of label ids attached to the iteration.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"updated_at": {
"description": "The instant when this iteration was last updated.",
"type": "string",
"format": "date-time"
},
"group_mention_ids": {
"description": "An array of Group IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"end_date": {
"description": "The date this iteration ends.",
"type": "string",
"format": "date-time"
},
"follower_ids": {
"description": "An array of UUIDs for any Members listed as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_ids": {
"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.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"start_date": {
"description": "The date this iteration begins.",
"type": "string",
"format": "date-time"
},
"status": {
"description": "The status of the iteration. Values are either \"unstarted\", \"started\", or \"done\".",
"type": "string"
},
"id": {
"description": "The ID of the iteration.",
"type": "integer",
"format": "int64"
},
"stats": {
"$ref": "#/components/schemas/IterationStats"
},
"created_at": {
"description": "The instant when this iteration was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"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"
]
},
"IterationStats": {
"description": "A group of calculated values for this Iteration.",
"type": "object",
"properties": {
"num_points_done": {
"description": "The total number of completed points in this Iteration.",
"type": "integer",
"format": "int64"
},
"num_related_documents": {
"description": "The total number of documents related to an Iteration",
"type": "integer",
"format": "int64"
},
"average_cycle_time": {
"description": "The average cycle time (in seconds) of completed stories in this Iteration.",
"type": "integer",
"format": "int64"
},
"num_stories_unstarted": {
"description": "The total number of unstarted Stories in this Iteration.",
"type": "integer",
"format": "int64"
},
"num_points_started": {
"description": "The total number of started points in this Iteration.",
"type": "integer",
"format": "int64"
},
"num_points_unstarted": {
"description": "The total number of unstarted points in this Iteration.",
"type": "integer",
"format": "int64"
},
"num_stories_started": {
"description": "The total number of started Stories in this Iteration.",
"type": "integer",
"format": "int64"
},
"num_stories_unestimated": {
"description": "The total number of Stories with no point estimate.",
"type": "integer",
"format": "int64"
},
"num_stories_backlog": {
"description": "The total number of backlog Stories in this Iteration.",
"type": "integer",
"format": "int64"
},
"average_lead_time": {
"description": "The average lead time (in seconds) of completed stories in this Iteration.",
"type": "integer",
"format": "int64"
},
"num_points_backlog": {
"description": "The total number of backlog points in this Iteration.",
"type": "integer",
"format": "int64"
},
"num_points": {
"description": "The total number of points in this Iteration.",
"type": "integer",
"format": "int64"
},
"num_stories_done": {
"description": "The total number of done Stories in this Iteration.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"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"
]
},
"KeyResult": {
"type": "object",
"properties": {
"id": {
"description": "The ID of the Key Result.",
"type": "string",
"format": "uuid"
},
"name": {
"description": "The name of the Key Result.",
"type": "string"
},
"objective_id": {
"description": "The Objective to which this Key Result belongs.",
"type": "integer",
"format": "int64"
},
"type": {
"description": "The type of the Key Result (numeric, percent, or boolean).",
"type": "string",
"enum": [
"percent",
"boolean",
"numeric"
]
},
"initial_observed_value": {
"$ref": "#/components/schemas/KeyResultValue"
},
"current_observed_value": {
"$ref": "#/components/schemas/KeyResultValue"
},
"current_target_value": {
"$ref": "#/components/schemas/KeyResultValue"
},
"progress": {
"description": "The integer percentage of progress toward completion of the Key Result.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"id",
"name",
"objective_id",
"type",
"initial_observed_value",
"current_observed_value",
"current_target_value",
"progress"
]
},
"KeyResultValue": {
"description": "The starting value of the Key Result.",
"type": "object",
"properties": {
"numeric_value": {
"description": "The numeric value, as a decimal string. No more than two decimal places are allowed.",
"type": "string"
},
"boolean_value": {
"description": "The boolean value.",
"type": "boolean"
}
},
"additionalProperties": false
},
"Label": {
"description": "A Label can be used to associate and filter Stories and Epics, and also create new Workspaces.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Label.",
"type": "string"
},
"description": {
"description": "The description of the Label.",
"type": "string",
"nullable": true
},
"archived": {
"description": "A true/false boolean indicating if the Label has been archived.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"color": {
"description": "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"minLength": 1,
"type": "string",
"nullable": true
},
"name": {
"description": "The name of the Label.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"updated_at": {
"description": "The time/date that the Label was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"external_id": {
"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.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Label.",
"type": "integer",
"format": "int64"
},
"stats": {
"$ref": "#/components/schemas/LabelStats"
},
"created_at": {
"description": "The time/date that the Label was created.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"app_url",
"description",
"archived",
"entity_type",
"color",
"name",
"global_id",
"updated_at",
"external_id",
"id",
"created_at"
]
},
"LabelSlim": {
"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.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Label.",
"type": "string"
},
"description": {
"description": "The description of the Label.",
"type": "string",
"nullable": true
},
"archived": {
"description": "A true/false boolean indicating if the Label has been archived.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"color": {
"description": "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"minLength": 1,
"type": "string",
"nullable": true
},
"name": {
"description": "The name of the Label.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"updated_at": {
"description": "The time/date that the Label was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"external_id": {
"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.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Label.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date that the Label was created.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"app_url",
"description",
"archived",
"entity_type",
"color",
"name",
"global_id",
"updated_at",
"external_id",
"id",
"created_at"
]
},
"LabelStats": {
"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.",
"type": "object",
"properties": {
"num_related_documents": {
"description": "The total number of Documents associated this Label.",
"type": "integer",
"format": "int64"
},
"num_epics": {
"description": "The total number of Epics with this Label.",
"type": "integer",
"format": "int64"
},
"num_stories_unstarted": {
"description": "The total number of stories unstarted Stories with this Label.",
"type": "integer",
"format": "int64"
},
"num_stories_total": {
"description": "The total number of Stories with this Label.",
"type": "integer",
"format": "int64"
},
"num_epics_unstarted": {
"description": "The number of unstarted epics associated with this label.",
"type": "integer",
"format": "int64"
},
"num_epics_in_progress": {
"description": "The number of in progress epics associated with this label.",
"type": "integer",
"format": "int64"
},
"num_points_unstarted": {
"description": "The total number of unstarted points with this Label.",
"type": "integer",
"format": "int64"
},
"num_stories_unestimated": {
"description": "The total number of Stories with no point estimate with this Label.",
"type": "integer",
"format": "int64"
},
"num_points_in_progress": {
"description": "The total number of in-progress points with this Label.",
"type": "integer",
"format": "int64"
},
"num_epics_total": {
"description": "The total number of Epics associated with this Label.",
"type": "integer",
"format": "int64"
},
"num_stories_completed": {
"description": "The total number of completed Stories with this Label.",
"type": "integer",
"format": "int64"
},
"num_points_completed": {
"description": "The total number of completed points with this Label.",
"type": "integer",
"format": "int64"
},
"num_stories_backlog": {
"description": "The total number of stories backlog Stories with this Label.",
"type": "integer",
"format": "int64"
},
"num_points_total": {
"description": "The total number of points with this Label.",
"type": "integer",
"format": "int64"
},
"num_stories_in_progress": {
"description": "The total number of in-progress Stories with this Label.",
"type": "integer",
"format": "int64"
},
"num_points_backlog": {
"description": "The total number of backlog points with this Label.",
"type": "integer",
"format": "int64"
},
"num_epics_completed": {
"description": "The number of completed Epics associated with this Label.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"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"
]
},
"LinkSubTaskParams": {
"x-doc-skip": true,
"type": "object",
"properties": {
"story_id": {
"description": "The ID of the story to link as a sub-task of the parent story",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"story_id"
]
},
"LinkedFile": {
"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.",
"type": "object",
"properties": {
"description": {
"description": "The description of the file.",
"type": "string",
"nullable": true
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"story_ids": {
"description": "The IDs of the stories this file is attached to.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"member_mention_ids": {
"description": "The members that are mentioned in the description of the file.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"name": {
"description": "The name of the linked file.",
"type": "string"
},
"thumbnail_url": {
"description": "The URL of the file thumbnail, if the integration provided it.",
"type": "string",
"nullable": true
},
"type": {
"description": "The integration type (e.g. google, dropbox, box).",
"type": "string"
},
"size": {
"description": "The filesize, if the integration provided it.",
"type": "integer",
"format": "int64",
"nullable": true
},
"uploader_id": {
"description": "The UUID of the member that uploaded the file.",
"type": "string",
"format": "uuid"
},
"content_type": {
"description": "The content type of the image (e.g. txt/plain).",
"type": "string",
"nullable": true
},
"updated_at": {
"description": "The time/date the LinkedFile was updated.",
"type": "string",
"format": "date-time"
},
"group_mention_ids": {
"description": "The groups that are mentioned in the description of the file.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"id": {
"description": "The unique identifier for the file.",
"type": "integer",
"format": "int64"
},
"url": {
"description": "The URL of the file.",
"type": "string"
},
"created_at": {
"description": "The time/date the LinkedFile was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"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"
]
},
"MaxSearchResultsExceededError": {
"description": "Error returned when total maximum supported results have been reached.",
"type": "object",
"properties": {
"error": {
"description": "The name for this type of error, `maximum-results-exceeded`",
"type": "string",
"enum": [
"maximum-results-exceeded"
]
},
"message": {
"description": "An explanatory message: \"A maximum of 1000 search results are supported.\"",
"type": "string"
},
"maximum-results": {
"description": "The maximum number of search results supported, `1000`",
"type": "integer",
"format": "int64",
"enum": [
1000
]
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"maximum-results"
]
},
"Member": {
"description": "Details about an individual user within the Workspace.",
"type": "object",
"properties": {
"role": {
"description": "The Member's role in the Workspace.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"disabled": {
"description": "True/false boolean indicating whether the Member has been disabled within the Workspace.",
"type": "boolean"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"state": {
"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.",
"type": "string",
"enum": [
"partial",
"full",
"disabled",
"imported"
]
},
"updated_at": {
"description": "The time/date the Member was last updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"created_without_invite": {
"description": "Whether this member was created as a placeholder entity.",
"x-doc-skip": true,
"type": "boolean"
},
"group_ids": {
"description": "The Member's group ids",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"id": {
"description": "The Member's ID in Shortcut.",
"type": "string",
"format": "uuid"
},
"profile": {
"$ref": "#/components/schemas/Profile"
},
"created_at": {
"description": "The time/date the Member was created.",
"type": "string",
"format": "date-time",
"nullable": true
},
"replaced_by": {
"description": "The id of the member that replaces this one when merged.",
"x-doc-skip": true,
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"required": [
"role",
"entity_type",
"disabled",
"global_id",
"state",
"updated_at",
"created_without_invite",
"group_ids",
"id",
"profile",
"created_at"
]
},
"MemberInfo": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"is_owner": {
"type": "boolean"
},
"mention_name": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"workspace2": {
"$ref": "#/components/schemas/BasicWorkspaceInfo"
},
"organization2": {
"$ref": "#/components/schemas/MemberInfoOrganization2"
}
},
"additionalProperties": false,
"required": [
"id",
"is_owner",
"mention_name",
"name",
"role",
"workspace2",
"organization2"
]
},
"MemberInfoOrganization2": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"required": [
"id"
]
},
"Milestone": {
"description": "(Deprecated) A Milestone is a collection of Epics that represent a release or some other large initiative that you are working on. Milestones have become Objectives, so you should use Objective-related API resources instead of Milestone ones.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Milestone.",
"type": "string"
},
"description": {
"description": "The Milestone's description.",
"type": "string"
},
"archived": {
"description": "A boolean indicating whether the Milestone has been archived or not.",
"type": "boolean"
},
"started": {
"description": "A true/false boolean indicating if the Milestone has been started.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"completed_at_override": {
"description": "A manual override for the time/date the Milestone was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"started_at": {
"description": "The time/date the Milestone was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"description": "The time/date the Milestone was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"name": {
"description": "The name of the Milestone.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"completed": {
"description": "A true/false boolean indicating if the Milestone has been completed.",
"type": "boolean"
},
"state": {
"description": "The workflow state that the Milestone is in.",
"type": "string"
},
"started_at_override": {
"description": "A manual override for the time/date the Milestone was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"description": "The time/date the Milestone was updated.",
"type": "string",
"format": "date-time"
},
"categories": {
"description": "An array of Categories attached to the Milestone.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
},
"id": {
"description": "The unique ID of the Milestone.",
"type": "integer",
"format": "int64"
},
"key_result_ids": {
"description": "The IDs of the Key Results associated with the Objective.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"position": {
"description": "A number representing the position of the Milestone in relation to every other Milestone within the Workspace.",
"type": "integer",
"format": "int64"
},
"stats": {
"$ref": "#/components/schemas/MilestoneStats"
},
"created_at": {
"description": "The time/date the Milestone was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"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"
]
},
"MilestoneStats": {
"description": "A group of calculated values for this Milestone.",
"type": "object",
"properties": {
"average_cycle_time": {
"description": "The average cycle time (in seconds) of completed stories in this Milestone.",
"type": "integer",
"format": "int64"
},
"average_lead_time": {
"description": "The average lead time (in seconds) of completed stories in this Milestone.",
"type": "integer",
"format": "int64"
},
"num_related_documents": {
"description": "The number of related documents to this Milestone.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"num_related_documents"
]
},
"Objective": {
"description": "An Objective is a collection of Epics that represent a release or some other large initiative that you are working on.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Objective.",
"type": "string"
},
"description": {
"description": "The Objective's description.",
"type": "string"
},
"archived": {
"description": "A boolean indicating whether the Objective has been archived or not.",
"type": "boolean"
},
"started": {
"description": "A true/false boolean indicating if the Objective has been started.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"completed_at_override": {
"description": "A manual override for the time/date the Objective was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"started_at": {
"description": "The time/date the Objective was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"description": "The time/date the Objective was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"name": {
"description": "The name of the Objective.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"completed": {
"description": "A true/false boolean indicating if the Objectivehas been completed.",
"type": "boolean"
},
"state": {
"description": "The workflow state that the Objective is in.",
"type": "string"
},
"started_at_override": {
"description": "A manual override for the time/date the Objective was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"description": "The time/date the Objective was updated.",
"type": "string",
"format": "date-time"
},
"categories": {
"description": "An array of Categories attached to the Objective.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
},
"id": {
"description": "The unique ID of the Objective.",
"type": "integer",
"format": "int64"
},
"key_result_ids": {
"description": "The IDs of the Key Results associated with the Objective.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"position": {
"description": "A number representing the position of the Objective in relation to every other Objective within the Workspace.",
"type": "integer",
"format": "int64"
},
"stats": {
"$ref": "#/components/schemas/ObjectiveStats"
},
"created_at": {
"description": "The time/date the Objective was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"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"
]
},
"ObjectiveSearchResult": {
"description": "A Milestone in search results. This is typed differently from Milestone because the details=slim search argument will omit some fields.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Milestone.",
"type": "string"
},
"description": {
"description": "The Milestone's description.",
"type": "string"
},
"archived": {
"description": "A boolean indicating whether the Milestone has been archived or not.",
"type": "boolean"
},
"started": {
"description": "A true/false boolean indicating if the Milestone has been started.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"completed_at_override": {
"description": "A manual override for the time/date the Milestone was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"started_at": {
"description": "The time/date the Milestone was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"description": "The time/date the Milestone was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"name": {
"description": "The name of the Milestone.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"completed": {
"description": "A true/false boolean indicating if the Milestone has been completed.",
"type": "boolean"
},
"state": {
"description": "The workflow state that the Milestone is in.",
"type": "string"
},
"started_at_override": {
"description": "A manual override for the time/date the Milestone was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"description": "The time/date the Milestone was updated.",
"type": "string",
"format": "date-time"
},
"categories": {
"description": "An array of Categories attached to the Milestone.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
},
"id": {
"description": "The unique ID of the Milestone.",
"type": "integer",
"format": "int64"
},
"key_result_ids": {
"description": "The IDs of the Key Results associated with the Objective.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"position": {
"description": "A number representing the position of the Milestone in relation to every other Milestone within the Workspace.",
"type": "integer",
"format": "int64"
},
"stats": {
"$ref": "#/components/schemas/MilestoneStats"
},
"created_at": {
"description": "The time/date the Milestone was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"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"
]
},
"ObjectiveSearchResults": {
"description": "The results of the Objective search query.",
"type": "object",
"properties": {
"total": {
"description": "The total number of matches for the search query. The first 1000 matches can be paged through via the API.",
"type": "integer",
"format": "int64"
},
"data": {
"description": "A list of search results.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ObjectiveSearchResult"
}
},
"next": {
"description": "The URL path and query string for the next page of search results.",
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"total",
"data",
"next"
]
},
"ObjectiveStats": {
"description": "A group of calculated values for this Objective.",
"type": "object",
"properties": {
"average_cycle_time": {
"description": "The average cycle time (in seconds) of completed stories in this Objective.",
"type": "integer",
"format": "int64"
},
"average_lead_time": {
"description": "The average lead time (in seconds) of completed stories in this Objective.",
"type": "integer",
"format": "int64"
},
"num_related_documents": {
"description": "The number of related documents to this Objective.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"num_related_documents"
]
},
"Profile": {
"description": "A group of Member profile details.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"deactivated": {
"description": "A true/false boolean indicating whether the Member has been deactivated within Shortcut.",
"type": "boolean"
},
"two_factor_auth_activated": {
"description": "If Two Factor Authentication is activated for this User.",
"type": "boolean"
},
"mention_name": {
"description": "The Member's username within the Organization.",
"type": "string"
},
"name": {
"description": "The Member's name within the Organization.",
"type": "string",
"nullable": true
},
"is_agent": {
"description": "Whether this profile is an Agent/Bot user.",
"x-doc-skip": true,
"type": "boolean"
},
"gravatar_hash": {
"description": "This is the gravatar hash associated with email_address.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique identifier of the profile.",
"type": "string",
"format": "uuid"
},
"display_icon": {
"$ref": "#/components/schemas/Icon"
},
"is_owner": {
"description": "A boolean indicating whether this profile is an owner at their associated organization.",
"type": "boolean"
},
"email_address": {
"description": "The primary email address of the Member with the Organization.",
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"entity_type",
"deactivated",
"mention_name",
"name",
"gravatar_hash",
"id",
"display_icon",
"is_owner",
"email_address"
]
},
"Project": {
"description": "Projects typically map to teams (such as Frontend, Backend, Mobile, Devops, etc) but can represent any open-ended product, component, or initiative.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Project.",
"type": "string"
},
"description": {
"description": "The description of the Project.",
"type": "string",
"nullable": true
},
"archived": {
"description": "True/false boolean indicating whether the Project is in an Archived state.",
"type": "boolean"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"days_to_thermometer": {
"description": "The number of days before the thermometer appears in the Story summary.",
"type": "integer",
"format": "int64"
},
"color": {
"description": "The color associated with the Project in the Shortcut member interface.",
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"minLength": 1,
"type": "string",
"nullable": true
},
"workflow_id": {
"description": "The ID of the workflow the project belongs to.",
"type": "integer",
"format": "int64"
},
"name": {
"description": "The name of the Project",
"type": "string"
},
"global_id": {
"description": "The Global ID of the Project.",
"x-doc-skip": true,
"type": "string"
},
"start_time": {
"description": "The date at which the Project was started.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "The time/date that the Project was last updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"follower_ids": {
"description": "An array of UUIDs for any Members listed as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"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.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Project.",
"type": "integer",
"format": "int64"
},
"show_thermometer": {
"description": "Configuration to enable or disable thermometers in the Story summary.",
"type": "boolean"
},
"team_id": {
"description": "The ID of the team the project belongs to.",
"type": "integer",
"format": "int64"
},
"iteration_length": {
"description": "The number of weeks per iteration in this Project.",
"type": "integer",
"format": "int64"
},
"abbreviation": {
"description": "The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.",
"type": "string",
"nullable": true
},
"stats": {
"$ref": "#/components/schemas/ProjectStats"
},
"created_at": {
"description": "The time/date that the Project was created.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"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"
]
},
"ProjectStats": {
"description": "A group of calculated values for this Project.",
"type": "object",
"properties": {
"num_stories": {
"description": "The total number of stories in this Project.",
"type": "integer",
"format": "int64"
},
"num_points": {
"description": "The total number of points in this Project.",
"type": "integer",
"format": "int64"
},
"num_related_documents": {
"description": "The total number of documents related to this Project",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"num_stories",
"num_points",
"num_related_documents"
]
},
"PullRequest": {
"description": "Corresponds to a VCS Pull Request attached to a Shortcut story.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"closed": {
"description": "True/False boolean indicating whether the VCS pull request has been closed.",
"type": "boolean"
},
"merged": {
"description": "True/False boolean indicating whether the VCS pull request has been merged.",
"type": "boolean"
},
"num_added": {
"description": "Number of lines added in the pull request, according to VCS.",
"type": "integer",
"format": "int64"
},
"branch_id": {
"description": "The ID of the branch for the particular pull request.",
"type": "integer",
"format": "int64"
},
"overlapping_stories": {
"description": "An array of Story ids that have Pull Requests that change at least one of the same lines this Pull Request changes.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"number": {
"description": "The pull request's unique number ID in VCS.",
"type": "integer",
"format": "int64"
},
"branch_name": {
"description": "The name of the branch for the particular pull request.",
"type": "string"
},
"target_branch_name": {
"description": "The name of the target branch for the particular pull request.",
"type": "string"
},
"num_commits": {
"description": "The number of commits on the pull request.",
"type": "integer",
"format": "int64",
"nullable": true
},
"title": {
"description": "The title of the pull request.",
"type": "string"
},
"updated_at": {
"description": "The time/date the pull request was created.",
"type": "string",
"format": "date-time"
},
"has_overlapping_stories": {
"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.",
"type": "boolean"
},
"draft": {
"description": "True/False boolean indicating whether the VCS pull request is in the draft state.",
"type": "boolean"
},
"id": {
"description": "The unique ID associated with the pull request in Shortcut.",
"type": "integer",
"format": "int64"
},
"vcs_labels": {
"description": "An array of PullRequestLabels attached to the PullRequest.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PullRequestLabel"
},
"nullable": true
},
"url": {
"description": "The URL for the pull request.",
"type": "string"
},
"num_removed": {
"description": "Number of lines removed in the pull request, according to VCS.",
"type": "integer",
"format": "int64"
},
"review_status": {
"description": "The status of the review for the pull request.",
"type": "string"
},
"num_modified": {
"description": "Number of lines modified in the pull request, according to VCS.",
"type": "integer",
"format": "int64",
"nullable": true
},
"build_status": {
"description": "The status of the Continuous Integration workflow for the pull request.",
"type": "string"
},
"target_branch_id": {
"description": "The ID of the target branch for the particular pull request.",
"type": "integer",
"format": "int64"
},
"repository_id": {
"description": "The ID of the repository for the particular pull request.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date the pull request was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"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"
]
},
"PullRequestLabel": {
"description": "Corresponds to a VCS Label associated with a Pull Request.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"id": {
"description": "The unique ID of the VCS Label.",
"type": "integer",
"format": "int64"
},
"color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"description": "The color of the VCS label.",
"minLength": 1,
"type": "string"
},
"description": {
"description": "The description of the VCS label.",
"type": "string",
"nullable": true
},
"name": {
"description": "The name of the VCS label.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"entity_type",
"id",
"color",
"name"
]
},
"RemoveCustomFieldParams": {
"type": "object",
"properties": {
"field_id": {
"description": "The unique public ID for the CustomField.",
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"required": [
"field_id"
]
},
"RemoveLabelParams": {
"description": "Request parameters for removing a Label from a Shortcut Story.",
"type": "object",
"properties": {
"name": {
"maxLength": 128,
"minLength": 1,
"description": "The name of the new Label to remove.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name"
]
},
"Repository": {
"description": "Repository refers to a VCS repository.",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"name": {
"description": "The shorthand name of the VCS repository.",
"type": "string",
"nullable": true
},
"type": {
"description": "The VCS provider for the Repository.",
"type": "string",
"enum": [
"github",
"gitlab",
"bitbucket"
]
},
"updated_at": {
"description": "The time/date the Repository was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"external_id": {
"description": "The VCS unique identifier for the Repository.",
"type": "string",
"nullable": true
},
"id": {
"description": "The ID associated to the VCS repository in Shortcut.",
"type": "integer",
"format": "int64",
"nullable": true
},
"url": {
"description": "The URL of the Repository.",
"type": "string",
"nullable": true
},
"full_name": {
"description": "The full name of the VCS repository.",
"type": "string",
"nullable": true
},
"created_at": {
"description": "The time/date the Repository was created.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"entity_type",
"name",
"type",
"updated_at",
"external_id",
"id",
"url",
"full_name",
"created_at"
]
},
"SearchResults": {
"description": "The results of the multi-entity search query.",
"type": "object",
"properties": {
"epics": {
"$ref": "#/components/schemas/EpicSearchResults"
},
"stories": {
"$ref": "#/components/schemas/StorySearchResults"
},
"iterations": {
"$ref": "#/components/schemas/IterationSearchResults"
},
"milestones": {
"$ref": "#/components/schemas/ObjectiveSearchResults"
}
},
"additionalProperties": false
},
"SearchStories": {
"x-doc-skip": true,
"type": "object",
"properties": {
"archived": {
"description": "A true/false boolean indicating whether the Story is in archived state.",
"type": "boolean"
},
"owner_id": {
"description": "An array of UUIDs for any Users who may be Owners of the Stories.",
"type": "string",
"format": "uuid",
"nullable": true
},
"story_type": {
"description": "The type of Stories that you want returned.",
"type": "string",
"enum": [
"feature",
"chore",
"bug"
]
},
"epic_ids": {
"description": "The Epic IDs that may be associated with the Stories.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"project_ids": {
"description": "The IDs for the Projects the Stories may be assigned to.",
"type": "array",
"items": {
"type": "integer",
"format": "int64",
"nullable": true
},
"uniqueItems": true
},
"updated_at_end": {
"description": "Stories should have been updated on or before this date.",
"type": "string",
"format": "date-time"
},
"completed_at_end": {
"description": "Stories should have been completed on or before this date.",
"type": "string",
"format": "date-time"
},
"workflow_state_types": {
"description": "The type of Workflow State the Stories may be in.",
"type": "array",
"items": {
"type": "string",
"enum": [
"started",
"backlog",
"unstarted",
"done"
]
}
},
"deadline_end": {
"description": "Stories should have a deadline on or before this date.",
"type": "string",
"format": "date-time"
},
"created_at_start": {
"description": "Stories should have been created on or after this date.",
"type": "string",
"format": "date-time"
},
"epic_id": {
"description": "The Epic IDs that may be associated with the Stories.",
"type": "integer",
"format": "int64",
"nullable": true
},
"label_name": {
"minLength": 1,
"description": "The name of any associated Labels.",
"type": "string"
},
"requested_by_id": {
"description": "The UUID of any Users who may have requested the Stories.",
"type": "string",
"format": "uuid"
},
"iteration_id": {
"description": "The Iteration ID that may be associated with the Stories.",
"type": "integer",
"format": "int64",
"nullable": true
},
"label_ids": {
"description": "The Label IDs that may be associated with the Stories.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"group_id": {
"description": "The Group ID that is associated with the Stories",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The unique IDs of the specific Workflow States that the Stories should be in.",
"type": "integer",
"format": "int64"
},
"iteration_ids": {
"description": "The Iteration IDs that may be associated with the Stories.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"created_at_end": {
"description": "Stories should have been created on or before this date.",
"type": "string",
"format": "date-time"
},
"deadline_start": {
"description": "Stories should have a deadline on or after this date.",
"type": "string",
"format": "date-time"
},
"group_ids": {
"description": "The Group IDs that are associated with the Stories",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"owner_ids": {
"description": "An array of UUIDs for any Users who may be Owners of the Stories.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"external_id": {
"maxLength": 1024,
"description": "An ID or URL that references an external resource. Useful during imports.",
"type": "string"
},
"includes_description": {
"description": "Whether to include the story description in the response.",
"type": "boolean"
},
"estimate": {
"description": "The number of estimate points associate with the Stories.",
"type": "integer",
"format": "int64"
},
"project_id": {
"description": "The IDs for the Projects the Stories may be assigned to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"completed_at_start": {
"description": "Stories should have been completed on or after this date.",
"type": "string",
"format": "date-time"
},
"updated_at_start": {
"description": "Stories should have been updated on or after this date.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"Story": {
"description": "Stories are the standard unit of work in Shortcut and represent individual features, bugs, and chores.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Story.",
"type": "string"
},
"description": {
"description": "The description of the story.",
"type": "string"
},
"archived": {
"description": "True if the story has been archived or not.",
"type": "boolean"
},
"started": {
"description": "A true/false boolean indicating if the Story has been started.",
"type": "boolean"
},
"story_links": {
"description": "An array of story links attached to the Story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TypedStoryLink"
}
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"labels": {
"description": "An array of labels attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LabelSlim"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"synced_item": {
"$ref": "#/components/schemas/SyncedItem"
},
"member_mention_ids": {
"description": "An array of Member IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string"
},
"custom_fields": {
"description": "An array of CustomField value assertions for the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryCustomField"
}
},
"linked_files": {
"description": "An array of linked files attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LinkedFile"
}
},
"workflow_id": {
"description": "The ID of the workflow the story belongs to.",
"type": "integer",
"format": "int64"
},
"completed_at_override": {
"description": "A manual override for the time/date the Story was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"started_at": {
"description": "The time/date the Story was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"description": "The time/date the Story was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"name": {
"description": "The name of the story.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"completed": {
"description": "A true/false boolean indicating if the Story has been completed.",
"type": "boolean"
},
"comments": {
"description": "An array of comments attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryComment"
}
},
"blocker": {
"description": "A true/false boolean indicating if the Story is currently a blocker of another story.",
"type": "boolean"
},
"branches": {
"description": "An array of Git branches attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Branch"
}
},
"epic_id": {
"description": "The ID of the epic the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"story_template_id": {
"description": "The ID of the story template used to create this story, or null if not created using a template.",
"type": "string",
"format": "uuid",
"nullable": true
},
"external_links": {
"description": "An array of external links (strings) associated with a Story",
"type": "array",
"items": {
"type": "string"
}
},
"previous_iteration_ids": {
"description": "The IDs of the iteration the story belongs to.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"requested_by_id": {
"description": "The ID of the Member that requested the story.",
"type": "string",
"format": "uuid"
},
"iteration_id": {
"description": "The ID of the iteration the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"sub_task_story_ids": {
"x-doc-skip": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"tasks": {
"description": "An array of tasks connected to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"formatted_vcs_branch_name": {
"description": "The formatted branch name for this story.",
"x-doc-skip": true,
"type": "string",
"nullable": true
},
"label_ids": {
"description": "An array of label ids attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"started_at_override": {
"description": "A manual override for the time/date the Story was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_id": {
"description": "The ID of the group associated with the story.",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The ID of the workflow state the story is currently in.",
"type": "integer",
"format": "int64"
},
"updated_at": {
"description": "The time/date the Story was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"pull_requests": {
"description": "An array of Pull/Merge Requests attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PullRequest"
}
},
"group_mention_ids": {
"description": "An array of Group IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"follower_ids": {
"description": "An array of UUIDs for any Members listed as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"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.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Story.",
"type": "integer",
"format": "int64"
},
"lead_time": {
"description": "The lead time (in seconds) of this story when complete.",
"type": "integer",
"format": "int64"
},
"parent_story_id": {
"x-doc-skip": true,
"type": "integer",
"format": "int64",
"nullable": true
},
"estimate": {
"description": "The numeric point estimate of the story. Can also be null, which means unestimated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"commits": {
"description": "An array of commits attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Commit"
}
},
"files": {
"description": "An array of files attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadedFile"
}
},
"position": {
"description": "A number representing the position of the story in relation to every other story in the current project.",
"type": "integer",
"format": "int64"
},
"blocked": {
"description": "A true/false boolean indicating if the Story is currently blocked.",
"type": "boolean"
},
"project_id": {
"description": "The ID of the project the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time",
"nullable": true
},
"stats": {
"$ref": "#/components/schemas/StoryStats"
},
"cycle_time": {
"description": "The cycle time (in seconds) of this story when complete.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date the Story was created.",
"type": "string",
"format": "date-time"
},
"moved_at": {
"description": "The time/date the Story was last changed workflow-state.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"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"
]
},
"StoryComment": {
"description": "A Comment is any note added within the Comment field of a Story.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Comment.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"deleted": {
"description": "True/false boolean indicating whether the Comment has been deleted.",
"type": "boolean"
},
"story_id": {
"description": "The ID of the Story on which the Comment appears.",
"type": "integer",
"format": "int64"
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"author_id": {
"description": "The unique ID of the Member who is the Comment's author.",
"type": "string",
"format": "uuid",
"nullable": true
},
"member_mention_ids": {
"description": "The unique IDs of the Member who are mentioned in the Comment.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"blocker": {
"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.",
"type": "boolean"
},
"linked_to_slack": {
"description": "Whether the Comment is currently the root of a thread that is linked to Slack.",
"type": "boolean"
},
"updated_at": {
"description": "The time/date when the Comment was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_mention_ids": {
"description": "The unique IDs of the Group who are mentioned in the Comment.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"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.",
"type": "string",
"nullable": true
},
"parent_id": {
"description": "The ID of the parent Comment this Comment is threaded under.",
"type": "integer",
"format": "int64",
"nullable": true
},
"id": {
"description": "The unique ID of the Comment.",
"type": "integer",
"format": "int64"
},
"position": {
"description": "The Comments numerical position in the list from oldest to newest.",
"type": "integer",
"format": "int64"
},
"unblocks_parent": {
"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.",
"type": "boolean"
},
"reactions": {
"description": "A set of Reactions to this Comment.",
"x-doc-skip": true,
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryReaction"
}
},
"created_at": {
"description": "The time/date when the Comment was created.",
"type": "string",
"format": "date-time"
},
"text": {
"description": "The text of the Comment. In the case that the Comment has been deleted, this field can be set to nil.",
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"app_url",
"entity_type",
"deleted",
"story_id",
"mention_ids",
"author_id",
"member_mention_ids",
"linked_to_slack",
"updated_at",
"group_mention_ids",
"external_id",
"id",
"position",
"reactions",
"created_at",
"text"
]
},
"StoryContents": {
"description": "A container entity for the attributes this template should populate.",
"type": "object",
"properties": {
"description": {
"description": "The description of the story.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"labels": {
"description": "An array of labels attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LabelSlim"
}
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string"
},
"custom_fields": {
"description": "An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldValueParams"
}
},
"linked_files": {
"description": "An array of linked files attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LinkedFile"
}
},
"name": {
"description": "The name of the story.",
"type": "string"
},
"epic_id": {
"description": "The ID of the epic the story belongs to.",
"type": "integer",
"format": "int64"
},
"external_links": {
"description": "An array of external links connected to the story.",
"type": "array",
"items": {
"type": "string"
}
},
"sub_tasks": {
"description": "An array of sub-tasks connected to the story",
"x-doc-skip": true,
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateSubTaskParams"
}
},
"iteration_id": {
"description": "The ID of the iteration the story belongs to.",
"type": "integer",
"format": "int64"
},
"tasks": {
"description": "An array of tasks connected to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryContentsTask"
}
},
"label_ids": {
"description": "An array of label ids attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"group_id": {
"description": "The ID of the group to which the story is assigned.",
"type": "string",
"format": "uuid"
},
"workflow_state_id": {
"description": "The ID of the workflow state the story is currently in.",
"type": "integer",
"format": "int64"
},
"follower_ids": {
"description": "An array of UUIDs for any Members listed as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"estimate": {
"description": "The numeric point estimate of the story. Can also be null, which means unestimated.",
"type": "integer",
"format": "int64"
},
"files": {
"description": "An array of files attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadedFile"
}
},
"project_id": {
"description": "The ID of the project the story belongs to.",
"type": "integer",
"format": "int64"
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"StoryContentsTask": {
"type": "object",
"properties": {
"description": {
"description": "Full text of the Task.",
"type": "string"
},
"position": {
"description": "The number corresponding to the Task's position within a list of Tasks on a Story.",
"type": "integer",
"format": "int64"
},
"complete": {
"description": "True/false boolean indicating whether the Task has been completed.",
"type": "boolean"
},
"owner_ids": {
"description": "An array of UUIDs of the Owners of this Task.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"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.",
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"description"
]
},
"StoryCustomField": {
"type": "object",
"properties": {
"field_id": {
"description": "The unique public ID for a CustomField.",
"type": "string",
"format": "uuid"
},
"value_id": {
"description": "The unique public ID for a CustomFieldEnumValue.",
"type": "string",
"format": "uuid"
},
"value": {
"description": "A string representation of the value, if applicable.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"field_id",
"value_id",
"value"
]
},
"StoryHistoryChangeAddsRemovesInt": {
"description": "Task IDs that have been added or removed from the Story.",
"type": "object",
"properties": {
"adds": {
"description": "The values that have been added.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"removes": {
"description": "The values that have been removed",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"additionalProperties": false
},
"StoryHistoryChangeAddsRemovesUuid": {
"description": "Custom Field Enum Value IDs that have been added or removed from the Story.",
"type": "object",
"properties": {
"adds": {
"description": "The values that have been added.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"removes": {
"description": "The values that have been removed",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"additionalProperties": false
},
"StoryHistoryChangeOldNewBool": {
"description": "True if the Story has archived, otherwise false.",
"type": "object",
"properties": {
"old": {
"description": "The old value.",
"type": "boolean"
},
"new": {
"description": "The new value.",
"type": "boolean"
}
},
"additionalProperties": false
},
"StoryHistoryChangeOldNewInt": {
"description": "The estimate value for the Story",
"type": "object",
"properties": {
"old": {
"description": "The old value.",
"type": "integer",
"format": "int64"
},
"new": {
"description": "The new value.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false
},
"StoryHistoryChangeOldNewStr": {
"description": "A timestamp that represents the Story's deadline.",
"type": "object",
"properties": {
"old": {
"description": "The old value.",
"type": "string",
"nullable": true
},
"new": {
"description": "The new value.",
"type": "string"
}
},
"additionalProperties": false
},
"StoryHistoryChangeOldNewUuid": {
"description": "The Team ID for the Story.",
"type": "object",
"properties": {
"old": {
"description": "The old value.",
"type": "string",
"format": "uuid"
},
"new": {
"description": "The new value.",
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
"StoryLink": {
"description": "Story links allow you create semantic relationships between two stories. Relationship types are relates to, blocks / blocked by, and duplicates / is duplicated by. The format is `subject -> link -> object`, or for example \"story 5 blocks story 6\".",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"id": {
"description": "The unique identifier of the Story Link.",
"type": "integer",
"format": "int64"
},
"subject_id": {
"description": "The ID of the subject Story.",
"type": "integer",
"format": "int64"
},
"subject_workflow_state_id": {
"description": "The workflow state of the \"subject\" story.",
"x-doc-skip": true,
"type": "integer",
"format": "int64"
},
"verb": {
"description": "How the subject Story acts on the object Story. This can be \"blocks\", \"duplicates\", or \"relates to\".",
"type": "string"
},
"object_id": {
"description": "The ID of the object Story.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date when the Story Link was created.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "The time/date when the Story Link was last updated.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"entity_type",
"id",
"subject_id",
"subject_workflow_state_id",
"verb",
"object_id",
"created_at",
"updated_at"
]
},
"StoryReaction": {
"description": "Emoji reaction on a comment.",
"type": "object",
"properties": {
"emoji": {
"description": "Emoji text of the reaction.",
"type": "string"
},
"permission_ids": {
"description": "Permissions who have reacted with this.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"additionalProperties": false,
"required": [
"emoji",
"permission_ids"
]
},
"StorySearchResult": {
"description": "A Story in search results. This is typed differently from Story because the details=slim search argument will omit some fields.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Story.",
"type": "string"
},
"description": {
"description": "The description of the story.",
"type": "string"
},
"archived": {
"description": "True if the story has been archived or not.",
"type": "boolean"
},
"started": {
"description": "A true/false boolean indicating if the Story has been started.",
"type": "boolean"
},
"story_links": {
"description": "An array of story links attached to the Story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TypedStoryLink"
}
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"labels": {
"description": "An array of labels attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LabelSlim"
}
},
"task_ids": {
"description": "An array of IDs of Tasks attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"synced_item": {
"$ref": "#/components/schemas/SyncedItem"
},
"member_mention_ids": {
"description": "An array of Member IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string"
},
"custom_fields": {
"description": "An array of CustomField value assertions for the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryCustomField"
}
},
"linked_files": {
"description": "An array of linked files attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LinkedFile"
}
},
"file_ids": {
"description": "An array of IDs of Files attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"num_tasks_completed": {
"description": "The number of tasks on the story which are complete.",
"type": "integer",
"format": "int64"
},
"workflow_id": {
"description": "The ID of the workflow the story belongs to.",
"type": "integer",
"format": "int64"
},
"completed_at_override": {
"description": "A manual override for the time/date the Story was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"started_at": {
"description": "The time/date the Story was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"description": "The time/date the Story was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"name": {
"description": "The name of the story.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"completed": {
"description": "A true/false boolean indicating if the Story has been completed.",
"type": "boolean"
},
"comments": {
"description": "An array of comments attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryComment"
}
},
"blocker": {
"description": "A true/false boolean indicating if the Story is currently a blocker of another story.",
"type": "boolean"
},
"branches": {
"description": "An array of Git branches attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Branch"
}
},
"epic_id": {
"description": "The ID of the epic the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"story_template_id": {
"description": "The ID of the story template used to create this story, or null if not created using a template.",
"type": "string",
"format": "uuid",
"nullable": true
},
"external_links": {
"description": "An array of external links (strings) associated with a Story",
"type": "array",
"items": {
"type": "string"
}
},
"previous_iteration_ids": {
"description": "The IDs of the iteration the story belongs to.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"requested_by_id": {
"description": "The ID of the Member that requested the story.",
"type": "string",
"format": "uuid"
},
"iteration_id": {
"description": "The ID of the iteration the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"sub_task_story_ids": {
"x-doc-skip": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"tasks": {
"description": "An array of tasks connected to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Task"
}
},
"formatted_vcs_branch_name": {
"description": "The formatted branch name for this story.",
"x-doc-skip": true,
"type": "string",
"nullable": true
},
"label_ids": {
"description": "An array of label ids attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"started_at_override": {
"description": "A manual override for the time/date the Story was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_id": {
"description": "The ID of the group associated with the story.",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The ID of the workflow state the story is currently in.",
"type": "integer",
"format": "int64"
},
"updated_at": {
"description": "The time/date the Story was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"pull_requests": {
"description": "An array of Pull/Merge Requests attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PullRequest"
}
},
"group_mention_ids": {
"description": "An array of Group IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"follower_ids": {
"description": "An array of UUIDs for any Members listed as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"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.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Story.",
"type": "integer",
"format": "int64"
},
"lead_time": {
"description": "The lead time (in seconds) of this story when complete.",
"type": "integer",
"format": "int64"
},
"parent_story_id": {
"x-doc-skip": true,
"type": "integer",
"format": "int64",
"nullable": true
},
"estimate": {
"description": "The numeric point estimate of the story. Can also be null, which means unestimated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"commits": {
"description": "An array of commits attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Commit"
}
},
"files": {
"description": "An array of files attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/UploadedFile"
}
},
"position": {
"description": "A number representing the position of the story in relation to every other story in the current project.",
"type": "integer",
"format": "int64"
},
"blocked": {
"description": "A true/false boolean indicating if the Story is currently blocked.",
"type": "boolean"
},
"project_id": {
"description": "The ID of the project the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"linked_file_ids": {
"description": "An array of IDs of LinkedFiles attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time",
"nullable": true
},
"stats": {
"$ref": "#/components/schemas/StoryStats"
},
"comment_ids": {
"description": "An array of IDs of Comments attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"cycle_time": {
"description": "The cycle time (in seconds) of this story when complete.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date the Story was created.",
"type": "string",
"format": "date-time"
},
"moved_at": {
"description": "The time/date the Story was last changed workflow-state.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"app_url",
"archived",
"started",
"story_links",
"entity_type",
"labels",
"mention_ids",
"member_mention_ids",
"story_type",
"workflow_id",
"completed_at_override",
"started_at",
"completed_at",
"name",
"global_id",
"completed",
"blocker",
"epic_id",
"story_template_id",
"external_links",
"previous_iteration_ids",
"requested_by_id",
"iteration_id",
"label_ids",
"started_at_override",
"group_id",
"workflow_state_id",
"updated_at",
"group_mention_ids",
"follower_ids",
"owner_ids",
"external_id",
"id",
"estimate",
"position",
"blocked",
"project_id",
"deadline",
"stats",
"created_at",
"moved_at"
]
},
"StorySearchResults": {
"description": "The results of the Story search query.",
"type": "object",
"properties": {
"total": {
"description": "The total number of matches for the search query. The first 1000 matches can be paged through via the API.",
"type": "integer",
"format": "int64"
},
"data": {
"description": "A list of search results.",
"type": "array",
"items": {
"$ref": "#/components/schemas/StorySearchResult"
}
},
"next": {
"description": "The URL path and query string for the next page of search results.",
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"total",
"data",
"next"
]
},
"StorySlim": {
"description": "StorySlim represents the same resource as a Story, but is more light-weight. For certain fields it provides ids rather than full resources (e.g., `comment_ids` and `file_ids`) and it also excludes certain aggregate values (e.g., `cycle_time`). The `description` field can be optionally included. Use the [Get Story](#Get-Story) endpoint to fetch the unabridged payload for a Story.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Story.",
"type": "string"
},
"description": {
"description": "The description of the Story.",
"type": "string"
},
"archived": {
"description": "True if the story has been archived or not.",
"type": "boolean"
},
"started": {
"description": "A true/false boolean indicating if the Story has been started.",
"type": "boolean"
},
"story_links": {
"description": "An array of story links attached to the Story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TypedStoryLink"
}
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"labels": {
"description": "An array of labels attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LabelSlim"
}
},
"task_ids": {
"description": "An array of IDs of Tasks attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"synced_item": {
"$ref": "#/components/schemas/SyncedItem"
},
"member_mention_ids": {
"description": "An array of Member IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string"
},
"custom_fields": {
"description": "An array of CustomField value assertions for the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/StoryCustomField"
}
},
"file_ids": {
"description": "An array of IDs of Files attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"num_tasks_completed": {
"description": "The number of tasks on the story which are complete.",
"type": "integer",
"format": "int64"
},
"workflow_id": {
"description": "The ID of the workflow the story belongs to.",
"type": "integer",
"format": "int64"
},
"completed_at_override": {
"description": "A manual override for the time/date the Story was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"started_at": {
"description": "The time/date the Story was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"description": "The time/date the Story was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"name": {
"description": "The name of the story.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"completed": {
"description": "A true/false boolean indicating if the Story has been completed.",
"type": "boolean"
},
"blocker": {
"description": "A true/false boolean indicating if the Story is currently a blocker of another story.",
"type": "boolean"
},
"epic_id": {
"description": "The ID of the epic the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"story_template_id": {
"description": "The ID of the story template used to create this story, or null if not created using a template.",
"type": "string",
"format": "uuid",
"nullable": true
},
"external_links": {
"description": "An array of external links (strings) associated with a Story",
"type": "array",
"items": {
"type": "string"
}
},
"previous_iteration_ids": {
"description": "The IDs of the iteration the story belongs to.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"requested_by_id": {
"description": "The ID of the Member that requested the story.",
"type": "string",
"format": "uuid"
},
"iteration_id": {
"description": "The ID of the iteration the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"sub_task_story_ids": {
"x-doc-skip": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"formatted_vcs_branch_name": {
"description": "The formatted branch name for this story.",
"x-doc-skip": true,
"type": "string",
"nullable": true
},
"label_ids": {
"description": "An array of label ids attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"started_at_override": {
"description": "A manual override for the time/date the Story was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_id": {
"description": "The ID of the group associated with the story.",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The ID of the workflow state the story is currently in.",
"type": "integer",
"format": "int64"
},
"updated_at": {
"description": "The time/date the Story was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_mention_ids": {
"description": "An array of Group IDs that have been mentioned in the Story description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"follower_ids": {
"description": "An array of UUIDs for any Members listed as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"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.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Story.",
"type": "integer",
"format": "int64"
},
"lead_time": {
"description": "The lead time (in seconds) of this story when complete.",
"type": "integer",
"format": "int64"
},
"parent_story_id": {
"x-doc-skip": true,
"type": "integer",
"format": "int64",
"nullable": true
},
"estimate": {
"description": "The numeric point estimate of the story. Can also be null, which means unestimated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"position": {
"description": "A number representing the position of the story in relation to every other story in the current project.",
"type": "integer",
"format": "int64"
},
"blocked": {
"description": "A true/false boolean indicating if the Story is currently blocked.",
"type": "boolean"
},
"project_id": {
"description": "The ID of the project the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"linked_file_ids": {
"description": "An array of IDs of LinkedFiles attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time",
"nullable": true
},
"stats": {
"$ref": "#/components/schemas/StoryStats"
},
"comment_ids": {
"description": "An array of IDs of Comments attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"cycle_time": {
"description": "The cycle time (in seconds) of this story when complete.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date the Story was created.",
"type": "string",
"format": "date-time"
},
"moved_at": {
"description": "The time/date the Story was last changed workflow-state.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"app_url",
"archived",
"started",
"story_links",
"entity_type",
"labels",
"task_ids",
"mention_ids",
"member_mention_ids",
"story_type",
"file_ids",
"num_tasks_completed",
"workflow_id",
"completed_at_override",
"started_at",
"completed_at",
"name",
"global_id",
"completed",
"blocker",
"epic_id",
"story_template_id",
"external_links",
"previous_iteration_ids",
"requested_by_id",
"iteration_id",
"label_ids",
"started_at_override",
"group_id",
"workflow_state_id",
"updated_at",
"group_mention_ids",
"follower_ids",
"owner_ids",
"external_id",
"id",
"estimate",
"position",
"blocked",
"project_id",
"linked_file_ids",
"deadline",
"stats",
"comment_ids",
"created_at",
"moved_at"
]
},
"StoryStats": {
"description": "The stats object for Stories",
"type": "object",
"properties": {
"num_related_documents": {
"description": "The number of documents related to this Story.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"num_related_documents"
]
},
"SyncedItem": {
"x-doc-skip": true,
"description": "The synced item for the story.",
"type": "object",
"properties": {
"external_id": {
"description": "The id used to reference an external entity.",
"type": "string"
},
"url": {
"description": "The url to the external entity.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"external_id",
"url"
]
},
"Task": {
"description": "A Task on a Story.",
"type": "object",
"properties": {
"description": {
"description": "Full text of the Task.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"story_id": {
"description": "The unique identifier of the parent Story.",
"type": "integer",
"format": "int64"
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"member_mention_ids": {
"description": "An array of UUIDs of Members mentioned in this Task.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"completed_at": {
"description": "The time/date the Task was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"updated_at": {
"description": "The time/date the Task was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_mention_ids": {
"description": "An array of UUIDs of Groups mentioned in this Task.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs of the Owners of this Task.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"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.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Task.",
"type": "integer",
"format": "int64"
},
"position": {
"description": "The number corresponding to the Task's position within a list of Tasks on a Story.",
"type": "integer",
"format": "int64"
},
"complete": {
"description": "True/false boolean indicating whether the Task has been completed.",
"type": "boolean"
},
"created_at": {
"description": "The time/date the Task was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"description",
"entity_type",
"story_id",
"mention_ids",
"member_mention_ids",
"completed_at",
"global_id",
"updated_at",
"group_mention_ids",
"owner_ids",
"external_id",
"id",
"position",
"complete",
"created_at"
]
},
"ThreadedComment": {
"description": "Comments associated with Epic Discussions.",
"type": "object",
"properties": {
"app_url": {
"description": "The Shortcut application url for the Comment.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"deleted": {
"description": "True/false boolean indicating whether the Comment is deleted.",
"type": "boolean"
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"author_id": {
"description": "The unique ID of the Member that authored the Comment.",
"type": "string",
"format": "uuid"
},
"member_mention_ids": {
"description": "An array of Member IDs that have been mentioned in this Comment.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"comments": {
"description": "A nested array of threaded comments.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ThreadedComment"
}
},
"updated_at": {
"description": "The time/date the Comment was updated.",
"type": "string",
"format": "date-time"
},
"group_mention_ids": {
"description": "An array of Group IDs that have been mentioned in this Comment.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"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.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID of the Comment.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date the Comment was created.",
"type": "string",
"format": "date-time"
},
"text": {
"description": "The text of the Comment.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"app_url",
"entity_type",
"deleted",
"mention_ids",
"author_id",
"member_mention_ids",
"comments",
"updated_at",
"group_mention_ids",
"external_id",
"id",
"created_at",
"text"
]
},
"TypedStoryLink": {
"description": "The type of Story Link. The string can be subject or object. ",
"type": "object",
"properties": {
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"object_id": {
"description": "The ID of the object Story.",
"type": "integer",
"format": "int64"
},
"verb": {
"description": "How the subject Story acts on the object Story. This can be \"blocks\", \"duplicates\", or \"relates to\".",
"type": "string"
},
"type": {
"description": "This indicates whether the Story is the subject or object in the Story Link.",
"type": "string"
},
"updated_at": {
"description": "The time/date when the Story Link was last updated.",
"type": "string",
"format": "date-time"
},
"id": {
"description": "The unique identifier of the Story Link.",
"type": "integer",
"format": "int64"
},
"subject_id": {
"description": "The ID of the subject Story.",
"type": "integer",
"format": "int64"
},
"subject_workflow_state_id": {
"description": "The workflow state of the \"subject\" story.",
"x-doc-skip": true,
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date when the Story Link was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"entity_type",
"object_id",
"verb",
"type",
"updated_at",
"id",
"subject_id",
"subject_workflow_state_id",
"created_at"
]
},
"UnusableEntitlementError": {
"type": "object",
"properties": {
"reason_tag": {
"description": "The tag for violating an entitlement action.",
"type": "string",
"enum": [
"entitlement-violation"
]
},
"entitlement_tag": {
"maxLength": 63,
"minLength": 1,
"description": "Short tag describing the unusable entitlement action taken by the user.",
"type": "string"
},
"message": {
"maxLength": 256,
"minLength": 1,
"description": "Message displayed to the user on why their action failed.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"reason_tag",
"entitlement_tag",
"message"
]
},
"UpdateCategory": {
"x-doc-skip": true,
"type": "object",
"properties": {
"name": {
"minLength": 1,
"description": "The new name of the Category.",
"type": "string"
},
"color": {
"description": "The hex color to be displayed with the Category (for example, \"#ff0000\").",
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"minLength": 1,
"type": "string",
"nullable": true
},
"archived": {
"description": "A true/false boolean indicating if the Category has been archived.",
"type": "boolean"
}
},
"additionalProperties": false
},
"UpdateComment": {
"x-doc-skip": true,
"type": "object",
"properties": {
"text": {
"description": "The updated comment text.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
},
"UpdateCustomField": {
"type": "object",
"properties": {
"enabled": {
"description": "Indicates whether the Field is enabled for the Workspace. Only enabled fields can be applied to Stories.",
"type": "boolean"
},
"name": {
"maxLength": 63,
"minLength": 1,
"description": "A collection of objects representing reporting periods for years.",
"type": "string"
},
"values": {
"description": "A collection of EnumValue objects representing the values in the domain of some Custom Field.",
"type": "array",
"items": {
"$ref": "#/components/schemas/UpdateCustomFieldEnumValue"
}
},
"icon_set_identifier": {
"maxLength": 63,
"minLength": 1,
"description": "A frontend-controlled string that represents the icon for this custom field.",
"type": "string"
},
"description": {
"description": "A description of the purpose of this field.",
"type": "string"
},
"before_id": {
"description": "The ID of the CustomField we want to move this CustomField before.",
"type": "string",
"format": "uuid"
},
"after_id": {
"description": "The ID of the CustomField we want to move this CustomField after.",
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
"UpdateCustomFieldEnumValue": {
"type": "object",
"properties": {
"id": {
"description": "The unique ID of an existing EnumValue within the CustomField's domain.",
"type": "string",
"format": "uuid"
},
"value": {
"maxLength": 63,
"minLength": 1,
"description": "A string value within the domain of this Custom Field.",
"type": "string"
},
"color_key": {
"description": "A color key associated with this EnumValue within the CustomField's domain.",
"type": "string",
"nullable": true
},
"enabled": {
"description": "Whether this EnumValue is enabled for its CustomField or not. Leaving this key out of the request leaves the current enabled state untouched.",
"type": "boolean"
}
},
"additionalProperties": false
},
"UpdateEntityTemplate": {
"description": "Request parameters for changing either a template's name or any of\n the attributes it is designed to pre-populate.",
"type": "object",
"properties": {
"name": {
"maxLength": 128,
"minLength": 1,
"description": "The updated template name.",
"type": "string"
},
"story_contents": {
"$ref": "#/components/schemas/UpdateStoryContents"
}
},
"additionalProperties": false
},
"UpdateEpic": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 100000,
"description": "The Epic's description.",
"type": "string"
},
"archived": {
"description": "A true/false boolean indicating whether the Epic is in archived state.",
"type": "boolean"
},
"labels": {
"description": "An array of Labels attached to the Epic.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"completed_at_override": {
"description": "A manual override for the time/date the Epic was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"objective_ids": {
"description": "An array of IDs for Objectives to which this Epic is related.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"name": {
"maxLength": 256,
"minLength": 1,
"description": "The Epic's name.",
"type": "string"
},
"planned_start_date": {
"description": "The Epic's planned start date.",
"type": "string",
"format": "date-time",
"nullable": true
},
"state": {
"description": "`Deprecated` The Epic's state (to do, in progress, or done); will be ignored when `epic_state_id` is set.",
"type": "string",
"enum": [
"in progress",
"to do",
"done"
]
},
"milestone_id": {
"description": "`Deprecated` The ID of the Milestone this Epic is related to. Use `objective_ids`.",
"type": "integer",
"format": "int64",
"nullable": true
},
"requested_by_id": {
"description": "The ID of the member that requested the epic.",
"type": "string",
"format": "uuid"
},
"epic_state_id": {
"description": "The ID of the Epic State.",
"type": "integer",
"format": "int64"
},
"started_at_override": {
"description": "A manual override for the time/date the Epic was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_id": {
"description": "`Deprecated` The ID of the group to associate with the epic. Use `group_ids`.",
"type": "string",
"format": "uuid",
"nullable": true
},
"follower_ids": {
"description": "An array of UUIDs for any Members you want to add as Followers on this Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_ids": {
"description": "An array of UUIDS for Groups to which this Epic is related.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs for any members you want to add as Owners on this Epic.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"maxLength": 128,
"description": "This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string"
},
"before_id": {
"description": "The ID of the Epic we want to move this Epic before.",
"type": "integer",
"format": "int64"
},
"after_id": {
"description": "The ID of the Epic we want to move this Epic after.",
"type": "integer",
"format": "int64"
},
"deadline": {
"description": "The Epic's deadline.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"UpdateFile": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 4096,
"description": "The description of the file.",
"type": "string"
},
"created_at": {
"description": "The time/date that the file was uploaded.",
"type": "string",
"format": "date-time"
},
"updated_at": {
"description": "The time/date that the file was last updated.",
"type": "string",
"format": "date-time"
},
"name": {
"maxLength": 1024,
"minLength": 1,
"description": "The name of the file.",
"type": "string"
},
"uploader_id": {
"description": "The unique ID assigned to the Member who uploaded the file to Shortcut.",
"type": "string",
"format": "uuid"
},
"external_id": {
"maxLength": 128,
"description": "An additional ID that you may wish to assign to the file.",
"type": "string"
}
},
"additionalProperties": false
},
"UpdateGroup": {
"type": "object",
"properties": {
"description": {
"maxLength": 4096,
"description": "The description of this Group.",
"type": "string"
},
"archived": {
"description": "Whether or not this Group is archived.",
"type": "boolean",
"nullable": true
},
"color": {
"description": "The color you wish to use for the Group in the system.",
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"minLength": 1,
"type": "string",
"nullable": true
},
"display_icon_id": {
"description": "The Icon id for the avatar of this Group.",
"type": "string",
"format": "uuid",
"nullable": true
},
"mention_name": {
"maxLength": 63,
"minLength": 1,
"description": "The mention name of this Group.",
"type": "string"
},
"name": {
"maxLength": 63,
"minLength": 1,
"description": "The name of this Group.",
"type": "string"
},
"color_key": {
"description": "The color key you wish to use for the Group in the system.",
"type": "string",
"enum": [
"blue",
"purple",
"midnight-blue",
"orange",
"yellow-green",
"brass",
"gray",
"fuchsia",
"yellow",
"pink",
"sky-blue",
"green",
"red",
"black",
"slate",
"turquoise"
]
},
"default_workflow_id": {
"description": "The ID of the default workflow for stories created in this group.",
"type": "integer",
"format": "int64",
"nullable": true
},
"member_ids": {
"description": "The Member ids to add to this Group.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"workflow_ids": {
"description": "The Workflow ids to add to the Group.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"additionalProperties": false
},
"UpdateHealth": {
"x-doc-skip": true,
"type": "object",
"properties": {
"status": {
"description": "The health status of the Epic.",
"type": "string",
"enum": [
"At Risk",
"On Track",
"Off Track",
"No Health"
]
},
"text": {
"description": "The description of the Health status.",
"type": "string"
}
},
"additionalProperties": false
},
"UpdateIteration": {
"type": "object",
"properties": {
"follower_ids": {
"description": "An array of UUIDs for any Members you want to add as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"group_ids": {
"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.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"labels": {
"description": "An array of Labels attached to the Iteration.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"description": {
"maxLength": 100000,
"description": "The description of the Iteration.",
"type": "string"
},
"name": {
"maxLength": 256,
"minLength": 1,
"description": "The name of this Iteration",
"type": "string"
},
"start_date": {
"minLength": 1,
"description": "The date this Iteration begins, e.g. 2019-07-01",
"type": "string"
},
"end_date": {
"minLength": 1,
"description": "The date this Iteration ends, e.g. 2019-07-05.",
"type": "string"
}
},
"additionalProperties": false
},
"UpdateKeyResult": {
"type": "object",
"properties": {
"name": {
"maxLength": 1024,
"description": "The name of the Key Result.",
"type": "string"
},
"initial_observed_value": {
"$ref": "#/components/schemas/KeyResultValue"
},
"observed_value": {
"$ref": "#/components/schemas/KeyResultValue"
},
"target_value": {
"$ref": "#/components/schemas/KeyResultValue"
}
},
"additionalProperties": false
},
"UpdateLabel": {
"x-doc-skip": true,
"type": "object",
"properties": {
"name": {
"maxLength": 128,
"minLength": 1,
"description": "The new name of the label.",
"type": "string"
},
"description": {
"maxLength": 1024,
"description": "The new description of the label.",
"type": "string"
},
"color": {
"description": "The hex color to be displayed with the Label (for example, \"#ff0000\").",
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"minLength": 1,
"type": "string",
"nullable": true
},
"archived": {
"description": "A true/false boolean indicating if the Label has been archived.",
"type": "boolean"
}
},
"additionalProperties": false
},
"UpdateLinkedFile": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 512,
"description": "The description of the file.",
"type": "string"
},
"story_id": {
"description": "The ID of the linked story.",
"type": "integer",
"format": "int64"
},
"name": {
"minLength": 1,
"description": "The name of the file.",
"type": "string"
},
"thumbnail_url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The URL of the thumbnail, if the integration provided it.",
"type": "string"
},
"type": {
"description": "The integration type of the file (e.g. google, dropbox, box).",
"type": "string",
"enum": [
"google",
"url",
"dropbox",
"box",
"onedrive"
]
},
"size": {
"description": "The filesize, if the integration provided it.",
"type": "integer",
"format": "int64"
},
"uploader_id": {
"description": "The UUID of the member that uploaded the file.",
"type": "string",
"format": "uuid"
},
"url": {
"pattern": "^https?://.+$",
"maxLength": 2048,
"description": "The URL of linked file.",
"type": "string"
}
},
"additionalProperties": false
},
"UpdateMilestone": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 100000,
"description": "The Milestone's description.",
"type": "string"
},
"archived": {
"description": "A boolean indicating whether the Milestone is archived or not",
"type": "boolean"
},
"completed_at_override": {
"description": "A manual override for the time/date the Milestone was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"name": {
"maxLength": 256,
"minLength": 1,
"description": "The name of the Milestone.",
"type": "string"
},
"state": {
"description": "The workflow state that the Milestone is in.",
"type": "string",
"enum": [
"in progress",
"to do",
"done"
]
},
"started_at_override": {
"description": "A manual override for the time/date the Milestone was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"categories": {
"description": "An array of IDs of Categories attached to the Milestone.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateCategoryParams"
}
},
"before_id": {
"description": "The ID of the Milestone we want to move this Milestone before.",
"type": "integer",
"format": "int64"
},
"after_id": {
"description": "The ID of the Milestone we want to move this Milestone after.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false
},
"UpdateObjective": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 100000,
"description": "The Objective's description.",
"type": "string"
},
"archived": {
"description": "A boolean indicating whether the Objective is archived or not",
"type": "boolean"
},
"completed_at_override": {
"description": "A manual override for the time/date the Objective was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"name": {
"maxLength": 256,
"minLength": 1,
"description": "The name of the Objective.",
"type": "string"
},
"state": {
"description": "The workflow state that the Objective is in.",
"type": "string",
"enum": [
"in progress",
"to do",
"done"
]
},
"started_at_override": {
"description": "A manual override for the time/date the Objective was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"categories": {
"description": "An array of IDs of Categories attached to the Objective.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateCategoryParams"
}
},
"before_id": {
"description": "The ID of the Objective we want to move this Objective before.",
"type": "integer",
"format": "int64"
},
"after_id": {
"description": "The ID of the Objective we want to move this Objective after.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false
},
"UpdateProject": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 100000,
"description": "The Project's description.",
"type": "string"
},
"archived": {
"description": "A true/false boolean indicating whether the Story is in archived state.",
"type": "boolean"
},
"days_to_thermometer": {
"description": "The number of days before the thermometer appears in the Story summary.",
"type": "integer",
"format": "int64"
},
"color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"description": "The color that represents the Project in the UI.",
"minLength": 1,
"type": "string"
},
"name": {
"maxLength": 128,
"minLength": 1,
"description": "The Project's name.",
"type": "string"
},
"follower_ids": {
"description": "An array of UUIDs for any Members you want to add as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"show_thermometer": {
"description": "Configuration to enable or disable thermometers in the Story summary.",
"type": "boolean"
},
"team_id": {
"description": "The ID of the team the project belongs to.",
"type": "integer",
"format": "int64"
},
"abbreviation": {
"description": "The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.",
"type": "string"
}
},
"additionalProperties": false
},
"UpdateStories": {
"x-doc-skip": true,
"type": "object",
"properties": {
"archived": {
"description": "If the Stories should be archived or not.",
"type": "boolean"
},
"story_ids": {
"description": "The Ids of the Stories you wish to update.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string",
"enum": [
"feature",
"chore",
"bug"
]
},
"move_to": {
"description": "One of \"first\" or \"last\". This can be used to move the given story to the first or last position in the workflow state.",
"type": "string",
"enum": [
"last",
"first"
]
},
"follower_ids_add": {
"description": "The UUIDs of the new followers to be added.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"epic_id": {
"description": "The ID of the epic the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"external_links": {
"description": "An array of External Links associated with this story.",
"type": "array",
"items": {
"type": "string"
}
},
"follower_ids_remove": {
"description": "The UUIDs of the followers to be removed.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"requested_by_id": {
"description": "The ID of the member that requested the story.",
"type": "string",
"format": "uuid"
},
"iteration_id": {
"description": "The ID of the iteration the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"custom_fields_remove": {
"description": "A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldValueParams"
}
},
"labels_add": {
"description": "An array of labels to be added.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"group_id": {
"description": "The Id of the Group the Stories should belong to.",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The ID of the workflow state to put the stories in.",
"type": "integer",
"format": "int64"
},
"before_id": {
"description": "The ID of the story that the stories are to be moved before.",
"type": "integer",
"format": "int64"
},
"estimate": {
"description": "The numeric point estimate of the story. Can also be null, which means unestimated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"after_id": {
"description": "The ID of the story that the stories are to be moved below.",
"type": "integer",
"format": "int64"
},
"owner_ids_remove": {
"description": "The UUIDs of the owners to be removed.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"custom_fields_add": {
"description": "A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldValueParams"
}
},
"project_id": {
"description": "The ID of the Project the Stories should belong to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"labels_remove": {
"description": "An array of labels to be removed.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time",
"nullable": true
},
"owner_ids_add": {
"description": "The UUIDs of the new owners to be added.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
}
},
"additionalProperties": false,
"required": [
"story_ids"
]
},
"UpdateStory": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 100000,
"description": "The description of the story.",
"type": "string"
},
"archived": {
"description": "True if the story is archived, otherwise false.",
"type": "boolean"
},
"labels": {
"description": "An array of labels attached to the story.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"pull_request_ids": {
"description": "An array of IDs of Pull/Merge Requests attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string",
"enum": [
"feature",
"chore",
"bug"
]
},
"custom_fields": {
"description": "A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldValueParams"
}
},
"move_to": {
"description": "One of \"first\" or \"last\". This can be used to move the given story to the first or last position in the workflow state.",
"type": "string",
"enum": [
"last",
"first"
]
},
"file_ids": {
"description": "An array of IDs of files attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"completed_at_override": {
"description": "A manual override for the time/date the Story was completed.",
"type": "string",
"format": "date-time",
"nullable": true
},
"name": {
"maxLength": 512,
"minLength": 1,
"description": "The title of the story.",
"type": "string"
},
"epic_id": {
"description": "The ID of the epic the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"external_links": {
"description": "An array of External Links associated with this story.",
"type": "array",
"items": {
"type": "string"
}
},
"branch_ids": {
"description": "An array of IDs of Branches attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"commit_ids": {
"description": "An array of IDs of Commits attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"requested_by_id": {
"description": "The ID of the member that requested the story.",
"type": "string",
"format": "uuid"
},
"iteration_id": {
"description": "The ID of the iteration the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"started_at_override": {
"description": "A manual override for the time/date the Story was started.",
"type": "string",
"format": "date-time",
"nullable": true
},
"group_id": {
"description": "The ID of the group to associate with this story",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The ID of the workflow state to put the story in.",
"type": "integer",
"format": "int64"
},
"follower_ids": {
"description": "An array of UUIDs of the followers of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"uniqueItems": true
},
"parent_story_id": {
"description": "The parent story id. If you want to unset this value set parent_story_id to null.",
"x-doc-skip": true,
"type": "integer",
"format": "int64",
"nullable": true
},
"before_id": {
"description": "The ID of the story we want to move this story before.",
"type": "integer",
"format": "int64"
},
"estimate": {
"description": "The numeric point estimate of the story. Can also be null, which means unestimated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"after_id": {
"description": "The ID of the story we want to move this story after.",
"type": "integer",
"format": "int64"
},
"project_id": {
"description": "The ID of the project the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"linked_file_ids": {
"description": "An array of IDs of linked files attached to the story.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"UpdateStoryComment": {
"x-doc-skip": true,
"type": "object",
"properties": {
"text": {
"maxLength": 100000,
"description": "The updated comment text.",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"text"
]
},
"UpdateStoryContents": {
"description": "Updated attributes for the template to populate.",
"type": "object",
"properties": {
"description": {
"description": "The description of the story.",
"type": "string"
},
"labels": {
"description": "An array of labels to be populated by the template.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateLabelParams"
}
},
"story_type": {
"description": "The type of story (feature, bug, chore).",
"type": "string"
},
"custom_fields": {
"description": "An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldValueParams"
}
},
"file_ids": {
"description": "An array of the attached file IDs to be populated.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"name": {
"description": "The name of the story.",
"type": "string"
},
"epic_id": {
"description": "The ID of the epic the to be populated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"external_links": {
"description": "An array of external links to be populated.",
"type": "array",
"items": {
"type": "string"
}
},
"sub_tasks": {
"description": "An array of sub-tasks connected to the story",
"x-doc-skip": true,
"type": "array",
"items": {
"$ref": "#/components/schemas/CreateSubTaskParams"
}
},
"iteration_id": {
"description": "The ID of the iteration the to be populated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"tasks": {
"description": "An array of tasks to be populated by the template.",
"type": "array",
"items": {
"$ref": "#/components/schemas/BaseTaskParams"
}
},
"group_id": {
"description": "The ID of the group to be populated.",
"type": "string",
"format": "uuid",
"nullable": true
},
"workflow_state_id": {
"description": "The ID of the workflow state to be populated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"follower_ids": {
"description": "An array of UUIDs for any Members listed as Followers.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"estimate": {
"description": "The numeric point estimate to be populated.",
"type": "integer",
"format": "int64",
"nullable": true
},
"project_id": {
"description": "The ID of the project the story belongs to.",
"type": "integer",
"format": "int64",
"nullable": true
},
"linked_file_ids": {
"description": "An array of the linked file IDs to be populated.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"uniqueItems": true
},
"deadline": {
"description": "The due date of the story.",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
},
"UpdateStoryLink": {
"x-doc-skip": true,
"type": "object",
"properties": {
"verb": {
"description": "The type of link.",
"type": "string",
"enum": [
"blocks",
"duplicates",
"relates to"
]
},
"subject_id": {
"description": "The ID of the subject Story.",
"type": "integer",
"format": "int64"
},
"object_id": {
"description": "The ID of the object Story.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false
},
"UpdateTask": {
"x-doc-skip": true,
"type": "object",
"properties": {
"description": {
"maxLength": 2048,
"minLength": 1,
"description": "The Task's description.",
"type": "string"
},
"owner_ids": {
"description": "An array of UUIDs of the owners of this story.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"complete": {
"description": "A true/false boolean indicating whether the task is complete.",
"type": "boolean"
},
"before_id": {
"description": "Move task before this task ID.",
"type": "integer",
"format": "int64"
},
"after_id": {
"description": "Move task after this task ID.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false
},
"UploadedFile": {
"description": "An UploadedFile is any document uploaded to your Shortcut Workspace. Files attached from a third-party service are different: see the Linked Files endpoint.",
"type": "object",
"properties": {
"description": {
"description": "The description of the file.",
"type": "string",
"nullable": true
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"story_ids": {
"description": "The unique IDs of the Stories associated with this file.",
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"mention_ids": {
"description": "`Deprecated:` use `member_mention_ids`.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"member_mention_ids": {
"description": "The unique IDs of the Members who are mentioned in the file description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"name": {
"description": "The optional User-specified name of the file.",
"type": "string"
},
"thumbnail_url": {
"description": "The url where the thumbnail of the file can be found in Shortcut.",
"type": "string",
"nullable": true
},
"size": {
"description": "The size of the file.",
"type": "integer",
"format": "int64"
},
"uploader_id": {
"description": "The unique ID of the Member who uploaded the file.",
"type": "string",
"format": "uuid"
},
"content_type": {
"description": "Free form string corresponding to a text or image file.",
"type": "string"
},
"updated_at": {
"description": "The time/date that the file was updated.",
"type": "string",
"format": "date-time",
"nullable": true
},
"filename": {
"description": "The name assigned to the file in Shortcut upon upload.",
"type": "string"
},
"group_mention_ids": {
"description": "The unique IDs of the Groups who are mentioned in the file description.",
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"external_id": {
"description": "This field can be set to another unique ID. In the case that the File has been imported from another tool, the ID in the other tool can be indicated here.",
"type": "string",
"nullable": true
},
"id": {
"description": "The unique ID for the file.",
"type": "integer",
"format": "int64"
},
"url": {
"description": "The URL for the file.",
"type": "string",
"nullable": true
},
"created_at": {
"description": "The time/date that the file was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"description",
"entity_type",
"story_ids",
"mention_ids",
"member_mention_ids",
"name",
"thumbnail_url",
"size",
"uploader_id",
"content_type",
"updated_at",
"filename",
"group_mention_ids",
"external_id",
"id",
"url",
"created_at"
]
},
"Workflow": {
"description": "Workflow is the array of defined Workflow States. Workflow can be queried using the API but must be updated in the Shortcut UI. ",
"type": "object",
"properties": {
"description": {
"description": "A description of the workflow.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"project_ids": {
"description": "An array of IDs of projects within the Workflow.",
"type": "array",
"items": {
"type": "number",
"format": "double"
}
},
"states": {
"description": "A map of the states in this Workflow.",
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkflowState"
}
},
"name": {
"description": "The name of the workflow.",
"type": "string"
},
"updated_at": {
"description": "The date the Workflow was updated.",
"type": "string",
"format": "date-time"
},
"auto_assign_owner": {
"description": "Indicates if an owner is automatically assigned when an unowned story is started.",
"type": "boolean"
},
"id": {
"description": "The unique ID of the Workflow.",
"type": "integer",
"format": "int64"
},
"team_id": {
"description": "The ID of the team the workflow belongs to.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The date the Workflow was created.",
"type": "string",
"format": "date-time"
},
"default_state_id": {
"description": "The unique ID of the default state that new Stories are entered into.",
"type": "integer",
"format": "int64"
}
},
"additionalProperties": false,
"required": [
"description",
"entity_type",
"project_ids",
"states",
"name",
"updated_at",
"auto_assign_owner",
"id",
"team_id",
"created_at",
"default_state_id"
]
},
"WorkflowState": {
"description": "Workflow State is any of the at least 3 columns. Workflow States correspond to one of 3 types: Unstarted, Started, or Done.",
"type": "object",
"properties": {
"description": {
"description": "The description of what sort of Stories belong in that Workflow state.",
"type": "string"
},
"entity_type": {
"description": "A string description of this resource.",
"type": "string"
},
"color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"format": "css-color",
"description": "The hex color for this Workflow State.",
"minLength": 1,
"type": "string"
},
"verb": {
"description": "The verb that triggers a move to that Workflow State when making VCS commits.",
"type": "string",
"nullable": true
},
"name": {
"description": "The Workflow State's name.",
"type": "string"
},
"global_id": {
"x-doc-skip": true,
"type": "string"
},
"num_stories": {
"description": "The number of Stories currently in that Workflow State.",
"type": "integer",
"format": "int64"
},
"type": {
"description": "The type of Workflow State (Unstarted, Started, or Finished)",
"type": "string"
},
"updated_at": {
"description": "When the Workflow State was last updated.",
"type": "string",
"format": "date-time"
},
"id": {
"description": "The unique ID of the Workflow State.",
"type": "integer",
"format": "int64"
},
"num_story_templates": {
"description": "The number of Story Templates associated with that Workflow State.",
"type": "integer",
"format": "int64"
},
"position": {
"description": "The position that the Workflow State is in, starting with 0 at the left.",
"type": "integer",
"format": "int64"
},
"created_at": {
"description": "The time/date the Workflow State was created.",
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"description",
"entity_type",
"verb",
"name",
"global_id",
"num_stories",
"type",
"updated_at",
"id",
"num_story_templates",
"position",
"created_at"
]
}
}
}
}