Last updated: Wednesday, November 06, 2024
We changed our name!
Clubhouse is now called Shortcut!
Changes to the REST API
This changes some things about the REST API:
- The API Token header is now
Shortcut-Token
.Clubhouse-Token
is deprecated but will keep working until November 13, 2021. - The API URL is
https://api.app.shortcut.com
.https://api.clubhouse.io
is deprecated, but will keep working until November 13, 2021. - After September 14, 2021 all links in REST API responses which were to
clubhouse.io
domains will be toshortcut.com
domains instead,
even if you made the request toapi.clubhouse.io
.
Updating your application
To update your application or scripts, you should:
- Change your
Clubhouse-Token
header toShortcut-Token
. You can do this today. - Remove any assumptions that links in the response are always to
clubhouse.io
domains. (You probably don’t have any assumptions like this, but just in case.) - Change the API URL from
https://api.clubhouse.io
tohttps://api.app.shortcut.com
.
Introduction
The Shortcut REST API provides a greater amount of control over your workspace’s Shortcut data than what is possible using the Shortcut web app. You can use this API to build custom integrations or automate even more of your workspace’s workflow. If you have any questions about anything related to our API or this documentation, please let us know - we’re happy to help!
API Status
This is the current version of the Shortcut API. Any changes made to this API will be made in a backwards-compatible way.
If you’re currently using REST API Beta, you can safely replace beta
with v3
in your API URLs.
Examples
See our API Cookbook for real-life examples of using the API.
Authentication
API URL
https://api.app.shortcut.com/
The Shortcut API uses token-based authentication. To generate an API token, go to https://app.shortcut.com/settings/account/api-tokens. To make it easier to explore our API, we recommend saving this token as an environment variable in your local dev environment:
export SHORTCUT_API_TOKEN="YOUR API TOKEN HERE"
This will allow you to copy and paste many of the example curl
requests on this page into your terminal to try them out.
Requests made with a missing or invalid token will get a 401 Unauthorized
response. All requests must be made over HTTPS. Tokens provide complete access to your Shortcut account, so keep them secure. Don’t paste them into your source code, use an environment variable instead. For security reasons, we will immediately invalidate any tokens we find have been made public.
API requests can accept the API token from the Shortcut-Token
header or the token
query parameter. However, the query parameter method is deprecated, and will be removed in future versions of the API.
Rate Limiting
The Shortcut REST API limits requests to 200 per minute. Any requests over that limit will not be processed, and will return a 429 (“Too Many Requests”) response code.
String Length Limits
Many string values have length limits in requests or responses.
If there is a limit, it is shown in parentheses after the type name.
For example, “String(100)” means the string must be 100 characters or fewer.
Requests which exceed a string limit will fail with a 4xx response.
Response types with limits are a guarantee we will never send a longer value.
Setting Colors
Any request that provides a color
value should provide a valid css color value. Acceptable values are hexadecimal strings (prefixed with #
). See the CSS documentation for more details (Note that global, keyword, or named color values are not accepted).
Any value that doesn’t match the above will be rejected.
Response Formats
Our API speaks JSON. You should always supply Content-Type: application/json
in your headers. See our endpoint documentation below for example requests using curl
.
Nullable Fields
Some optional parameters accept a null
value, which effectively unsets or deletes the property. For example, you can estimate a story as 1
, and then later on remove the estimate by using null
.
Swagger / OpenAPI file
We provide a machine-readable version of our API specified in Swagger / OpenAPI. You can download a JSON version here.
Migrating from v2 to v3
There are no longer any differences between v2 and v3 except for some small
changes to how markdown text is processed. Updating should not break anything.
To update, simply change the /v2/
in your URL paths to /v3/
.
No other changes should be required.
Categories
List Categories
List Categories returns a list of all Categories and their attributes.
Definition
GET https://api.app.shortcut.com/api/v3/categories
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/categories"
Example Response
[
{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
]
Responses
Code | Description |
---|---|
200 | [ Category, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Category
Create Category allows you to create a new Category in Shortcut.
Definition
POST https://api.app.shortcut.com/api/v3/categories
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "color": "#6515dd", "external_id": null, "name": null }' \
-L "https://api.app.shortcut.com/api/v3/categories"
Example Response
{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
Body Parameters
Name | Description |
---|---|
color Color | The hex color to be displayed with the Category (for example, “#ff0000”). |
external_id String (128) | 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. |
name String (128) | Required. The name of the new Category. |
Responses
Code | Description |
---|---|
201 | Category |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Category
Get Category returns information about the selected Category.
Definition
GET https://api.app.shortcut.com/api/v3/categories/{category-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/categories/{category-public-id}"
Example Response
{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
category-public-id Integer | Required. The unique ID of the Category. |
Responses
Code | Description |
---|---|
200 | Category |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Category
Update Category allows you to replace a Category name with another name. If you try to name a Category something that already exists, you will receive a 422 response.
Definition
PUT https://api.app.shortcut.com/api/v3/categories/{category-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "archived": true, "color": "#6515dd", "name": "foo" }' \
-L "https://api.app.shortcut.com/api/v3/categories/{category-public-id}"
Example Response
{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
category-public-id Integer | Required. The unique ID of the Category you wish to update. |
Body Parameters
Name | Description |
---|---|
archived Boolean | A true/false boolean indicating if the Category has been archived. |
color Color or null | The hex color to be displayed with the Category (for example, “#ff0000”). |
name String | The new name of the Category. |
Responses
Code | Description |
---|---|
200 | Category |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Category
Delete Category can be used to delete any Category.
Definition
DELETE https://api.app.shortcut.com/api/v3/categories/{category-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/categories/{category-public-id}"
URL Parameters
Name | Description |
---|---|
category-public-id Integer | Required. The unique ID of the Category. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Category Milestones
List Category Milestones returns a list of all Milestones with the Category.
Definition
GET https://api.app.shortcut.com/api/v3/categories/{category-public-id}/milestones
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/categories/{category-public-id}/milestones"
Example Response
[
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Parameters
Name | Description |
---|---|
category-public-id Integer | Required. The unique ID of the Category. |
Responses
Code | Description |
---|---|
200 | [ Milestone, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Category Objectives
Returns a list of all Objectives with the Category.
Definition
GET https://api.app.shortcut.com/api/v3/categories/{category-public-id}/objectives
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/categories/{category-public-id}/objectives"
Example Response
[
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Parameters
Name | Description |
---|---|
category-public-id Integer | Required. The unique ID of the Category. |
Responses
Code | Description |
---|---|
200 | [ Milestone, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Custom-Fields
List Custom Fields
Definition
GET https://api.app.shortcut.com/api/v3/custom-fields
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/custom-fields"
Example Response
[
{
"canonical_name": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": null,
"enabled": true,
"entity_type": "custom-field",
"field_type": "enum",
"icon_set_identifier": null,
"id": "12345678-9012-3456-7890-123456789012",
"name": null,
"position": 123,
"updated_at": "2016-12-31T12:30:00Z",
"values": [{
"color_key": "foo",
"entity_type": "custom-field-enum-value",
"id": "12345678-9012-3456-7890-123456789012",
"position": 123,
"value": null
}]
}
]
Responses
Code | Description |
---|---|
200 | [ CustomField, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Custom Field
Definition
GET https://api.app.shortcut.com/api/v3/custom-fields/{custom-field-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/custom-fields/{custom-field-public-id}"
Example Response
{
"canonical_name": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": null,
"enabled": true,
"entity_type": "custom-field",
"field_type": "enum",
"icon_set_identifier": null,
"id": "12345678-9012-3456-7890-123456789012",
"name": null,
"position": 123,
"updated_at": "2016-12-31T12:30:00Z",
"values": [{
"color_key": "foo",
"entity_type": "custom-field-enum-value",
"id": "12345678-9012-3456-7890-123456789012",
"position": 123,
"value": null
}]
}
URL Parameters
Name | Description |
---|---|
custom-field-public-id UUID | Required. The unique ID of the CustomField. |
Responses
Code | Description |
---|---|
200 | CustomField |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Custom Field
Update Custom Field can be used to update the definition of a Custom Field. The order of items in the ‘values’ collection is interpreted to be their ascending sort order.To delete an existing enum value, simply omit it from the ‘values’ collection. New enum values may be created inline by including an object in the ‘values’ collection having a ‘value’ entry with no ‘id’ (eg. {‘value’: ‘myNewValue’, ‘color_key’: ‘green’}).
Definition
PUT https://api.app.shortcut.com/api/v3/custom-fields/{custom-field-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "after_id": "12345678-9012-3456-7890-123456789012", "before_id": "12345678-9012-3456-7890-123456789012", "description": "foo", "enabled": true, "icon_set_identifier": null, "name": null, "values": [{ "color_key": "foo", "enabled": true, "id": "12345678-9012-3456-7890-123456789012", "value": null }] }' \
-L "https://api.app.shortcut.com/api/v3/custom-fields/{custom-field-public-id}"
Example Response
{
"canonical_name": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": null,
"enabled": true,
"entity_type": "custom-field",
"field_type": "enum",
"icon_set_identifier": null,
"id": "12345678-9012-3456-7890-123456789012",
"name": null,
"position": 123,
"updated_at": "2016-12-31T12:30:00Z",
"values": [{
"color_key": "foo",
"entity_type": "custom-field-enum-value",
"id": "12345678-9012-3456-7890-123456789012",
"position": 123,
"value": null
}]
}
URL Parameters
Name | Description |
---|---|
custom-field-public-id UUID | Required. The unique ID of the CustomField. |
Body Parameters
Name | Description |
---|---|
after_id UUID | The ID of the CustomField we want to move this CustomField after. |
before_id UUID | The ID of the CustomField we want to move this CustomField before. |
description String | A description of the purpose of this field. |
enabled Boolean | Indicates whether the Field is enabled for the Workspace. Only enabled fields can be applied to Stories. |
icon_set_identifier String (63) | A frontend-controlled string that represents the icon for this custom field. |
name String (63) | A collection of objects representing reporting periods for years. |
values Array [UpdateCustomFieldEnumValue] | A collection of EnumValue objects representing the values in the domain of some Custom Field. |
Responses
Code | Description |
---|---|
200 | CustomField |
400 | Schema mismatch |
404 | Resource does not exist |
409 | DataConflictError |
422 | Unprocessable |
Delete Custom Field
Definition
DELETE https://api.app.shortcut.com/api/v3/custom-fields/{custom-field-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/custom-fields/{custom-field-public-id}"
URL Parameters
Name | Description |
---|---|
custom-field-public-id UUID | Required. The unique ID of the CustomField. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Entity-Templates
List Entity Templates
List all the entity templates for the Workspace.
Definition
GET https://api.app.shortcut.com/api/v3/entity-templates
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/entity-templates"
Example Response
[
{
"author_id": "12345678-9012-3456-7890-123456789012",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"last_used_at": "2016-12-31T12:30:00Z",
"name": "foo",
"story_contents": {
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_links": [],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"name": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"project_id": 123,
"story_type": "foo",
"tasks": [{
"complete": true,
"description": "foo",
"external_id": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123
}],
"workflow_state_id": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
]
Responses
Code | Description |
---|---|
200 | [ EntityTemplate, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Entity Template
Create a new entity template for the Workspace.
Definition
POST https://api.app.shortcut.com/api/v3/entity-templates
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "author_id": "12345678-9012-3456-7890-123456789012", "name": null, "story_contents": { "custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}], "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_id": 123, "estimate": 123, "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{
"color": "#6515dd",
"description": null,
"external_id": null,
"name": null
}], "linked_file_ids": [123], "name": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "story_type": "foo", "tasks": [{
"complete": true,
"description": null,
"external_id": null,
"owner_ids": ["12345678-9012-3456-7890-123456789012"]
}], "workflow_state_id": 123 } }' \
-L "https://api.app.shortcut.com/api/v3/entity-templates"
Example Response
{
"author_id": "12345678-9012-3456-7890-123456789012",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"last_used_at": "2016-12-31T12:30:00Z",
"name": "foo",
"story_contents": {
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_links": [],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"name": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"project_id": 123,
"story_type": "foo",
"tasks": [{
"complete": true,
"description": "foo",
"external_id": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123
}],
"workflow_state_id": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
Body Parameters
Name | Description |
---|---|
author_id UUID | The id of the user creating this template. |
name String (128) | Required. The name of the new entity template |
story_contents CreateStoryContents | Required. A map of story attributes this template populates. |
Responses
Code | Description |
---|---|
201 | EntityTemplate |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Disable Story Templates
Disables the Story Template feature for the Workspace.
Definition
PUT https://api.app.shortcut.com/api/v3/entity-templates/disable
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/entity-templates/disable"
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Enable Story Templates
Enables the Story Template feature for the Workspace.
Definition
PUT https://api.app.shortcut.com/api/v3/entity-templates/enable
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/entity-templates/enable"
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Entity Template
Get Entity Template returns information about a given entity template.
Definition
GET https://api.app.shortcut.com/api/v3/entity-templates/{entity-template-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/entity-templates/{entity-template-public-id}"
Example Response
{
"author_id": "12345678-9012-3456-7890-123456789012",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"last_used_at": "2016-12-31T12:30:00Z",
"name": "foo",
"story_contents": {
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_links": [],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"name": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"project_id": 123,
"story_type": "foo",
"tasks": [{
"complete": true,
"description": "foo",
"external_id": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123
}],
"workflow_state_id": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
entity-template-public-id UUID | Required. The unique ID of the entity template. |
Responses
Code | Description |
---|---|
200 | EntityTemplate |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Entity Template
Update an entity template’s name or its contents.
Definition
PUT https://api.app.shortcut.com/api/v3/entity-templates/{entity-template-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "name": null, "story_contents": { "custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}], "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_id": 123, "estimate": 123, "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{
"color": "#6515dd",
"description": null,
"external_id": null,
"name": null
}], "linked_file_ids": [123], "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "story_type": "foo", "tasks": [{
"complete": true,
"description": null,
"external_id": null,
"owner_ids": ["12345678-9012-3456-7890-123456789012"]
}], "workflow_state_id": 123 } }' \
-L "https://api.app.shortcut.com/api/v3/entity-templates/{entity-template-public-id}"
Example Response
{
"author_id": "12345678-9012-3456-7890-123456789012",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"last_used_at": "2016-12-31T12:30:00Z",
"name": "foo",
"story_contents": {
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_links": [],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"name": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"project_id": 123,
"story_type": "foo",
"tasks": [{
"complete": true,
"description": "foo",
"external_id": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123
}],
"workflow_state_id": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
entity-template-public-id UUID | Required. The unique ID of the template to be updated. |
Body Parameters
Name | Description |
---|---|
name String (128) | The updated template name. |
story_contents UpdateStoryContents | Updated attributes for the template to populate. |
Responses
Code | Description |
---|---|
200 | EntityTemplate |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Entity Template
Definition
DELETE https://api.app.shortcut.com/api/v3/entity-templates/{entity-template-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/entity-templates/{entity-template-public-id}"
URL Parameters
Name | Description |
---|---|
entity-template-public-id UUID | Required. The unique ID of the entity template. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Epic-Workflow
Get Epic Workflow
Returns the Epic Workflow for the Workspace.
Definition
GET https://api.app.shortcut.com/api/v3/epic-workflow
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/epic-workflow"
Example Response
{
"created_at": "2016-12-31T12:30:00Z",
"default_epic_state_id": 123,
"entity_type": "foo",
"epic_states": [{
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo",
"position": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
Responses
Code | Description |
---|---|
200 | EpicWorkflow |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Epics
List Epics
List Epics returns a list of all Epics and their attributes.
Definition
GET https://api.app.shortcut.com/api/v3/epics
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/epics"
Example Response
[
{
"app_url": "foo",
"archived": true,
"associated_groups": [{
"associated_stories_count": 123,
"group_id": "12345678-9012-3456-7890-123456789012"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_state_id": 123,
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"milestone_id": 123,
"name": "foo",
"objective_ids": [123],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"planned_start_date": "2016-12-31T12:30:00Z",
"position": 123,
"productboard_id": "12345678-9012-3456-7890-123456789012",
"productboard_name": "foo",
"productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
"productboard_url": "foo",
"project_ids": [123],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"last_story_update": "2016-12-31T12:30:00Z",
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"stories_without_projects": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Query Params Parameters
Name | Description |
---|---|
includes_description Boolean | A true/false boolean indicating whether to return Epics with their descriptions. |
Responses
Code | Description |
---|---|
200 | [ EpicSlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Epic
Create Epic allows you to create a new Epic in Shortcut.
Definition
POST https://api.app.shortcut.com/api/v3/epics
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "completed_at_override": "2016-12-31T12:30:00Z", "created_at": "2016-12-31T12:30:00Z", "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_state_id": 123, "external_id": null, "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "group_ids": ["12345678-9012-3456-7890-123456789012"], "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "milestone_id": 123, "name": null, "objective_ids": [123], "owner_ids": ["12345678-9012-3456-7890-123456789012"], "planned_start_date": "2016-12-31T12:30:00Z", "requested_by_id": "12345678-9012-3456-7890-123456789012", "started_at_override": "2016-12-31T12:30:00Z", "state": "done", "updated_at": "2016-12-31T12:30:00Z" }' \
-L "https://api.app.shortcut.com/api/v3/epics"
Example Response
{
"app_url": "foo",
"archived": true,
"associated_groups": [{
"associated_stories_count": 123,
"group_id": "12345678-9012-3456-7890-123456789012"
}],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_state_id": 123,
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"milestone_id": 123,
"name": "foo",
"objective_ids": [123],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"planned_start_date": "2016-12-31T12:30:00Z",
"position": 123,
"productboard_id": "12345678-9012-3456-7890-123456789012",
"productboard_name": "foo",
"productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
"productboard_url": "foo",
"project_ids": [123],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"last_story_update": "2016-12-31T12:30:00Z",
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"stories_without_projects": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
Body Parameters
Name | Description |
---|---|
completed_at_override Date | A manual override for the time/date the Epic was completed. |
created_at Date | Defaults to the time/date it is created but can be set to reflect another date. |
deadline Date or null | The Epic’s deadline. |
description String (100000) | The Epic’s description. |
epic_state_id Integer | The ID of the Epic State. |
external_id String (128) | This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers on this new Epic. |
group_id UUID or null | Deprecated The ID of the group to associate with the epic. Use group_ids . |
group_ids Array [UUID] | An array of UUIDS for Groups to which this Epic is related. |
labels Array [CreateLabelParams] | An array of Labels attached to the Epic. |
milestone_id Integer or null | Deprecated The ID of the Milestone this Epic is related to. Use objective_ids . |
name String (256) | Required. The Epic’s name. |
objective_ids Array [Integer] | An array of IDs for Objectives to which this Epic is related. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Epic. |
planned_start_date Date or null | The Epic’s planned start date. |
requested_by_id UUID | The ID of the member that requested the epic. |
started_at_override Date | A manual override for the time/date the Epic was started. |
state Enum (done, in progress, to do) | Deprecated The Epic’s state (to do, in progress, or done); will be ignored when epic_state_id is set. |
updated_at Date | Defaults to the time/date it is created but can be set to reflect another date. |
Responses
Code | Description |
---|---|
201 | Epic |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Epic
Get Epic returns information about the selected Epic.
Definition
GET https://api.app.shortcut.com/api/v3/epics/{epic-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"associated_groups": [{
"associated_stories_count": 123,
"group_id": "12345678-9012-3456-7890-123456789012"
}],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_state_id": 123,
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"milestone_id": 123,
"name": "foo",
"objective_ids": [123],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"planned_start_date": "2016-12-31T12:30:00Z",
"position": 123,
"productboard_id": "12345678-9012-3456-7890-123456789012",
"productboard_name": "foo",
"productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
"productboard_url": "foo",
"project_ids": [123],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"last_story_update": "2016-12-31T12:30:00Z",
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"stories_without_projects": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The unique ID of the Epic. |
Responses
Code | Description |
---|---|
200 | Epic |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Epic
Update Epic can be used to update numerous fields in the Epic. The only required parameter is Epic ID, which can be found in the Shortcut UI.
Definition
PUT https://api.app.shortcut.com/api/v3/epics/{epic-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "after_id": 123, "archived": true, "before_id": 123, "completed_at_override": "2016-12-31T12:30:00Z", "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_state_id": 123, "external_id": null, "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "group_ids": ["12345678-9012-3456-7890-123456789012"], "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "milestone_id": 123, "name": null, "objective_ids": [123], "owner_ids": ["12345678-9012-3456-7890-123456789012"], "planned_start_date": "2016-12-31T12:30:00Z", "requested_by_id": "12345678-9012-3456-7890-123456789012", "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"associated_groups": [{
"associated_stories_count": 123,
"group_id": "12345678-9012-3456-7890-123456789012"
}],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_state_id": 123,
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"milestone_id": 123,
"name": "foo",
"objective_ids": [123],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"planned_start_date": "2016-12-31T12:30:00Z",
"position": 123,
"productboard_id": "12345678-9012-3456-7890-123456789012",
"productboard_name": "foo",
"productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
"productboard_url": "foo",
"project_ids": [123],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"last_story_update": "2016-12-31T12:30:00Z",
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"stories_without_projects": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The unique ID of the Epic. |
Body Parameters
Name | Description |
---|---|
after_id Integer | The ID of the Epic we want to move this Epic after. |
archived Boolean | A true/false boolean indicating whether the Epic is in archived state. |
before_id Integer | The ID of the Epic we want to move this Epic before. |
completed_at_override Date or null | A manual override for the time/date the Epic was completed. |
deadline Date or null | The Epic’s deadline. |
description String (100000) | The Epic’s description. |
epic_state_id Integer | The ID of the Epic State. |
external_id String (128) | This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers on this Epic. |
group_id UUID or null | Deprecated The ID of the group to associate with the epic. Use group_ids . |
group_ids Array [UUID] | An array of UUIDS for Groups to which this Epic is related. |
labels Array [CreateLabelParams] | An array of Labels attached to the Epic. |
milestone_id Integer or null | Deprecated The ID of the Milestone this Epic is related to. Use objective_ids . |
name String (256) | The Epic’s name. |
objective_ids Array [Integer] | An array of IDs for Objectives to which this Epic is related. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this Epic. |
planned_start_date Date or null | The Epic’s planned start date. |
requested_by_id UUID | The ID of the member that requested the epic. |
started_at_override Date or null | A manual override for the time/date the Epic was started. |
state Enum (done, in progress, to do) | Deprecated The Epic’s state (to do, in progress, or done); will be ignored when epic_state_id is set. |
Responses
Code | Description |
---|---|
200 | Epic |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Epic
Delete Epic can be used to delete the Epic. The only required parameter is Epic ID.
Definition
DELETE https://api.app.shortcut.com/api/v3/epics/{epic-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}"
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The unique ID of the Epic. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Epic Comments
Get a list of all Comments on an Epic.
Definition
GET https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments"
Example Response
[
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The unique ID of the Epic. |
Responses
Code | Description |
---|---|
200 | [ ThreadedComment, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Epic Comment
This endpoint allows you to create a threaded Comment on an Epic.
Definition
POST https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": null, "text": null, "updated_at": "2016-12-31T12:30:00Z" }' \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments"
Example Response
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The ID of the associated Epic. |
Body Parameters
Name | Description |
---|---|
author_id UUID | The Member ID of the Comment’s author. Defaults to the user identified by the API token. |
created_at Date | Defaults to the time/date the comment is created, but can be set to reflect another date. |
external_id String (128) | 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. |
text String (100000) | Required. The comment text. |
updated_at Date | Defaults to the time/date the comment is last updated, but can be set to reflect another date. |
Responses
Code | Description |
---|---|
201 | ThreadedComment |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Epic Comment
This endpoint returns information about the selected Epic Comment.
Definition
GET https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments/{comment-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments/{comment-public-id}"
Example Response
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The ID of the associated Epic. |
comment-public-id Integer | Required. The ID of the Comment. |
Responses
Code | Description |
---|---|
200 | ThreadedComment |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Epic Comment Comment
This endpoint allows you to create a nested Comment reply to an existing Epic Comment.
Definition
POST https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments/{comment-public-id}
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": null, "text": null, "updated_at": "2016-12-31T12:30:00Z" }' \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments/{comment-public-id}"
Example Response
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The ID of the associated Epic. |
comment-public-id Integer | Required. The ID of the parent Epic Comment. |
Body Parameters
Name | Description |
---|---|
author_id UUID | The Member ID of the Comment’s author. Defaults to the user identified by the API token. |
created_at Date | Defaults to the time/date the comment is created, but can be set to reflect another date. |
external_id String (128) | 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. |
text String (100000) | Required. The comment text. |
updated_at Date | Defaults to the time/date the comment is last updated, but can be set to reflect another date. |
Responses
Code | Description |
---|---|
201 | ThreadedComment |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Epic Comment
This endpoint allows you to update a threaded Comment on an Epic.
Definition
PUT https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments/{comment-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "text": "foo" }' \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments/{comment-public-id}"
Example Response
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The ID of the associated Epic. |
comment-public-id Integer | Required. The ID of the Comment. |
Body Parameters
Name | Description |
---|---|
text String | Required. The updated comment text. |
Responses
Code | Description |
---|---|
200 | ThreadedComment |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Epic Comment
This endpoint allows you to delete a Comment from an Epic.
Definition
DELETE https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments/{comment-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/comments/{comment-public-id}"
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The ID of the associated Epic. |
comment-public-id Integer | Required. The ID of the Comment. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Epic Stories
Get a list of all Stories in an Epic.
Definition
GET https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/stories
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/stories"
Example Response
[
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"comment_ids": [123],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
]
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The unique ID of the Epic. |
URL Query Params Parameters
Name | Description |
---|---|
includes_description Boolean | A true/false boolean indicating whether to return Stories with their descriptions. |
Responses
Code | Description |
---|---|
200 | [ StorySlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Unlink Productboard from Epic
This endpoint allows you to unlink a productboard epic.
Definition
POST https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/unlink-productboard
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/epics/{epic-public-id}/unlink-productboard"
URL Parameters
Name | Description |
---|---|
epic-public-id Integer | Required. The unique ID of the Epic. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
External-Link
Get External Link Stories
Get Stories which have a given External Link associated with them.
Definition
GET https://api.app.shortcut.com/api/v3/external-link/stories
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/external-link/stories"
Example Response
[
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"comment_ids": [123],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
]
URL Query Params Parameters
Name | Description |
---|---|
external_link String (2048) | Required. The external link associated with one or more stories. |
Responses
Code | Description |
---|---|
200 | [ StorySlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Files
List Files
List Files returns a list of all UploadedFiles in the workspace.
Definition
GET https://api.app.shortcut.com/api/v3/files
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/files"
Example Response
[
{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}
]
Responses
Code | Description |
---|---|
200 | [ UploadedFile, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Upload Files
Upload Files uploads one or many files and optionally associates them with a story.
Use the multipart/form-data content-type to upload.
Each file
key should contain a separate file.
Each UploadedFile’s name comes from the Content-Disposition header “filename” directive for that field.
Definition
POST https://api.app.shortcut.com/api/v3/files
Example Request
curl -X POST \
-H "Content-Type: multipart/form-data" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-F 'story_id=123' \
-F 'file0=@/path/to/file.gif;filename=myFileNameOverride.gif' \
-L "https://api.app.shortcut.com/api/v3/files"
Example Response
[
{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}
]
Form Parameters
Name | Description |
---|---|
story_id Integer | The story ID that these files will be associated with. |
file0 File | Required. A file upload. At least one is required. |
file1 File | Optional additional files. |
file2 File | Optional additional files. |
file3 File | Optional additional files. |
Responses
Code | Description |
---|---|
201 | [ UploadedFile, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get File
Get File returns information about the selected UploadedFile.
Definition
GET https://api.app.shortcut.com/api/v3/files/{file-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/files/{file-public-id}"
Example Response
{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}
URL Parameters
Name | Description |
---|---|
file-public-id Integer | Required. The File’s unique ID. |
Responses
Code | Description |
---|---|
200 | UploadedFile |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update File
Update File updates the properties of an UploadedFile (but not its content).
Definition
PUT https://api.app.shortcut.com/api/v3/files/{file-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "created_at": "2016-12-31T12:30:00Z", "description": null, "external_id": null, "name": null, "updated_at": "2016-12-31T12:30:00Z", "uploader_id": "12345678-9012-3456-7890-123456789012" }' \
-L "https://api.app.shortcut.com/api/v3/files/{file-public-id}"
Example Response
{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}
URL Parameters
Name | Description |
---|---|
file-public-id Integer | Required. The unique ID assigned to the file in Shortcut. |
Body Parameters
Name | Description |
---|---|
created_at Date | The time/date that the file was uploaded. |
description String (4096) | The description of the file. |
external_id String (128) | An additional ID that you may wish to assign to the file. |
name String (1024) | The name of the file. |
updated_at Date | The time/date that the file was last updated. |
uploader_id UUID | The unique ID assigned to the Member who uploaded the file to Shortcut. |
Responses
Code | Description |
---|---|
200 | UploadedFile |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete File
Delete File deletes a previously uploaded file.
Definition
DELETE https://api.app.shortcut.com/api/v3/files/{file-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/files/{file-public-id}"
URL Parameters
Name | Description |
---|---|
file-public-id Integer | Required. The File’s unique ID. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Groups
List Groups
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.
Definition
GET https://api.app.shortcut.com/api/v3/groups
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/groups"
Example Response
[
{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"color_key": "black",
"description": "foo",
"display_icon": {
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
},
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"member_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_name": "foo",
"name": "foo",
"num_epics_started": 123,
"num_stories": 123,
"num_stories_backlog": 123,
"num_stories_started": 123,
"workflow_ids": [123]
}
]
Responses
Code | Description |
---|---|
200 | [ Group, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Group
Definition
POST https://api.app.shortcut.com/api/v3/groups
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "color": "#6515dd", "color_key": "black", "description": null, "display_icon_id": "12345678-9012-3456-7890-123456789012", "member_ids": ["12345678-9012-3456-7890-123456789012"], "mention_name": null, "name": null, "workflow_ids": [123] }' \
-L "https://api.app.shortcut.com/api/v3/groups"
Example Response
{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"color_key": "black",
"description": "foo",
"display_icon": {
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
},
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"member_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_name": "foo",
"name": "foo",
"num_epics_started": 123,
"num_stories": 123,
"num_stories_backlog": 123,
"num_stories_started": 123,
"workflow_ids": [123]
}
Body Parameters
Name | Description |
---|---|
color Color | The color you wish to use for the Group in the system. |
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) | The color key you wish to use for the Group in the system. |
description String (4096) | The description of the Group. |
display_icon_id UUID | The Icon id for the avatar of this Group. |
member_ids Array [UUID] | The Member ids to add to this Group. |
mention_name String (63) | Required. The mention name of this Group. |
name String (63) | Required. The name of this Group. |
workflow_ids Array [Integer] | The Workflow ids to add to the Group. |
Responses
Code | Description |
---|---|
201 | Group |
400 | Schema mismatch |
403 | UnusableEntitlementError |
404 | Resource does not exist |
422 | Unprocessable |
Get Group
Definition
GET https://api.app.shortcut.com/api/v3/groups/{group-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/groups/{group-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"color_key": "black",
"description": "foo",
"display_icon": {
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
},
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"member_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_name": "foo",
"name": "foo",
"num_epics_started": 123,
"num_stories": 123,
"num_stories_backlog": 123,
"num_stories_started": 123,
"workflow_ids": [123]
}
URL Parameters
Name | Description |
---|---|
group-public-id UUID | Required. The unique ID of the Group. |
Responses
Code | Description |
---|---|
200 | Group |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Group
Definition
PUT https://api.app.shortcut.com/api/v3/groups/{group-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "archived": true, "color": "#6515dd", "color_key": "black", "description": null, "display_icon_id": "12345678-9012-3456-7890-123456789012", "member_ids": ["12345678-9012-3456-7890-123456789012"], "mention_name": null, "name": null, "workflow_ids": [123] }' \
-L "https://api.app.shortcut.com/api/v3/groups/{group-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"color_key": "black",
"description": "foo",
"display_icon": {
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
},
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"member_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_name": "foo",
"name": "foo",
"num_epics_started": 123,
"num_stories": 123,
"num_stories_backlog": 123,
"num_stories_started": 123,
"workflow_ids": [123]
}
URL Parameters
Name | Description |
---|---|
group-public-id UUID | Required. The unique ID of the Group. |
Body Parameters
Name | Description |
---|---|
archived Boolean or null | Whether or not this Group is archived. |
color Color or null | The color you wish to use for the Group in the system. |
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) | The color key you wish to use for the Group in the system. |
description String (4096) | The description of this Group. |
display_icon_id UUID or null | The Icon id for the avatar of this Group. |
member_ids Array [UUID] | The Member ids to add to this Group. |
mention_name String (63) | The mention name of this Group. |
name String (63) | The name of this Group. |
workflow_ids Array [Integer] | The Workflow ids to add to the Group. |
Responses
Code | Description |
---|---|
200 | Group |
400 | Schema mismatch |
403 | UnusableEntitlementError |
404 | Resource does not exist |
422 | Unprocessable |
List Group Stories
List the Stories assigned to the Group. (By default, limited to 1,000).
Definition
GET https://api.app.shortcut.com/api/v3/groups/{group-public-id}/stories
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/groups/{group-public-id}/stories"
Example Response
[
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"comment_ids": [123],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
]
URL Parameters
Name | Description |
---|---|
group-public-id UUID | Required. The unique ID of the Group. |
URL Query Params Parameters
Name | Description |
---|---|
limit Integer | The maximum number of results to return. (Defaults to 1000, max 1000) |
offset Integer | The offset at which to begin returning results. (Defaults to 0) |
Responses
Code | Description |
---|---|
200 | [ StorySlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Iterations
List Iterations
Definition
GET https://api.app.shortcut.com/api/v3/iterations
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/iterations"
Example Response
[
{
"app_url": "foo",
"created_at": "2016-12-31T12:30:00Z",
"end_date": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"start_date": "2016-12-31T12:30:00Z",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"status": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
]
Responses
Code | Description |
---|---|
200 | [ IterationSlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Iteration
Definition
POST https://api.app.shortcut.com/api/v3/iterations
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "description": null, "end_date": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_ids": ["12345678-9012-3456-7890-123456789012"], "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "name": null, "start_date": "foo" }' \
-L "https://api.app.shortcut.com/api/v3/iterations"
Example Response
{
"app_url": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"end_date": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"start_date": "2016-12-31T12:30:00Z",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"status": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
Body Parameters
Name | Description |
---|---|
description String (100000) | The description of the Iteration. |
end_date String | Required. The date this Iteration ends, e.g. 2019-07-01. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers. |
group_ids Array [UUID] | An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI. |
labels Array [CreateLabelParams] | An array of Labels attached to the Iteration. |
name String (256) | Required. The name of this Iteration. |
start_date String | Required. The date this Iteration begins, e.g. 2019-07-01. |
Responses
Code | Description |
---|---|
201 | Iteration |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Disable Iterations
Disables Iterations for the current workspace
Definition
PUT https://api.app.shortcut.com/api/v3/iterations/disable
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/iterations/disable"
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Enable Iterations
Enables Iterations for the current workspace
Definition
PUT https://api.app.shortcut.com/api/v3/iterations/enable
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/iterations/enable"
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Iteration
Definition
GET https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}"
Example Response
{
"app_url": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"end_date": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"start_date": "2016-12-31T12:30:00Z",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"status": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
iteration-public-id Integer | Required. The unique ID of the Iteration. |
Responses
Code | Description |
---|---|
200 | Iteration |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Iteration
Definition
PUT https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "description": null, "end_date": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_ids": ["12345678-9012-3456-7890-123456789012"], "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "name": null, "start_date": "foo" }' \
-L "https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}"
Example Response
{
"app_url": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"end_date": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"start_date": "2016-12-31T12:30:00Z",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"status": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
iteration-public-id Integer | Required. The unique ID of the Iteration. |
Body Parameters
Name | Description |
---|---|
description String (100000) | The description of the Iteration. |
end_date String | The date this Iteration ends, e.g. 2019-07-05. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers. |
group_ids Array [UUID] | An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI. |
labels Array [CreateLabelParams] | An array of Labels attached to the Iteration. |
name String (256) | The name of this Iteration |
start_date String | The date this Iteration begins, e.g. 2019-07-01 |
Responses
Code | Description |
---|---|
200 | Iteration |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Iteration
Definition
DELETE https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}"
URL Parameters
Name | Description |
---|---|
iteration-public-id Integer | Required. The unique ID of the Iteration. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Iteration Stories
Get a list of all Stories in an Iteration.
Definition
GET https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}/stories
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}/stories"
Example Response
[
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"comment_ids": [123],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
]
URL Parameters
Name | Description |
---|---|
iteration-public-id Integer | Required. The unique ID of the Iteration. |
URL Query Params Parameters
Name | Description |
---|---|
includes_description Boolean | A true/false boolean indicating whether to return Stories with their descriptions. |
Responses
Code | Description |
---|---|
200 | [ StorySlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Key-Results
Get Key Result
Get Key Result returns information about a chosen Key Result.
Definition
GET https://api.app.shortcut.com/api/v3/key-results/{key-result-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/key-results/{key-result-public-id}"
Example Response
{
"current_observed_value": {
"boolean_value": true,
"numeric_value": "foo"
},
"current_target_value": {
"boolean_value": true,
"numeric_value": "foo"
},
"id": "12345678-9012-3456-7890-123456789012",
"initial_observed_value": {
"boolean_value": true,
"numeric_value": "foo"
},
"name": "foo",
"objective_id": 123,
"progress": 123,
"type": "boolean"
}
URL Parameters
Name | Description |
---|---|
key-result-public-id UUID | Required. The ID of the Key Result. |
Responses
Code | Description |
---|---|
200 | KeyResult |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Key Result
Update Key Result allows updating a Key Result’s name or initial, observed, or target values.
Definition
PUT https://api.app.shortcut.com/api/v3/key-results/{key-result-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "initial_observed_value": { "boolean_value": true, "numeric_value": "foo" }, "name": null, "observed_value": { "boolean_value": true, "numeric_value": "foo" }, "target_value": { "boolean_value": true, "numeric_value": "foo" } }' \
-L "https://api.app.shortcut.com/api/v3/key-results/{key-result-public-id}"
Example Response
{
"current_observed_value": {
"boolean_value": true,
"numeric_value": "foo"
},
"current_target_value": {
"boolean_value": true,
"numeric_value": "foo"
},
"id": "12345678-9012-3456-7890-123456789012",
"initial_observed_value": {
"boolean_value": true,
"numeric_value": "foo"
},
"name": "foo",
"objective_id": 123,
"progress": 123,
"type": "boolean"
}
URL Parameters
Name | Description |
---|---|
key-result-public-id UUID | Required. The ID of the Key Result. |
Body Parameters
Name | Description |
---|---|
initial_observed_value KeyResultValue | The starting value of the Key Result. |
name String (1024) | The name of the Key Result. |
observed_value KeyResultValue | The starting value of the Key Result. |
target_value KeyResultValue | The starting value of the Key Result. |
Responses
Code | Description |
---|---|
200 | KeyResult |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Labels
List Labels
List Labels returns a list of all Labels and their attributes.
Definition
GET https://api.app.shortcut.com/api/v3/labels
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/labels"
Example Response
[
{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Query Params Parameters
Name | Description |
---|---|
slim Boolean | A true/false boolean indicating if the slim versions of the Label should be returned. |
Responses
Code | Description |
---|---|
200 | [ Label, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Label
Create Label allows you to create a new Label in Shortcut.
Definition
POST https://api.app.shortcut.com/api/v3/labels
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "color": "#6515dd", "description": null, "external_id": null, "name": null }' \
-L "https://api.app.shortcut.com/api/v3/labels"
Example Response
{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
Body Parameters
Name | Description |
---|---|
color Color | The hex color to be displayed with the Label (for example, “#ff0000”). |
description String (1024) | The description of the new Label. |
external_id String (128) | 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. |
name String (128) | Required. The name of the new Label. |
Responses
Code | Description |
---|---|
201 | Label |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Label
Get Label returns information about the selected Label.
Definition
GET https://api.app.shortcut.com/api/v3/labels/{label-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
label-public-id Integer | Required. The unique ID of the Label. |
Responses
Code | Description |
---|---|
200 | Label |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Label
Update Label allows you to replace a Label name with another name. If you try to name a Label something that already exists, you will receive a 422 response.
Definition
PUT https://api.app.shortcut.com/api/v3/labels/{label-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "archived": true, "color": "#6515dd", "description": null, "name": null }' \
-L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
label-public-id Integer | Required. The unique ID of the Label you wish to update. |
Body Parameters
Name | Description |
---|---|
archived Boolean | A true/false boolean indicating if the Label has been archived. |
color Color or null | The hex color to be displayed with the Label (for example, “#ff0000”). |
description String (1024) | The new description of the label. |
name String (128) | The new name of the label. |
Responses
Code | Description |
---|---|
200 | Label |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Label
Delete Label can be used to delete any Label.
Definition
DELETE https://api.app.shortcut.com/api/v3/labels/{label-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}"
URL Parameters
Name | Description |
---|---|
label-public-id Integer | Required. The unique ID of the Label. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Label Epics
List all of the Epics with the Label.
Definition
GET https://api.app.shortcut.com/api/v3/labels/{label-public-id}/epics
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}/epics"
Example Response
[
{
"app_url": "foo",
"archived": true,
"associated_groups": [{
"associated_stories_count": 123,
"group_id": "12345678-9012-3456-7890-123456789012"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_state_id": 123,
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"milestone_id": 123,
"name": "foo",
"objective_ids": [123],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"planned_start_date": "2016-12-31T12:30:00Z",
"position": 123,
"productboard_id": "12345678-9012-3456-7890-123456789012",
"productboard_name": "foo",
"productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
"productboard_url": "foo",
"project_ids": [123],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"last_story_update": "2016-12-31T12:30:00Z",
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"stories_without_projects": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Parameters
Name | Description |
---|---|
label-public-id Integer | Required. The unique ID of the Label. |
Responses
Code | Description |
---|---|
200 | [ EpicSlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Label Stories
List all of the Stories with the Label.
Definition
GET https://api.app.shortcut.com/api/v3/labels/{label-public-id}/stories
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}/stories"
Example Response
[
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"comment_ids": [123],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
]
URL Parameters
Name | Description |
---|---|
label-public-id Integer | Required. The unique ID of the Label. |
URL Query Params Parameters
Name | Description |
---|---|
includes_description Boolean | A true/false boolean indicating whether to return Stories with their descriptions. |
Responses
Code | Description |
---|---|
200 | [ StorySlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Linked-Files
List Linked Files
List Linked Files returns a list of all Linked-Files and their attributes.
Definition
GET https://api.app.shortcut.com/api/v3/linked-files
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/linked-files"
Example Response
[
{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}
]
Responses
Code | Description |
---|---|
200 | [ LinkedFile, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Linked File
Create Linked File allows you to create a new Linked File in Shortcut.
Definition
POST https://api.app.shortcut.com/api/v3/linked-files
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "content_type": null, "description": null, "name": null, "size": 123, "story_id": 123, "thumbnail_url": null, "type": "box", "uploader_id": "12345678-9012-3456-7890-123456789012", "url": null }' \
-L "https://api.app.shortcut.com/api/v3/linked-files"
Example Response
{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}
Body Parameters
Name | Description |
---|---|
content_type String (128) | The content type of the image (e.g. txt/plain). |
description String (512) | The description of the file. |
name String (256) | Required. The name of the file. |
size Integer | The filesize, if the integration provided it. |
story_id Integer | The ID of the linked story. |
thumbnail_url String (2048) | The URL of the thumbnail, if the integration provided it. |
type Enum (box, dropbox, google, onedrive, url) | Required. The integration type of the file (e.g. google, dropbox, box). |
uploader_id UUID | The UUID of the member that uploaded the file. |
url String (2048) | Required. The URL of linked file. |
Responses
Code | Description |
---|---|
201 | LinkedFile |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Linked File
Get File returns information about the selected Linked File.
Definition
GET https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}"
Example Response
{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}
URL Parameters
Name | Description |
---|---|
linked-file-public-id Integer | Required. The unique identifier of the linked file. |
Responses
Code | Description |
---|---|
200 | LinkedFile |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Linked File
Updated Linked File allows you to update properties of a previously attached Linked-File.
Definition
PUT https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "description": null, "name": "foo", "size": 123, "story_id": 123, "thumbnail_url": null, "type": "box", "uploader_id": "12345678-9012-3456-7890-123456789012", "url": null }' \
-L "https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}"
Example Response
{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}
URL Parameters
Name | Description |
---|---|
linked-file-public-id Integer | Required. The unique identifier of the linked file. |
Body Parameters
Name | Description |
---|---|
description String (512) | The description of the file. |
name String | The name of the file. |
size Integer | The filesize, if the integration provided it. |
story_id Integer | The ID of the linked story. |
thumbnail_url String (2048) | The URL of the thumbnail, if the integration provided it. |
type Enum (box, dropbox, google, onedrive, url) | The integration type of the file (e.g. google, dropbox, box). |
uploader_id UUID | The UUID of the member that uploaded the file. |
url String (2048) | The URL of linked file. |
Responses
Code | Description |
---|---|
200 | LinkedFile |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Linked File
Delete Linked File can be used to delete any previously attached Linked-File.
Definition
DELETE https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}"
URL Parameters
Name | Description |
---|---|
linked-file-public-id Integer | Required. The unique identifier of the linked file. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Member
Get Current Member Info
Returns information about the authenticated member.
Definition
GET https://api.app.shortcut.com/api/v3/member
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/member"
Example Response
{
"id": "12345678-9012-3456-7890-123456789012",
"mention_name": "foo",
"name": "foo",
"workspace2": {
"estimate_scale": [123],
"url_slug": "foo"
}
}
Responses
Code | Description |
---|---|
200 | MemberInfo |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Members
List Members
Returns information about members of the Workspace.
Definition
GET https://api.app.shortcut.com/api/v3/members
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/members"
Example Response
[
{
"created_at": "2016-12-31T12:30:00Z",
"disabled": true,
"entity_type": "foo",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"id": "12345678-9012-3456-7890-123456789012",
"profile": {
"deactivated": true,
"display_icon": {
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
},
"email_address": "foo",
"entity_type": "foo",
"gravatar_hash": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"is_owner": true,
"mention_name": "foo",
"name": "foo",
"two_factor_auth_activated": true
},
"role": "foo",
"state": "disabled",
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Query Params Parameters
Name | Description |
---|---|
org-public-id UUID | The unique ID of the Organization to limit the list to. |
Responses
Code | Description |
---|---|
200 | [ Member, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Member
Returns information about a Member.
Definition
GET https://api.app.shortcut.com/api/v3/members/{member-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/members/{member-public-id}"
Example Response
{
"created_at": "2016-12-31T12:30:00Z",
"disabled": true,
"entity_type": "foo",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"id": "12345678-9012-3456-7890-123456789012",
"profile": {
"deactivated": true,
"display_icon": {
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
},
"email_address": "foo",
"entity_type": "foo",
"gravatar_hash": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"is_owner": true,
"mention_name": "foo",
"name": "foo",
"two_factor_auth_activated": true
},
"role": "foo",
"state": "disabled",
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
member-public-id UUID | Required. The Member’s unique ID. |
URL Query Params Parameters
Name | Description |
---|---|
org-public-id UUID | The unique ID of the Organization to limit the lookup to. |
Responses
Code | Description |
---|---|
200 | Member |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Milestones
List Milestones
(Deprecated: Use ‘List Objectives’) List Milestones returns a list of all Milestones and their attributes.
Definition
GET https://api.app.shortcut.com/api/v3/milestones
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/milestones"
Example Response
[
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
]
Responses
Code | Description |
---|---|
200 | [ Milestone, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Milestone
(Deprecated: Use ‘Create Objective’) Create Milestone allows you to create a new Milestone in Shortcut.
Definition
POST https://api.app.shortcut.com/api/v3/milestones
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "categories": [{ "color": "#6515dd", "external_id": null, "name": null }], "completed_at_override": "2016-12-31T12:30:00Z", "description": null, "name": null, "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
-L "https://api.app.shortcut.com/api/v3/milestones"
Example Response
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
Body Parameters
Name | Description |
---|---|
categories Array [CreateCategoryParams] | An array of IDs of Categories attached to the Milestone. |
completed_at_override Date | A manual override for the time/date the Milestone was completed. |
description String (100000) | The Milestone’s description. |
name String (256) | Required. The name of the Milestone. |
started_at_override Date | A manual override for the time/date the Milestone was started. |
state Enum (done, in progress, to do) | The workflow state that the Milestone is in. |
Responses
Code | Description |
---|---|
201 | Milestone |
400 | Schema mismatch |
403 | UnusableEntitlementError |
404 | Resource does not exist |
422 | Unprocessable |
Get Milestone
(Deprecated: Use ‘Get Objective’) Get Milestone returns information about a chosen Milestone.
Definition
GET https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
milestone-public-id Integer | Required. The ID of the Milestone. |
Responses
Code | Description |
---|---|
200 | Milestone |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Milestone
(Deprecated: Use ‘Update Objective’) Update Milestone can be used to update Milestone properties.
Definition
PUT https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "after_id": 123, "archived": true, "before_id": 123, "categories": [{ "color": "#6515dd", "external_id": null, "name": null }], "completed_at_override": "2016-12-31T12:30:00Z", "description": null, "name": null, "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
-L "https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
milestone-public-id Integer | Required. The ID of the Milestone. |
Body Parameters
Name | Description |
---|---|
after_id Integer | The ID of the Milestone we want to move this Milestone after. |
archived Boolean | A boolean indicating whether the Milestone is archived or not |
before_id Integer | The ID of the Milestone we want to move this Milestone before. |
categories Array [CreateCategoryParams] | An array of IDs of Categories attached to the Milestone. |
completed_at_override Date or null | A manual override for the time/date the Milestone was completed. |
description String (100000) | The Milestone’s description. |
name String (256) | The name of the Milestone. |
started_at_override Date or null | A manual override for the time/date the Milestone was started. |
state Enum (done, in progress, to do) | The workflow state that the Milestone is in. |
Responses
Code | Description |
---|---|
200 | Milestone |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Milestone
(Deprecated: Use ‘Delete Objective’) Delete Milestone can be used to delete any Milestone.
Definition
DELETE https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}"
URL Parameters
Name | Description |
---|---|
milestone-public-id Integer | Required. The ID of the Milestone. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Milestone Epics
(Deprecated: Use ‘List Objective Epics’) List all of the Epics within the Milestone.
Definition
GET https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}/epics
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}/epics"
Example Response
[
{
"app_url": "foo",
"archived": true,
"associated_groups": [{
"associated_stories_count": 123,
"group_id": "12345678-9012-3456-7890-123456789012"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_state_id": 123,
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"milestone_id": 123,
"name": "foo",
"objective_ids": [123],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"planned_start_date": "2016-12-31T12:30:00Z",
"position": 123,
"productboard_id": "12345678-9012-3456-7890-123456789012",
"productboard_name": "foo",
"productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
"productboard_url": "foo",
"project_ids": [123],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"last_story_update": "2016-12-31T12:30:00Z",
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"stories_without_projects": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Parameters
Name | Description |
---|---|
milestone-public-id Integer | Required. The ID of the Milestone. |
Responses
Code | Description |
---|---|
200 | [ EpicSlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Objectives
List Objectives
List Objectives returns a list of all Objectives and their attributes.
Definition
GET https://api.app.shortcut.com/api/v3/objectives
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/objectives"
Example Response
[
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
]
Responses
Code | Description |
---|---|
200 | [ Objective, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Objective
Create Objective allows you to create a new Objective in Shortcut.
Definition
POST https://api.app.shortcut.com/api/v3/objectives
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "categories": [{ "color": "#6515dd", "external_id": null, "name": null }], "completed_at_override": "2016-12-31T12:30:00Z", "description": null, "name": null, "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
-L "https://api.app.shortcut.com/api/v3/objectives"
Example Response
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
Body Parameters
Name | Description |
---|---|
categories Array [CreateCategoryParams] | An array of IDs of Categories attached to the Objective. |
completed_at_override Date | A manual override for the time/date the Objective was completed. |
description String (100000) | The Objective’s description. |
name String (256) | Required. The name of the Objective. |
started_at_override Date | A manual override for the time/date the Objective was started. |
state Enum (done, in progress, to do) | The workflow state that the Objective is in. |
Responses
Code | Description |
---|---|
201 | Objective |
400 | Schema mismatch |
403 | UnusableEntitlementError |
404 | Resource does not exist |
422 | Unprocessable |
Get Objective
Get Objective returns information about a chosen Objective.
Definition
GET https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
objective-public-id Integer | Required. The ID of the Objective. |
Responses
Code | Description |
---|---|
200 | Objective |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Objective
Update Objective can be used to update Objective properties.
Definition
PUT https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "after_id": 123, "archived": true, "before_id": 123, "categories": [{ "color": "#6515dd", "external_id": null, "name": null }], "completed_at_override": "2016-12-31T12:30:00Z", "description": null, "name": null, "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
-L "https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
objective-public-id Integer | Required. The ID of the Objective. |
Body Parameters
Name | Description |
---|---|
after_id Integer | The ID of the Objective we want to move this Objective after. |
archived Boolean | A boolean indicating whether the Objective is archived or not |
before_id Integer | The ID of the Objective we want to move this Objective before. |
categories Array [CreateCategoryParams] | An array of IDs of Categories attached to the Objective. |
completed_at_override Date or null | A manual override for the time/date the Objective was completed. |
description String (100000) | The Objective’s description. |
name String (256) | The name of the Objective. |
started_at_override Date or null | A manual override for the time/date the Objective was started. |
state Enum (done, in progress, to do) | The workflow state that the Objective is in. |
Responses
Code | Description |
---|---|
200 | Objective |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Objective
Delete Objective can be used to delete any Objective.
Definition
DELETE https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}"
URL Parameters
Name | Description |
---|---|
objective-public-id Integer | Required. The ID of the Objective. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Objective Epics
List all of the Epics within the Objective.
Definition
GET https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}/epics
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}/epics"
Example Response
[
{
"app_url": "foo",
"archived": true,
"associated_groups": [{
"associated_stories_count": 123,
"group_id": "12345678-9012-3456-7890-123456789012"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_state_id": 123,
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"milestone_id": 123,
"name": "foo",
"objective_ids": [123],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"planned_start_date": "2016-12-31T12:30:00Z",
"position": 123,
"productboard_id": "12345678-9012-3456-7890-123456789012",
"productboard_name": "foo",
"productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
"productboard_url": "foo",
"project_ids": [123],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"last_story_update": "2016-12-31T12:30:00Z",
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"stories_without_projects": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Parameters
Name | Description |
---|---|
objective-public-id Integer | Required. The ID of the Objective. |
Responses
Code | Description |
---|---|
200 | [ EpicSlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Projects
List Projects
List Projects returns a list of all Projects and their attributes.
Definition
GET https://api.app.shortcut.com/api/v3/projects
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/projects"
Example Response
[
{
"abbreviation": "foo",
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"days_to_thermometer": 123,
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_length": 123,
"name": "foo",
"show_thermometer": true,
"start_time": "2016-12-31T12:30:00Z",
"stats": {
"num_points": 123,
"num_related_documents": 123,
"num_stories": 123
},
"team_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123
}
]
Responses
Code | Description |
---|---|
200 | [ Project, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Project
Create Project is used to create a new Shortcut Project.
Definition
POST https://api.app.shortcut.com/api/v3/projects
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "abbreviation": null, "color": "#6515dd", "created_at": "2016-12-31T12:30:00Z", "description": null, "external_id": null, "follower_ids": ["12345678-9012-3456-7890-123456789012"], "iteration_length": 123, "name": null, "start_time": "2016-12-31T12:30:00Z", "team_id": 123, "updated_at": "2016-12-31T12:30:00Z" }' \
-L "https://api.app.shortcut.com/api/v3/projects"
Example Response
{
"abbreviation": "foo",
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"days_to_thermometer": 123,
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_length": 123,
"name": "foo",
"show_thermometer": true,
"start_time": "2016-12-31T12:30:00Z",
"stats": {
"num_points": 123,
"num_related_documents": 123,
"num_stories": 123
},
"team_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123
}
Body Parameters
Name | Description |
---|---|
abbreviation String (63) | The Project abbreviation used in Story summaries. Should be kept to 3 characters at most. |
color Color | The color you wish to use for the Project in the system. |
created_at Date | Defaults to the time/date it is created but can be set to reflect another date. |
description String (100000) | The Project description. |
external_id String (128) | 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. |
follower_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Epic. |
iteration_length Integer | The number of weeks per iteration in this Project. |
name String (128) | Required. The name of the Project. |
start_time Date | The date at which the Project was started. |
team_id Integer | Required. The ID of the team the project belongs to. |
updated_at Date | Defaults to the time/date it is created but can be set to reflect another date. |
Responses
Code | Description |
---|---|
201 | Project |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Project
Get Project returns information about the selected Project.
Definition
GET https://api.app.shortcut.com/api/v3/projects/{project-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/projects/{project-public-id}"
Example Response
{
"abbreviation": "foo",
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"days_to_thermometer": 123,
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_length": 123,
"name": "foo",
"show_thermometer": true,
"start_time": "2016-12-31T12:30:00Z",
"stats": {
"num_points": 123,
"num_related_documents": 123,
"num_stories": 123
},
"team_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123
}
URL Parameters
Name | Description |
---|---|
project-public-id Integer | Required. The unique ID of the Project. |
Responses
Code | Description |
---|---|
200 | Project |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Project
Update Project can be used to change properties of a Project.
Definition
PUT https://api.app.shortcut.com/api/v3/projects/{project-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "abbreviation": "foo", "archived": true, "color": "#6515dd", "days_to_thermometer": 123, "description": null, "follower_ids": ["12345678-9012-3456-7890-123456789012"], "name": null, "show_thermometer": true, "team_id": 123 }' \
-L "https://api.app.shortcut.com/api/v3/projects/{project-public-id}"
Example Response
{
"abbreviation": "foo",
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"days_to_thermometer": 123,
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_length": 123,
"name": "foo",
"show_thermometer": true,
"start_time": "2016-12-31T12:30:00Z",
"stats": {
"num_points": 123,
"num_related_documents": 123,
"num_stories": 123
},
"team_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123
}
URL Parameters
Name | Description |
---|---|
project-public-id Integer | Required. The unique ID of the Project. |
Body Parameters
Name | Description |
---|---|
abbreviation String | The Project abbreviation used in Story summaries. Should be kept to 3 characters at most. |
archived Boolean | A true/false boolean indicating whether the Story is in archived state. |
color Color | The color that represents the Project in the UI. |
days_to_thermometer Integer | The number of days before the thermometer appears in the Story summary. |
description String (100000) | The Project’s description. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers. |
name String (128) | The Project’s name. |
show_thermometer Boolean | Configuration to enable or disable thermometers in the Story summary. |
team_id Integer | The ID of the team the project belongs to. |
Responses
Code | Description |
---|---|
200 | Project |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Project
Delete Project can be used to delete a Project. Projects can only be deleted if all associated Stories are moved or deleted. In the case that the Project cannot be deleted, you will receive a 422 response.
Definition
DELETE https://api.app.shortcut.com/api/v3/projects/{project-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/projects/{project-public-id}"
URL Parameters
Name | Description |
---|---|
project-public-id Integer | Required. The unique ID of the Project. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Stories
List Stories returns a list of all Stories in a selected Project and their attributes.
Definition
GET https://api.app.shortcut.com/api/v3/projects/{project-public-id}/stories
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/projects/{project-public-id}/stories"
Example Response
[
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"comment_ids": [123],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
]
URL Parameters
Name | Description |
---|---|
project-public-id Integer | Required. The unique ID of the Project. |
URL Query Params Parameters
Name | Description |
---|---|
includes_description Boolean | A true/false boolean indicating whether to return Stories with their descriptions. |
Responses
Code | Description |
---|---|
200 | [ StorySlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Repositories
List Repositories
List Repositories returns a list of all Repositories and their attributes.
Definition
GET https://api.app.shortcut.com/api/v3/repositories
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/repositories"
Example Response
[
{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"full_name": "foo",
"id": 123,
"name": "foo",
"type": "bitbucket",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}
]
Responses
Code | Description |
---|---|
200 | [ Repository, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Repository
Get Repository returns information about the selected Repository.
Definition
GET https://api.app.shortcut.com/api/v3/repositories/{repo-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/repositories/{repo-public-id}"
Example Response
{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"full_name": "foo",
"id": 123,
"name": "foo",
"type": "bitbucket",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}
URL Parameters
Name | Description |
---|---|
repo-public-id Integer | Required. The unique ID of the Repository. |
Responses
Code | Description |
---|---|
200 | Repository |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Search
Search
Search lets you search Epics and Stories based on desired parameters. Since ordering of the results can change over time (due to search ranking decay, new Epics and Stories being created), the next
value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
Definition
GET https://api.app.shortcut.com/api/v3/search
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/search"
Example Response
{
"epics": {
"data": [{
"app_url": "foo",
"archived": true,
"associated_groups": [{
"associated_stories_count": 123,
"group_id": "12345678-9012-3456-7890-123456789012"
}],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_state_id": 123,
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"milestone_id": 123,
"name": "foo",
"objective_ids": [123],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"planned_start_date": "2016-12-31T12:30:00Z",
"position": 123,
"productboard_id": "12345678-9012-3456-7890-123456789012",
"productboard_name": "foo",
"productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
"productboard_url": "foo",
"project_ids": [123],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"last_story_update": "2016-12-31T12:30:00Z",
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"stories_without_projects": 123,
"updated_at": "2016-12-31T12:30:00Z"
}],
"next": "foo",
"total": 123
},
"iterations": {
"data": [{
"app_url": "foo",
"created_at": "2016-12-31T12:30:00Z",
"end_date": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"start_date": "2016-12-31T12:30:00Z",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"status": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"next": "foo",
"total": 123
},
"milestones": {
"data": [{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}],
"next": "foo",
"total": 123
},
"stories": {
"data": [{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"branches": [{
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"id": 123,
"merged_branch_ids": [123],
"name": "foo",
"persistent": true,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"repository_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"comment_ids": [123],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}],
"commits": [{
"author_email": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"author_identity": {
"entity_type": "foo",
"name": "foo",
"type": "bitbucket"
},
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"hash": "foo",
"id": 123,
"message": "foo",
"repository_id": 123,
"timestamp": "2016-12-31T12:30:00Z",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"tasks": [{
"complete": true,
"completed_at": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"story_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}],
"next": "foo",
"total": 123
}
}
URL Query Params Parameters
Name | Description |
---|---|
query String | Required. See our help center article on search operators |
page_size Integer | The number of search results to include in a page. Minimum of 1 and maximum of 25. |
detail Enum (full, slim) | The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”. |
next String | The next page token. |
entity_types Array [Enum (epic, iteration, milestone, objective, story)] | A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story. |
Responses
Code | Description |
---|---|
200 | SearchResults |
400 | Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError |
404 | Resource does not exist |
422 | Unprocessable |
Search Epics
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.
Definition
GET https://api.app.shortcut.com/api/v3/search/epics
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/search/epics"
Example Response
{
"data": [{
"app_url": "foo",
"archived": true,
"associated_groups": [{
"associated_stories_count": 123,
"group_id": "12345678-9012-3456-7890-123456789012"
}],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"comments": [Recursive],
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"text": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_state_id": 123,
"external_id": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"milestone_id": 123,
"name": "foo",
"objective_ids": [123],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"planned_start_date": "2016-12-31T12:30:00Z",
"position": 123,
"productboard_id": "12345678-9012-3456-7890-123456789012",
"productboard_name": "foo",
"productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
"productboard_url": "foo",
"project_ids": [123],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"last_story_update": "2016-12-31T12:30:00Z",
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"stories_without_projects": 123,
"updated_at": "2016-12-31T12:30:00Z"
}],
"next": "foo",
"total": 123
}
URL Query Params Parameters
Name | Description |
---|---|
query String | Required. See our help center article on search operators |
page_size Integer | The number of search results to include in a page. Minimum of 1 and maximum of 25. |
detail Enum (full, slim) | The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”. |
next String | The next page token. |
entity_types Array [Enum (epic, iteration, milestone, objective, story)] | A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story. |
Responses
Code | Description |
---|---|
200 | EpicSearchResults |
400 | Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError |
404 | Resource does not exist |
422 | Unprocessable |
Search Iterations
Search Iterations lets you search Iterations based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Iterations being created), the next
value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
Definition
GET https://api.app.shortcut.com/api/v3/search/iterations
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/search/iterations"
Example Response
{
"data": [{
"app_url": "foo",
"created_at": "2016-12-31T12:30:00Z",
"end_date": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_ids": ["12345678-9012-3456-7890-123456789012"],
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"stats": {
"num_epics": 123,
"num_epics_completed": 123,
"num_epics_in_progress": 123,
"num_epics_total": 123,
"num_epics_unstarted": 123,
"num_points_backlog": 123,
"num_points_completed": 123,
"num_points_in_progress": 123,
"num_points_total": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_completed": 123,
"num_stories_in_progress": 123,
"num_stories_total": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"start_date": "2016-12-31T12:30:00Z",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_points": 123,
"num_points_backlog": 123,
"num_points_done": 123,
"num_points_started": 123,
"num_points_unstarted": 123,
"num_related_documents": 123,
"num_stories_backlog": 123,
"num_stories_done": 123,
"num_stories_started": 123,
"num_stories_unestimated": 123,
"num_stories_unstarted": 123
},
"status": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"next": "foo",
"total": 123
}
URL Query Params Parameters
Name | Description |
---|---|
query String | Required. See our help center article on search operators |
page_size Integer | The number of search results to include in a page. Minimum of 1 and maximum of 25. |
detail Enum (full, slim) | The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”. |
next String | The next page token. |
entity_types Array [Enum (epic, iteration, milestone, objective, story)] | A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story. |
Responses
Code | Description |
---|---|
200 | IterationSearchResults |
400 | Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError |
404 | Resource does not exist |
422 | Unprocessable |
Search Milestones
Search Milestones lets you search Milestones based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Milestones being created), the next
value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
Definition
GET https://api.app.shortcut.com/api/v3/search/milestones
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/search/milestones"
Example Response
{
"data": [{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}],
"next": "foo",
"total": 123
}
URL Query Params Parameters
Name | Description |
---|---|
query String | Required. See our help center article on search operators |
page_size Integer | The number of search results to include in a page. Minimum of 1 and maximum of 25. |
detail Enum (full, slim) | The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”. |
next String | The next page token. |
entity_types Array [Enum (epic, iteration, milestone, objective, story)] | A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story. |
Responses
Code | Description |
---|---|
200 | ObjectiveSearchResults |
400 | Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError |
404 | Resource does not exist |
422 | Unprocessable |
Search Objectives
Search Objectives lets you search Objectives based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Objectives being created), the next
value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
Definition
GET https://api.app.shortcut.com/api/v3/search/objectives
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/search/objectives"
Example Response
{
"data": [{
"app_url": "foo",
"archived": true,
"categories": [{
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"key_result_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"position": 123,
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"state": "foo",
"stats": {
"average_cycle_time": 123,
"average_lead_time": 123,
"num_related_documents": 123
},
"updated_at": "2016-12-31T12:30:00Z"
}],
"next": "foo",
"total": 123
}
URL Query Params Parameters
Name | Description |
---|---|
query String | Required. See our help center article on search operators |
page_size Integer | The number of search results to include in a page. Minimum of 1 and maximum of 25. |
detail Enum (full, slim) | The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”. |
next String | The next page token. |
entity_types Array [Enum (epic, iteration, milestone, objective, story)] | A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story. |
Responses
Code | Description |
---|---|
200 | ObjectiveSearchResults |
400 | Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError |
404 | Resource does not exist |
422 | Unprocessable |
Search Stories
Search Stories lets you search Stories based on desired parameters. Since ordering of stories can change over time (due to search ranking decay, new stories being created), the next
value from the previous response can be used as the path and query string for the next page to ensure stable ordering.
Definition
GET https://api.app.shortcut.com/api/v3/search/stories
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/search/stories"
Example Response
{
"data": [{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"branches": [{
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"id": 123,
"merged_branch_ids": [123],
"name": "foo",
"persistent": true,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"repository_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"comment_ids": [123],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}],
"commits": [{
"author_email": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"author_identity": {
"entity_type": "foo",
"name": "foo",
"type": "bitbucket"
},
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"hash": "foo",
"id": 123,
"message": "foo",
"repository_id": 123,
"timestamp": "2016-12-31T12:30:00Z",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"tasks": [{
"complete": true,
"completed_at": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"story_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}],
"next": "foo",
"total": 123
}
URL Query Params Parameters
Name | Description |
---|---|
query String | Required. See our help center article on search operators |
page_size Integer | The number of search results to include in a page. Minimum of 1 and maximum of 25. |
detail Enum (full, slim) | The amount of detail included in each result item. “full” will include all descriptions and comments and more fields on related items such as pull requests, branches and tasks. “slim” omits larger fulltext fields such as descriptions and comments and only references related items by id. The default is “full”. |
next String | The next page token. |
entity_types Array [Enum (epic, iteration, milestone, objective, story)] | A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story. |
Responses
Code | Description |
---|---|
200 | StorySearchResults |
400 | Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError |
404 | Resource does not exist |
422 | Unprocessable |
Stories
Create Story
Create Story is used to add a new story to your Shortcut Workspace.
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.
Definition
POST https://api.app.shortcut.com/api/v3/stories
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "archived": true, "comments": [{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": null, "parent_id": 123, "text": null, "updated_at": "2016-12-31T12:30:00Z" }], "completed_at_override": "2016-12-31T12:30:00Z", "created_at": "2016-12-31T12:30:00Z", "custom_fields": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_id": 123, "estimate": 123, "external_id": null, "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "linked_file_ids": [123], "move_to": "first", "name": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "requested_by_id": "12345678-9012-3456-7890-123456789012", "source_task_id": 123, "started_at_override": "2016-12-31T12:30:00Z", "story_links": [{ "object_id": 123, "subject_id": 123, "verb": "blocks" }], "story_template_id": "12345678-9012-3456-7890-123456789012", "story_type": "bug", "tasks": [{ "complete": true, "created_at": "2016-12-31T12:30:00Z", "description": null, "external_id": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "updated_at": "2016-12-31T12:30:00Z" }], "updated_at": "2016-12-31T12:30:00Z", "workflow_state_id": 123 }' \
-L "https://api.app.shortcut.com/api/v3/stories"
Example Response
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"branches": [{
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"id": 123,
"merged_branch_ids": [123],
"name": "foo",
"persistent": true,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"repository_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}],
"commits": [{
"author_email": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"author_identity": {
"entity_type": "foo",
"name": "foo",
"type": "bitbucket"
},
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"hash": "foo",
"id": 123,
"message": "foo",
"repository_id": 123,
"timestamp": "2016-12-31T12:30:00Z",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"tasks": [{
"complete": true,
"completed_at": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"story_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
Body Parameters
Name | Description |
---|---|
archived Boolean | Controls the story’s archived state. |
comments Array [CreateStoryCommentParams] | An array of comments to add to the story. |
completed_at_override Date | A manual override for the time/date the Story was completed. |
created_at Date | The time/date the Story was created. |
custom_fields Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
deadline Date or null | The due date of the story. |
description String (100000) | The description of the story. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_id String (1024) | 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. |
external_links Array [String] | An array of External Links associated with this story. |
file_ids Array [Integer] | An array of IDs of files attached to the story. |
follower_ids Array [UUID] | An array of UUIDs of the followers of this story. |
group_id UUID or null | The id of the group to associate with this story. |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
labels Array [CreateLabelParams] | An array of labels attached to the story. |
linked_file_ids Array [Integer] | An array of IDs of linked files attached to the story. |
move_to Enum (first, last) | One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state. |
name String (512) | Required. The name of the story. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
project_id Integer or null | The ID of the project the story belongs to. |
requested_by_id UUID | The ID of the member that requested the story. |
source_task_id Integer or null | Given this story was converted from a task in another story, this is the original task ID that was converted to this story. |
started_at_override Date | A manual override for the time/date the Story was started. |
story_links Array [CreateStoryLinkParams] | An array of story links attached to the story. |
story_template_id UUID or null | 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. |
story_type Enum (bug, chore, feature) | The type of story (feature, bug, chore). |
tasks Array [CreateTaskParams] | An array of tasks connected to the story. |
updated_at Date | The time/date the Story was updated. |
workflow_state_id Integer | The ID of the workflow state the story will be in. |
Responses
Code | Description |
---|---|
201 | Story |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Multiple Stories
Create Multiple Stories allows you to create multiple stories in a single request using the same syntax as Create Story.
Definition
POST https://api.app.shortcut.com/api/v3/stories/bulk
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "stories": [{ "archived": true, "comments": [{
"author_id": "12345678-9012-3456-7890-123456789012",
"created_at": "2016-12-31T12:30:00Z",
"external_id": null,
"parent_id": 123,
"text": null,
"updated_at": "2016-12-31T12:30:00Z"
}], "completed_at_override": "2016-12-31T12:30:00Z", "created_at": "2016-12-31T12:30:00Z", "custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}], "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_id": 123, "estimate": 123, "external_id": null, "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{
"color": "#6515dd",
"description": null,
"external_id": null,
"name": null
}], "linked_file_ids": [123], "move_to": "first", "name": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "requested_by_id": "12345678-9012-3456-7890-123456789012", "source_task_id": 123, "started_at_override": "2016-12-31T12:30:00Z", "story_links": [{
"object_id": 123,
"subject_id": 123,
"verb": "blocks"
}], "story_template_id": "12345678-9012-3456-7890-123456789012", "story_type": "bug", "tasks": [{
"complete": true,
"created_at": "2016-12-31T12:30:00Z",
"description": null,
"external_id": null,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"updated_at": "2016-12-31T12:30:00Z"
}], "updated_at": "2016-12-31T12:30:00Z", "workflow_state_id": 123 }] }' \
-L "https://api.app.shortcut.com/api/v3/stories/bulk"
Example Response
[
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"comment_ids": [123],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
]
Body Parameters
Name | Description |
---|---|
stories Array [CreateStoryParams] | Required. An array of stories to be created. |
Responses
Code | Description |
---|---|
201 | [ StorySlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Multiple Stories
Update Multiple Stories allows you to make changes to numerous stories at once.
Definition
PUT https://api.app.shortcut.com/api/v3/stories/bulk
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "after_id": 123, "archived": true, "before_id": 123, "custom_fields_add": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "custom_fields_remove": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "epic_id": 123, "estimate": 123, "external_links": [], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels_add": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "labels_remove": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "move_to": "first", "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "requested_by_id": "12345678-9012-3456-7890-123456789012", "story_ids": [123], "story_type": "bug", "workflow_state_id": 123 }' \
-L "https://api.app.shortcut.com/api/v3/stories/bulk"
Example Response
[
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"comment_ids": [123],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
]
Body Parameters
Name | Description |
---|---|
after_id Integer | The ID of the story that the stories are to be moved below. |
archived Boolean | If the Stories should be archived or not. |
before_id Integer | The ID of the story that the stories are to be moved before. |
custom_fields_add Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
custom_fields_remove Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
deadline Date or null | The due date of the story. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_links Array [String] | An array of External Links associated with this story. |
follower_ids_add Array [UUID] | The UUIDs of the new followers to be added. |
follower_ids_remove Array [UUID] | The UUIDs of the followers to be removed. |
group_id UUID or null | The Id of the Group the Stories should belong to. |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
labels_add Array [CreateLabelParams] | An array of labels to be added. |
labels_remove Array [CreateLabelParams] | An array of labels to be removed. |
move_to Enum (first, last) | One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state. |
owner_ids_add Array [UUID] | The UUIDs of the new owners to be added. |
owner_ids_remove Array [UUID] | The UUIDs of the owners to be removed. |
project_id Integer or null | The ID of the Project the Stories should belong to. |
requested_by_id UUID | The ID of the member that requested the story. |
story_ids Array [Integer] | Required. The Ids of the Stories you wish to update. |
story_type Enum (bug, chore, feature) | The type of story (feature, bug, chore). |
workflow_state_id Integer | The ID of the workflow state to put the stories in. |
Responses
Code | Description |
---|---|
200 | [ StorySlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Multiple Stories
Delete Multiple Stories allows you to delete multiple archived stories at once.
Definition
DELETE https://api.app.shortcut.com/api/v3/stories/bulk
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "story_ids": [123] }' \
-L "https://api.app.shortcut.com/api/v3/stories/bulk"
Body Parameters
Name | Description |
---|---|
story_ids Array [Integer] | Required. An array of IDs of Stories to delete. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Story From Template
Create Story From Template is used to add a new story derived from a template to your Shortcut Workspace.
Definition
POST https://api.app.shortcut.com/api/v3/stories/from-template
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "archived": true, "comments": [{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": null, "parent_id": 123, "text": null, "updated_at": "2016-12-31T12:30:00Z" }], "completed_at_override": "2016-12-31T12:30:00Z", "created_at": "2016-12-31T12:30:00Z", "custom_fields": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "custom_fields_add": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "custom_fields_remove": [{ "field_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_id": 123, "estimate": 123, "external_id": null, "external_links": [], "external_links_add": [], "external_links_remove": [], "file_ids": [123], "file_ids_add": [123], "file_ids_remove": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "labels_add": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "labels_remove": [{ "name": null }], "linked_file_ids": [123], "linked_file_ids_add": [123], "linked_file_ids_remove": [123], "move_to": "first", "name": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "requested_by_id": "12345678-9012-3456-7890-123456789012", "source_task_id": 123, "started_at_override": "2016-12-31T12:30:00Z", "story_links": [{ "object_id": 123, "subject_id": 123, "verb": "blocks" }], "story_template_id": "12345678-9012-3456-7890-123456789012", "story_type": "bug", "tasks": [{ "complete": true, "created_at": "2016-12-31T12:30:00Z", "description": null, "external_id": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "updated_at": "2016-12-31T12:30:00Z" }], "updated_at": "2016-12-31T12:30:00Z", "workflow_state_id": 123 }' \
-L "https://api.app.shortcut.com/api/v3/stories/from-template"
Example Response
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"branches": [{
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"id": 123,
"merged_branch_ids": [123],
"name": "foo",
"persistent": true,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"repository_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}],
"commits": [{
"author_email": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"author_identity": {
"entity_type": "foo",
"name": "foo",
"type": "bitbucket"
},
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"hash": "foo",
"id": 123,
"message": "foo",
"repository_id": 123,
"timestamp": "2016-12-31T12:30:00Z",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"tasks": [{
"complete": true,
"completed_at": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"story_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
Body Parameters
Name | Description |
---|---|
archived Boolean | Controls the story’s archived state. |
comments Array [CreateStoryCommentParams] | An array of comments to add to the story. |
completed_at_override Date | A manual override for the time/date the Story was completed. |
created_at Date | The time/date the Story was created. |
custom_fields Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
custom_fields_add Array [CustomFieldValueParams] | 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 . |
custom_fields_remove Array [RemoveCustomFieldParams] | 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 . |
deadline Date or null | The due date of the story. |
description String (100000) | The description of the story. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_id String (1024) | 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. |
external_links Array [String] | An array of External Links associated with this story. |
external_links_add Array [String] | 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 . |
external_links_remove Array [String] | 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 . |
file_ids Array [Integer] | An array of IDs of files attached to the story. |
file_ids_add Array [Integer] | 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 . |
file_ids_remove Array [Integer] | An array of IDs of files removed from files from the template. Cannot be used in conjunction with file_ids . |
follower_ids Array [UUID] | An array of UUIDs of the followers of this story. |
follower_ids_add Array [UUID] | The UUIDs of the new followers to be added in addition to followers from the template. Cannot be used in conjunction with follower_ids. |
follower_ids_remove Array [UUID] | The UUIDs of the new followers to be removed from followers from the template. Cannot be used in conjunction with follower_ids . |
group_id UUID or null | The id of the group to associate with this story. |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
labels Array [CreateLabelParams] | An array of labels attached to the story. |
labels_add Array [CreateLabelParams] | An array of labels attached to the story in addition to the labels provided by the template. Cannot be used in conjunction with labels . |
labels_remove Array [RemoveLabelParams] | An array of labels to remove from the labels provided by the template. Cannot be used in conjunction with labels . |
linked_file_ids Array [Integer] | An array of IDs of linked files attached to the story. |
linked_file_ids_add Array [Integer] | 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 . |
linked_file_ids_remove Array [Integer] | An array of IDs of linked files removed from files from the template. Cannot be used in conjunction with linked_files. |
move_to Enum (first, last) | One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state. |
name String (512) | The name of the story. Must be provided if the template does not provide a name. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
owner_ids_add Array [UUID] | The UUIDs of the new owners to be added in addition to owners from the template. Cannot be used in conjunction with owners . |
owner_ids_remove Array [UUID] | The UUIDs of the new owners to be removed from owners from the template. Cannot be used in conjunction with owners . |
project_id Integer or null | The ID of the project the story belongs to. |
requested_by_id UUID | The ID of the member that requested the story. |
source_task_id Integer or null | Given this story was converted from a task in another story, this is the original task ID that was converted to this story. |
started_at_override Date | A manual override for the time/date the Story was started. |
story_links Array [CreateStoryLinkParams] | An array of story links attached to the story. |
story_template_id UUID | Required. The id of the story template used to create this story. |
story_type Enum (bug, chore, feature) | The type of story (feature, bug, chore). |
tasks Array [CreateTaskParams] | An array of tasks connected to the story. |
updated_at Date | The time/date the Story was updated. |
workflow_state_id Integer | The ID of the workflow state the story will be in. |
Responses
Code | Description |
---|---|
201 | Story |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Search Stories (Old)
Search Stories lets you search Stories based on desired parameters.
Definition
POST https://api.app.shortcut.com/api/v3/stories/search
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "archived": true, "completed_at_end": "2016-12-31T12:30:00Z", "completed_at_start": "2016-12-31T12:30:00Z", "created_at_end": "2016-12-31T12:30:00Z", "created_at_start": "2016-12-31T12:30:00Z", "deadline_end": "2016-12-31T12:30:00Z", "deadline_start": "2016-12-31T12:30:00Z", "epic_id": 123, "epic_ids": [123], "estimate": 123, "external_id": null, "group_id": "12345678-9012-3456-7890-123456789012", "group_ids": ["12345678-9012-3456-7890-123456789012"], "includes_description": true, "iteration_id": 123, "iteration_ids": [123], "label_ids": [123], "label_name": "foo", "owner_id": "12345678-9012-3456-7890-123456789012", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "project_ids": [123], "requested_by_id": "12345678-9012-3456-7890-123456789012", "story_type": "bug", "updated_at_end": "2016-12-31T12:30:00Z", "updated_at_start": "2016-12-31T12:30:00Z", "workflow_state_id": 123, "workflow_state_types": ["backlog"] }' \
-L "https://api.app.shortcut.com/api/v3/stories/search"
Example Response
[
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"comment_ids": [123],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"file_ids": [123],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_file_ids": [123],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"num_tasks_completed": 123,
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"task_ids": [123],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
]
Body Parameters
Name | Description |
---|---|
archived Boolean | A true/false boolean indicating whether the Story is in archived state. |
completed_at_end Date | Stories should have been completed on or before this date. |
completed_at_start Date | Stories should have been completed on or after this date. |
created_at_end Date | Stories should have been created on or before this date. |
created_at_start Date | Stories should have been created on or after this date. |
deadline_end Date | Stories should have a deadline on or before this date. |
deadline_start Date | Stories should have a deadline on or after this date. |
epic_id Integer or null | The Epic IDs that may be associated with the Stories. |
epic_ids Array [Integer] | The Epic IDs that may be associated with the Stories. |
estimate Integer | The number of estimate points associate with the Stories. |
external_id String (1024) | An ID or URL that references an external resource. Useful during imports. |
group_id UUID or null | The Group ID that is associated with the Stories |
group_ids Array [UUID] | The Group IDs that are associated with the Stories |
includes_description Boolean | Whether to include the story description in the response. |
iteration_id Integer or null | The Iteration ID that may be associated with the Stories. |
iteration_ids Array [Integer] | The Iteration IDs that may be associated with the Stories. |
label_ids Array [Integer] | The Label IDs that may be associated with the Stories. |
label_name String | The name of any associated Labels. |
owner_id UUID or null | An array of UUIDs for any Users who may be Owners of the Stories. |
owner_ids Array [UUID] | An array of UUIDs for any Users who may be Owners of the Stories. |
project_id Integer or null | The IDs for the Projects the Stories may be assigned to. |
project_ids Array [Integer or null] | The IDs for the Projects the Stories may be assigned to. |
requested_by_id UUID | The UUID of any Users who may have requested the Stories. |
story_type Enum (bug, chore, feature) | The type of Stories that you want returned. |
updated_at_end Date | Stories should have been updated on or before this date. |
updated_at_start Date | Stories should have been updated on or after this date. |
workflow_state_id Integer | The unique IDs of the specific Workflow States that the Stories should be in. |
workflow_state_types Array [Enum (backlog, done, started, unstarted)] | The type of Workflow State the Stories may be in. |
Responses
Code | Description |
---|---|
201 | [ StorySlim, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Story
Get Story returns information about a chosen Story.
Definition
GET https://api.app.shortcut.com/api/v3/stories/{story-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"branches": [{
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"id": 123,
"merged_branch_ids": [123],
"name": "foo",
"persistent": true,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"repository_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}],
"commits": [{
"author_email": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"author_identity": {
"entity_type": "foo",
"name": "foo",
"type": "bitbucket"
},
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"hash": "foo",
"id": 123,
"message": "foo",
"repository_id": 123,
"timestamp": "2016-12-31T12:30:00Z",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"tasks": [{
"complete": true,
"completed_at": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"story_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story. |
Responses
Code | Description |
---|---|
200 | Story |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Story
Update Story can be used to update Story properties.
Definition
PUT https://api.app.shortcut.com/api/v3/stories/{story-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "after_id": 123, "archived": true, "before_id": 123, "branch_ids": [123], "commit_ids": [123], "completed_at_override": "2016-12-31T12:30:00Z", "custom_fields": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_id": 123, "estimate": 123, "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "linked_file_ids": [123], "move_to": "first", "name": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "pull_request_ids": [123], "requested_by_id": "12345678-9012-3456-7890-123456789012", "started_at_override": "2016-12-31T12:30:00Z", "story_type": "bug", "workflow_state_id": 123 }' \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}"
Example Response
{
"app_url": "foo",
"archived": true,
"blocked": true,
"blocker": true,
"branches": [{
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"id": 123,
"merged_branch_ids": [123],
"name": "foo",
"persistent": true,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"repository_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"comments": [{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}],
"commits": [{
"author_email": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"author_identity": {
"entity_type": "foo",
"name": "foo",
"type": "bitbucket"
},
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"hash": "foo",
"id": 123,
"message": "foo",
"repository_id": 123,
"timestamp": "2016-12-31T12:30:00Z",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo"
}],
"completed": true,
"completed_at": "2016-12-31T12:30:00Z",
"completed_at_override": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"custom_fields": [{
"field_id": "12345678-9012-3456-7890-123456789012",
"value": "foo",
"value_id": "12345678-9012-3456-7890-123456789012"
}],
"cycle_time": 123,
"deadline": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"epic_id": 123,
"estimate": 123,
"external_id": "foo",
"external_links": [],
"files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"filename": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"follower_ids": ["12345678-9012-3456-7890-123456789012"],
"group_id": "12345678-9012-3456-7890-123456789012",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"iteration_id": 123,
"label_ids": [123],
"labels": [{
"app_url": "foo",
"archived": true,
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"id": 123,
"name": "foo",
"updated_at": "2016-12-31T12:30:00Z"
}],
"lead_time": 123,
"linked_files": [{
"content_type": "foo",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"name": "foo",
"size": 123,
"story_ids": [123],
"thumbnail_url": "foo",
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"uploader_id": "12345678-9012-3456-7890-123456789012",
"url": "foo"
}],
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"moved_at": "2016-12-31T12:30:00Z",
"name": "foo",
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"previous_iteration_ids": [123],
"project_id": 123,
"pull_requests": [{
"branch_id": 123,
"branch_name": "foo",
"build_status": "foo",
"closed": true,
"created_at": "2016-12-31T12:30:00Z",
"draft": true,
"entity_type": "foo",
"has_overlapping_stories": true,
"id": 123,
"merged": true,
"num_added": 123,
"num_commits": 123,
"num_modified": 123,
"num_removed": 123,
"number": 123,
"overlapping_stories": [123],
"repository_id": 123,
"review_status": "foo",
"target_branch_id": 123,
"target_branch_name": "foo",
"title": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"url": "foo",
"vcs_labels": [{
"color": "#6515dd",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo"
}]
}],
"requested_by_id": "12345678-9012-3456-7890-123456789012",
"started": true,
"started_at": "2016-12-31T12:30:00Z",
"started_at_override": "2016-12-31T12:30:00Z",
"stats": {
"num_related_documents": 123
},
"story_links": [{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"story_template_id": "12345678-9012-3456-7890-123456789012",
"story_type": "foo",
"synced_item": {
"external_id": "foo",
"url": "foo"
},
"tasks": [{
"complete": true,
"completed_at": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"story_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}],
"unresolved_blocker_comments": [123],
"updated_at": "2016-12-31T12:30:00Z",
"workflow_id": 123,
"workflow_state_id": 123
}
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The unique identifier of this story. |
Body Parameters
Name | Description |
---|---|
after_id Integer | The ID of the story we want to move this story after. |
archived Boolean | True if the story is archived, otherwise false. |
before_id Integer | The ID of the story we want to move this story before. |
branch_ids Array [Integer] | An array of IDs of Branches attached to the story. |
commit_ids Array [Integer] | An array of IDs of Commits attached to the story. |
completed_at_override Date or null | A manual override for the time/date the Story was completed. |
custom_fields Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
deadline Date or null | The due date of the story. |
description String (100000) | The description of the story. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_links Array [String] | An array of External Links associated with this story. |
file_ids Array [Integer] | An array of IDs of files attached to the story. |
follower_ids Array [UUID] | An array of UUIDs of the followers of this story. |
group_id UUID or null | The ID of the group to associate with this story |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
labels Array [CreateLabelParams] | An array of labels attached to the story. |
linked_file_ids Array [Integer] | An array of IDs of linked files attached to the story. |
move_to Enum (first, last) | One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state. |
name String (512) | The title of the story. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
project_id Integer or null | The ID of the project the story belongs to. |
pull_request_ids Array [Integer] | An array of IDs of Pull/Merge Requests attached to the story. |
requested_by_id UUID | The ID of the member that requested the story. |
started_at_override Date or null | A manual override for the time/date the Story was started. |
story_type Enum (bug, chore, feature) | The type of story (feature, bug, chore). |
workflow_state_id Integer | The ID of the workflow state to put the story in. |
Responses
Code | Description |
---|---|
200 | Story |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Story
Delete Story can be used to delete any Story.
Definition
DELETE https://api.app.shortcut.com/api/v3/stories/{story-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}"
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
List Story Comment
Lists Comments associated with a Story
Definition
GET https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments"
Example Response
[
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}
]
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story that the Comment is in. |
Responses
Code | Description |
---|---|
200 | [ StoryComment, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Story Comment
Create Comment allows you to create a Comment on any Story.
Definition
POST https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": null, "parent_id": 123, "text": null, "updated_at": "2016-12-31T12:30:00Z" }' \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments"
Example Response
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story that the Comment is in. |
Body Parameters
Name | Description |
---|---|
author_id UUID | The Member ID of the Comment’s author. Defaults to the user identified by the API token. |
created_at Date | Defaults to the time/date the comment is created, but can be set to reflect another date. |
external_id String (1024) | 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. |
parent_id Integer or null | The ID of the Comment that this comment is threaded under. |
text String (100000) | Required. The comment text. |
updated_at Date | Defaults to the time/date the comment is last updated, but can be set to reflect another date. |
Responses
Code | Description |
---|---|
201 | StoryComment |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Story Comment
Get Comment is used to get Comment information.
Definition
GET https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}"
Example Response
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story that the Comment is in. |
comment-public-id Integer | Required. The ID of the Comment. |
Responses
Code | Description |
---|---|
200 | StoryComment |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Story Comment
Update Comment replaces the text of the existing Comment.
Definition
PUT https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "text": null }' \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}"
Example Response
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story that the Comment is in. |
comment-public-id Integer | Required. The ID of the Comment |
Body Parameters
Name | Description |
---|---|
text String (100000) | Required. The updated comment text. |
Responses
Code | Description |
---|---|
200 | StoryComment |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Story Comment
Delete a Comment from any story.
Definition
DELETE https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}"
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story that the Comment is in. |
comment-public-id Integer | Required. The ID of the Comment. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Story Reaction
Create a reaction to a story comment.
Definition
POST https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "emoji": "foo" }' \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions"
Example Response
[
{
"emoji": "foo",
"permission_ids": ["12345678-9012-3456-7890-123456789012"]
}
]
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story that the Comment is in. |
comment-public-id Integer | Required. The ID of the Comment. |
Body Parameters
Name | Description |
---|---|
emoji String | Required. The emoji short-code to add / remove. E.g. :thumbsup::skin-tone-4: . |
Responses
Code | Description |
---|---|
201 | [ StoryReaction, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Story Reaction
Delete a reaction from any story comment.
Definition
DELETE https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "emoji": "foo" }' \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions"
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story that the Comment is in. |
comment-public-id Integer | Required. The ID of the Comment. |
Body Parameters
Name | Description |
---|---|
emoji String | Required. The emoji short-code to add / remove. E.g. :thumbsup::skin-tone-4: . |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Unlink Comment thread from Slack
Unlinks a Comment from its linked Slack thread (Comment replies and Slack replies will no longer be synced)
Definition
POST https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/unlink-from-slack
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/unlink-from-slack"
Example Response
{
"app_url": "foo",
"author_id": "12345678-9012-3456-7890-123456789012",
"blocker": true,
"created_at": "2016-12-31T12:30:00Z",
"deleted": true,
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"linked_to_slack": true,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"parent_id": 123,
"position": 123,
"story_id": 123,
"text": "foo",
"unblocks_parent": true,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story to unlink. |
comment-public-id Integer | Required. The ID of the Comment to unlink. |
Responses
Code | Description |
---|---|
201 | StoryComment |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Story History
Definition
GET https://api.app.shortcut.com/api/v3/stories/{story-public-id}/history
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/history"
Example Response
[
{
"actions": [],
"automation_id": "12345678-9012-3456-7890-123456789012",
"changed_at": "foo",
"external_id": "foo",
"id": "12345678-9012-3456-7890-123456789012",
"member_id": "12345678-9012-3456-7890-123456789012",
"primary_id": null,
"references": [],
"version": "v1",
"webhook_id": "foo"
}
]
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story. |
Responses
Code | Description |
---|---|
200 | [ History, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Create Task
Create Task is used to create a new task in a Story.
Definition
POST https://api.app.shortcut.com/api/v3/stories/{story-public-id}/tasks
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "complete": true, "created_at": "2016-12-31T12:30:00Z", "description": null, "external_id": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "updated_at": "2016-12-31T12:30:00Z" }' \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/tasks"
Example Response
{
"complete": true,
"completed_at": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"story_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The ID of the Story that the Task will be in. |
Body Parameters
Name | Description |
---|---|
complete Boolean | True/false boolean indicating whether the Task is completed. Defaults to false. |
created_at Date | Defaults to the time/date the Task is created but can be set to reflect another creation time/date. |
description String (2048) | Required. The Task description. |
external_id String (128) | 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. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Task. |
updated_at Date | Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date. |
Responses
Code | Description |
---|---|
201 | Task |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Task
Returns information about a chosen Task.
Definition
GET https://api.app.shortcut.com/api/v3/stories/{story-public-id}/tasks/{task-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/tasks/{task-public-id}"
Example Response
{
"complete": true,
"completed_at": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"story_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The unique ID of the Story this Task is associated with. |
task-public-id Integer | Required. The unique ID of the Task. |
Responses
Code | Description |
---|---|
200 | Task |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Task
Update Task can be used to update Task properties.
Definition
PUT https://api.app.shortcut.com/api/v3/stories/{story-public-id}/tasks/{task-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "after_id": 123, "before_id": 123, "complete": true, "description": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"] }' \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/tasks/{task-public-id}"
Example Response
{
"complete": true,
"completed_at": "2016-12-31T12:30:00Z",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"external_id": "foo",
"group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"id": 123,
"member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
"mention_ids": ["12345678-9012-3456-7890-123456789012"],
"owner_ids": ["12345678-9012-3456-7890-123456789012"],
"position": 123,
"story_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The unique identifier of the parent Story. |
task-public-id Integer | Required. The unique identifier of the Task you wish to update. |
Body Parameters
Name | Description |
---|---|
after_id Integer | Move task after this task ID. |
before_id Integer | Move task before this task ID. |
complete Boolean | A true/false boolean indicating whether the task is complete. |
description String (2048) | The Task’s description. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
Responses
Code | Description |
---|---|
200 | Task |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Task
Delete Task can be used to delete any previously created Task on a Story.
Definition
DELETE https://api.app.shortcut.com/api/v3/stories/{story-public-id}/tasks/{task-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/tasks/{task-public-id}"
URL Parameters
Name | Description |
---|---|
story-public-id Integer | Required. The unique ID of the Story this Task is associated with. |
task-public-id Integer | Required. The unique ID of the Task. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Story-Links
Create Story Link
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.
The subject story acts on the object Story; the object story is the direct object of the sentence.
The subject story “blocks”, “duplicates”, or “relates to” the object story. Examples:
- “story 5 blocks story 6” – story 6 is now “blocked” until story 5 is moved to a Done workflow state.
- “story 2 duplicates story 1” – Story 2 represents the same body of work as Story 1 (and should probably be archived).
- “story 7 relates to story 3”
Definition
POST https://api.app.shortcut.com/api/v3/story-links
Example Request
curl -X POST \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "object_id": 123, "subject_id": 123, "verb": "blocks" }' \
-L "https://api.app.shortcut.com/api/v3/story-links"
Example Response
{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}
Body Parameters
Name | Description |
---|---|
object_id Integer | Required. The ID of the object Story. |
subject_id Integer | Required. The ID of the subject Story. |
verb Enum (blocks, duplicates, relates to) | Required. The type of link. |
Responses
Code | Description |
---|---|
201 | StoryLink |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Story Link
Returns the stories and their relationship for the given Story Link.
Definition
GET https://api.app.shortcut.com/api/v3/story-links/{story-link-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/story-links/{story-link-public-id}"
Example Response
{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}
URL Parameters
Name | Description |
---|---|
story-link-public-id Integer | Required. The unique ID of the Story Link. |
Responses
Code | Description |
---|---|
200 | StoryLink |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Update Story Link
Updates the stories and/or the relationship for the given Story Link.
Definition
PUT https://api.app.shortcut.com/api/v3/story-links/{story-link-public-id}
Example Request
curl -X PUT \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-d '{ "object_id": 123, "subject_id": 123, "verb": "blocks" }' \
-L "https://api.app.shortcut.com/api/v3/story-links/{story-link-public-id}"
Example Response
{
"created_at": "2016-12-31T12:30:00Z",
"entity_type": "foo",
"id": 123,
"object_id": 123,
"subject_id": 123,
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}
URL Parameters
Name | Description |
---|---|
story-link-public-id Integer | Required. The unique ID of the Story Link. |
Body Parameters
Name | Description |
---|---|
object_id Integer | The ID of the object Story. |
subject_id Integer | The ID of the subject Story. |
verb Enum (blocks, duplicates, relates to) | The type of link. |
Responses
Code | Description |
---|---|
200 | StoryLink |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Delete Story Link
Removes the relationship between the stories for the given Story Link.
Definition
DELETE https://api.app.shortcut.com/api/v3/story-links/{story-link-public-id}
Example Request
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/story-links/{story-link-public-id}"
URL Parameters
Name | Description |
---|---|
story-link-public-id Integer | Required. The unique ID of the Story Link. |
Responses
Code | Description |
---|---|
204 | No Content |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Workflows
List Workflows
Returns a list of all Workflows in the Workspace.
Definition
GET https://api.app.shortcut.com/api/v3/workflows
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/workflows"
Example Response
[
{
"auto_assign_owner": true,
"created_at": "2016-12-31T12:30:00Z",
"default_state_id": 123,
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo",
"project_ids": [123],
"states": [{
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo",
"num_stories": 123,
"num_story_templates": 123,
"position": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"team_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
]
Responses
Code | Description |
---|---|
200 | [ Workflow, … ] |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Get Workflow
Get Workflow returns information about a chosen Workflow.
Definition
GET https://api.app.shortcut.com/api/v3/workflows/{workflow-public-id}
Example Request
curl -X GET \
-H "Content-Type: application/json" \
-H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
-L "https://api.app.shortcut.com/api/v3/workflows/{workflow-public-id}"
Example Response
{
"auto_assign_owner": true,
"created_at": "2016-12-31T12:30:00Z",
"default_state_id": 123,
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo",
"project_ids": [123],
"states": [{
"color": "#6515dd",
"created_at": "2016-12-31T12:30:00Z",
"description": "foo",
"entity_type": "foo",
"id": 123,
"name": "foo",
"num_stories": 123,
"num_story_templates": 123,
"position": 123,
"type": "foo",
"updated_at": "2016-12-31T12:30:00Z",
"verb": "foo"
}],
"team_id": 123,
"updated_at": "2016-12-31T12:30:00Z"
}
URL Parameters
Name | Description |
---|---|
workflow-public-id Integer | Required. The ID of the Workflow. |
Responses
Code | Description |
---|---|
200 | Workflow |
400 | Schema mismatch |
404 | Resource does not exist |
422 | Unprocessable |
Resources
What follows are resource (or schema) definitions for everything referenced in the above endpoints.
BaseTaskParams
Request parameters for specifying how to pre-populate a task through a template.
Name | Description |
---|---|
complete Boolean | True/false boolean indicating whether the Task is completed. Defaults to false. |
description String (2048) | The Task description. |
external_id String (128) | 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. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Task. |
BasicWorkspaceInfo
Name | Description |
---|---|
estimate_scale Array [Integer] | |
url_slug String |
Branch
Branch refers to a VCS branch. Branches are feature branches associated with Shortcut Stories.
Name | Description |
---|---|
created_at Date or null | The time/date the Branch was created. |
deleted Boolean | A true/false boolean indicating if the Branch has been deleted. |
entity_type String | A string description of this resource. |
id Integer or null | The unique ID of the Branch. |
merged_branch_ids Array [Integer] | The IDs of the Branches the Branch has been merged into. |
name String | The name of the Branch. |
persistent Boolean | A true/false boolean indicating if the Branch is persistent; e.g. master. |
pull_requests Array [PullRequest] | An array of PullRequests attached to the Branch (there is usually only one). |
repository_id Integer | The ID of the Repository that contains the Branch. |
updated_at Date or null | The time/date the Branch was updated. |
url String | The URL of the Branch. |
Category
A Category can be used to associate Objectives.
Name | Description |
---|---|
archived Boolean | A true/false boolean indicating if the Category has been archived. |
color Color or null | The hex color to be displayed with the Category (for example, “#ff0000”). |
created_at Date | The time/date that the Category was created. |
entity_type String | A string description of this resource. |
external_id String or null | 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. |
id Integer | The unique ID of the Category. |
name String | The name of the Category. |
updated_at Date | The time/date that the Category was updated. |
Commit
Commit refers to a VCS commit and all associated details.
Name | Description |
---|---|
author_email String | The email address of the VCS user that authored the Commit. |
author_id UUID or null | The ID of the Member that authored the Commit, if known. |
author_identity Identity | The Identity of the VCS user that authored the Commit. |
created_at Date | The time/date the Commit was created. |
entity_type String | A string description of this resource. |
hash String | The Commit hash. |
id Integer or null | The unique ID of the Commit. |
message String | The Commit message. |
repository_id Integer or null | The ID of the Repository that contains the Commit. |
timestamp Date | The time/date the Commit was pushed. |
updated_at Date or null | The time/date the Commit was updated. |
url String | The URL of the Commit. |
CreateCategory
Name | Description |
---|---|
color Color | The hex color to be displayed with the Category (for example, “#ff0000”). |
external_id String (128) | 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. |
name String (128) | The name of the new Category. |
CreateCategoryParams
Request parameters for creating a Category with a Objective.
Name | Description |
---|---|
color Color | The hex color to be displayed with the Category (for example, “#ff0000”). |
external_id String (128) | 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. |
name String (128) | The name of the new Category. |
CreateCommentComment
Name | Description |
---|---|
author_id UUID | The Member ID of the Comment’s author. Defaults to the user identified by the API token. |
created_at Date | Defaults to the time/date the comment is created, but can be set to reflect another date. |
external_id String (128) | 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. |
text String (100000) | The comment text. |
updated_at Date | Defaults to the time/date the comment is last updated, but can be set to reflect another date. |
CreateEntityTemplate
Request parameters for creating an entirely new entity template.
Name | Description |
---|---|
author_id UUID | The id of the user creating this template. |
name String (128) | The name of the new entity template |
story_contents CreateStoryContents | A map of story attributes this template populates. |
CreateEpic
Name | Description |
---|---|
completed_at_override Date | A manual override for the time/date the Epic was completed. |
created_at Date | Defaults to the time/date it is created but can be set to reflect another date. |
deadline Date or null | The Epic’s deadline. |
description String (100000) | The Epic’s description. |
epic_state_id Integer | The ID of the Epic State. |
external_id String (128) | This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers on this new Epic. |
group_id UUID or null | Deprecated The ID of the group to associate with the epic. Use group_ids . |
group_ids Array [UUID] | An array of UUIDS for Groups to which this Epic is related. |
labels Array [CreateLabelParams] | An array of Labels attached to the Epic. |
milestone_id Integer or null | Deprecated The ID of the Milestone this Epic is related to. Use objective_ids . |
name String (256) | The Epic’s name. |
objective_ids Array [Integer] | An array of IDs for Objectives to which this Epic is related. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Epic. |
planned_start_date Date or null | The Epic’s planned start date. |
requested_by_id UUID | The ID of the member that requested the epic. |
started_at_override Date | A manual override for the time/date the Epic was started. |
state Enum (done, in progress, to do) | Deprecated The Epic’s state (to do, in progress, or done); will be ignored when epic_state_id is set. |
updated_at Date | Defaults to the time/date it is created but can be set to reflect another date. |
CreateEpicComment
Name | Description |
---|---|
author_id UUID | The Member ID of the Comment’s author. Defaults to the user identified by the API token. |
created_at Date | Defaults to the time/date the comment is created, but can be set to reflect another date. |
external_id String (128) | 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. |
text String (100000) | The comment text. |
updated_at Date | Defaults to the time/date the comment is last updated, but can be set to reflect another date. |
CreateGroup
Name | Description |
---|---|
color Color | The color you wish to use for the Group in the system. |
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) | The color key you wish to use for the Group in the system. |
description String (4096) | The description of the Group. |
display_icon_id UUID | The Icon id for the avatar of this Group. |
member_ids Array [UUID] | The Member ids to add to this Group. |
mention_name String (63) | The mention name of this Group. |
name String (63) | The name of this Group. |
workflow_ids Array [Integer] | The Workflow ids to add to the Group. |
CreateIteration
Name | Description |
---|---|
description String (100000) | The description of the Iteration. |
end_date String | The date this Iteration ends, e.g. 2019-07-01. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers. |
group_ids Array [UUID] | An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI. |
labels Array [CreateLabelParams] | An array of Labels attached to the Iteration. |
name String (256) | The name of this Iteration. |
start_date String | The date this Iteration begins, e.g. 2019-07-01. |
CreateLabelParams
Request parameters for creating a Label on a Shortcut Story.
Name | Description |
---|---|
color Color | The hex color to be displayed with the Label (for example, “#ff0000”). |
description String (1024) | The description of the new Label. |
external_id String (128) | 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. |
name String (128) | The name of the new Label. |
CreateLinkedFile
Name | Description |
---|---|
content_type String (128) | The content type of the image (e.g. txt/plain). |
description String (512) | The description of the file. |
name String (256) | The name of the file. |
size Integer | The filesize, if the integration provided it. |
story_id Integer | The ID of the linked story. |
thumbnail_url String (2048) | The URL of the thumbnail, if the integration provided it. |
type Enum (box, dropbox, google, onedrive, url) | The integration type of the file (e.g. google, dropbox, box). |
uploader_id UUID | The UUID of the member that uploaded the file. |
url String (2048) | The URL of linked file. |
CreateMilestone
Name | Description |
---|---|
categories Array [CreateCategoryParams] | An array of IDs of Categories attached to the Milestone. |
completed_at_override Date | A manual override for the time/date the Milestone was completed. |
description String (100000) | The Milestone’s description. |
name String (256) | The name of the Milestone. |
started_at_override Date | A manual override for the time/date the Milestone was started. |
state Enum (done, in progress, to do) | The workflow state that the Milestone is in. |
CreateObjective
Name | Description |
---|---|
categories Array [CreateCategoryParams] | An array of IDs of Categories attached to the Objective. |
completed_at_override Date | A manual override for the time/date the Objective was completed. |
description String (100000) | The Objective’s description. |
name String (256) | The name of the Objective. |
started_at_override Date | A manual override for the time/date the Objective was started. |
state Enum (done, in progress, to do) | The workflow state that the Objective is in. |
CreateOrDeleteStoryReaction
Name | Description |
---|---|
emoji String | The emoji short-code to add / remove. E.g. :thumbsup::skin-tone-4: . |
CreateProject
Name | Description |
---|---|
abbreviation String (63) | The Project abbreviation used in Story summaries. Should be kept to 3 characters at most. |
color Color | The color you wish to use for the Project in the system. |
created_at Date | Defaults to the time/date it is created but can be set to reflect another date. |
description String (100000) | The Project description. |
external_id String (128) | 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. |
follower_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Epic. |
iteration_length Integer | The number of weeks per iteration in this Project. |
name String (128) | The name of the Project. |
start_time Date | The date at which the Project was started. |
team_id Integer | The ID of the team the project belongs to. |
updated_at Date | Defaults to the time/date it is created but can be set to reflect another date. |
CreateStories
Name | Description |
---|---|
stories Array [CreateStoryParams] | An array of stories to be created. |
CreateStoryComment
Name | Description |
---|---|
author_id UUID | The Member ID of the Comment’s author. Defaults to the user identified by the API token. |
created_at Date | Defaults to the time/date the comment is created, but can be set to reflect another date. |
external_id String (1024) | 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. |
parent_id Integer or null | The ID of the Comment that this comment is threaded under. |
text String (100000) | The comment text. |
updated_at Date | Defaults to the time/date the comment is last updated, but can be set to reflect another date. |
CreateStoryCommentParams
Request parameters for creating a Comment on a Shortcut Story.
Name | Description |
---|---|
author_id UUID | The Member ID of the Comment’s author. Defaults to the user identified by the API token. |
created_at Date | Defaults to the time/date the comment is created, but can be set to reflect another date. |
external_id String (1024) | 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. |
parent_id Integer or null | The ID of the Comment that this comment is threaded under. |
text String (100000) | The comment text. |
updated_at Date | Defaults to the time/date the comment is last updated, but can be set to reflect another date. |
CreateStoryContents
A map of story attributes this template populates.
Name | Description |
---|---|
custom_fields Array [CustomFieldValueParams] | An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
deadline Date or null | The due date of the story. |
description String | The description of the story. |
epic_id Integer or null | The ID of the epic the to be populated. |
estimate Integer or null | The numeric point estimate to be populated. |
external_links Array [String] | An array of external links to be populated. |
file_ids Array [Integer] | An array of the attached file IDs to be populated. |
follower_ids Array [UUID] | An array of UUIDs for any Members listed as Followers. |
group_id UUID or null | The ID of the group to be populated. |
iteration_id Integer or null | The ID of the iteration the to be populated. |
labels Array [CreateLabelParams] | An array of labels to be populated by the template. |
linked_file_ids Array [Integer] | An array of the linked file IDs to be populated. |
name String (512) | The name of the story. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
project_id Integer | The ID of the project the story belongs to. |
story_type String | The type of story (feature, bug, chore). |
tasks Array [BaseTaskParams] | An array of tasks to be populated by the template. |
workflow_state_id Integer or null | The ID of the workflow state to be populated. |
CreateStoryFromTemplateParams
Request parameters for creating a story from a story template. These parameters are merged with the values derived from the template.
Name | Description |
---|---|
archived Boolean | Controls the story’s archived state. |
comments Array [CreateStoryCommentParams] | An array of comments to add to the story. |
completed_at_override Date | A manual override for the time/date the Story was completed. |
created_at Date | The time/date the Story was created. |
custom_fields Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
custom_fields_add Array [CustomFieldValueParams] | 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 . |
custom_fields_remove Array [RemoveCustomFieldParams] | 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 . |
deadline Date or null | The due date of the story. |
description String (100000) | The description of the story. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_id String (1024) | 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. |
external_links Array [String] | An array of External Links associated with this story. |
external_links_add Array [String] | 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 . |
external_links_remove Array [String] | 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 . |
file_ids Array [Integer] | An array of IDs of files attached to the story. |
file_ids_add Array [Integer] | 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 . |
file_ids_remove Array [Integer] | An array of IDs of files removed from files from the template. Cannot be used in conjunction with file_ids . |
follower_ids Array [UUID] | An array of UUIDs of the followers of this story. |
follower_ids_add Array [UUID] | The UUIDs of the new followers to be added in addition to followers from the template. Cannot be used in conjunction with follower_ids. |
follower_ids_remove Array [UUID] | The UUIDs of the new followers to be removed from followers from the template. Cannot be used in conjunction with follower_ids . |
group_id UUID or null | The id of the group to associate with this story. |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
labels Array [CreateLabelParams] | An array of labels attached to the story. |
labels_add Array [CreateLabelParams] | An array of labels attached to the story in addition to the labels provided by the template. Cannot be used in conjunction with labels . |
labels_remove Array [RemoveLabelParams] | An array of labels to remove from the labels provided by the template. Cannot be used in conjunction with labels . |
linked_file_ids Array [Integer] | An array of IDs of linked files attached to the story. |
linked_file_ids_add Array [Integer] | 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 . |
linked_file_ids_remove Array [Integer] | An array of IDs of linked files removed from files from the template. Cannot be used in conjunction with linked_files. |
move_to Enum (first, last) | One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state. |
name String (512) | The name of the story. Must be provided if the template does not provide a name. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
owner_ids_add Array [UUID] | The UUIDs of the new owners to be added in addition to owners from the template. Cannot be used in conjunction with owners . |
owner_ids_remove Array [UUID] | The UUIDs of the new owners to be removed from owners from the template. Cannot be used in conjunction with owners . |
project_id Integer or null | The ID of the project the story belongs to. |
requested_by_id UUID | The ID of the member that requested the story. |
source_task_id Integer or null | Given this story was converted from a task in another story, this is the original task ID that was converted to this story. |
started_at_override Date | A manual override for the time/date the Story was started. |
story_links Array [CreateStoryLinkParams] | An array of story links attached to the story. |
story_template_id UUID | The id of the story template used to create this story. |
story_type Enum (bug, chore, feature) | The type of story (feature, bug, chore). |
tasks Array [CreateTaskParams] | An array of tasks connected to the story. |
updated_at Date | The time/date the Story was updated. |
workflow_state_id Integer | The ID of the workflow state the story will be in. |
CreateStoryLink
Name | Description |
---|---|
object_id Integer | The ID of the object Story. |
subject_id Integer | The ID of the subject Story. |
verb Enum (blocks, duplicates, relates to) | The type of link. |
CreateStoryLinkParams
Request parameters for creating a Story Link within a Story.
Name | Description |
---|---|
object_id Integer | The unique ID of the Story defined as object. |
subject_id Integer | The unique ID of the Story defined as subject. |
verb Enum (blocks, duplicates, relates to) | How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”. |
CreateStoryParams
Request parameters for creating a story.
Name | Description |
---|---|
archived Boolean | Controls the story’s archived state. |
comments Array [CreateStoryCommentParams] | An array of comments to add to the story. |
completed_at_override Date | A manual override for the time/date the Story was completed. |
created_at Date | The time/date the Story was created. |
custom_fields Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
deadline Date or null | The due date of the story. |
description String (100000) | The description of the story. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_id String (1024) | 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. |
external_links Array [String] | An array of External Links associated with this story. |
file_ids Array [Integer] | An array of IDs of files attached to the story. |
follower_ids Array [UUID] | An array of UUIDs of the followers of this story. |
group_id UUID or null | The id of the group to associate with this story. |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
labels Array [CreateLabelParams] | An array of labels attached to the story. |
linked_file_ids Array [Integer] | An array of IDs of linked files attached to the story. |
move_to Enum (first, last) | One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state. |
name String (512) | The name of the story. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
project_id Integer or null | The ID of the project the story belongs to. |
requested_by_id UUID | The ID of the member that requested the story. |
source_task_id Integer or null | Given this story was converted from a task in another story, this is the original task ID that was converted to this story. |
started_at_override Date | A manual override for the time/date the Story was started. |
story_links Array [CreateStoryLinkParams] | An array of story links attached to the story. |
story_template_id UUID or null | 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. |
story_type Enum (bug, chore, feature) | The type of story (feature, bug, chore). |
tasks Array [CreateTaskParams] | An array of tasks connected to the story. |
updated_at Date | The time/date the Story was updated. |
workflow_state_id Integer | The ID of the workflow state the story will be in. |
CreateTask
Name | Description |
---|---|
complete Boolean | True/false boolean indicating whether the Task is completed. Defaults to false. |
created_at Date | Defaults to the time/date the Task is created but can be set to reflect another creation time/date. |
description String (2048) | The Task description. |
external_id String (128) | 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. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Task. |
updated_at Date | Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date. |
CreateTaskParams
Request parameters for creating a Task on a Story.
Name | Description |
---|---|
complete Boolean | True/false boolean indicating whether the Task is completed. Defaults to false. |
created_at Date | Defaults to the time/date the Task is created but can be set to reflect another creation time/date. |
description String (2048) | The Task description. |
external_id String (128) | 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. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Task. |
updated_at Date | Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date. |
CustomField
Name | Description |
---|---|
canonical_name String | The canonical name for a Shortcut-defined field. |
created_at Date | The instant when this CustomField was created. |
description String (512) | A string description of the CustomField |
enabled Boolean | When true, the CustomField can be applied to entities in the Workspace. |
entity_type Enum (custom-field) | A string description of this resource. |
field_type Enum (enum) | The type of Custom Field, eg. ‘enum’. |
icon_set_identifier String (63) | A string that represents the icon that corresponds to this custom field. |
id UUID | The unique public ID for the CustomField. |
name String (63) | The name of the Custom Field. |
position Integer | An integer indicating the position of this Custom Field with respect to the other CustomField |
updated_at Date | The instant when this CustomField was last updated. |
values Array [CustomFieldEnumValue] | A collection of legal values for a CustomField. |
CustomFieldEnumValue
Name | Description |
---|---|
color_key String or null | A color key associated with this CustomFieldEnumValue. |
entity_type Enum (custom-field-enum-value) | A string description of this resource. |
id UUID | The unique public ID for the Custom Field. |
position Integer | An integer indicating the position of this Value with respect to the other CustomFieldEnumValues in the enumeration. |
value String (63) | A string value within the domain of this Custom Field. |
CustomFieldValueParams
Name | Description |
---|---|
field_id UUID | The unique public ID for the CustomField. |
value String | A literal value for the CustomField. Currently ignored. |
value_id UUID | The unique public ID for the CustomFieldEnumValue. |
DataConflictError
Error returned when Datomic tx fails due to Datomc :db.error/cas-failed error
Name | Description |
---|---|
error Enum (data-conflict-error) | |
message String | An explanatory message: “The update failed due to a data conflict. Please refresh and try again.” |
DeleteStories
Name | Description |
---|---|
story_ids Array [Integer] | An array of IDs of Stories to delete. |
EntityTemplate
An entity template can be used to prefill various fields when creating new stories.
Name | Description |
---|---|
author_id UUID | The unique ID of the member who created the template. |
created_at Date | The time/date when the entity template was created. |
entity_type String | A string description of this resource. |
id UUID | The unique identifier for the entity template. |
last_used_at Date | The last time that someone created an entity using this template. |
name String | The template’s name. |
story_contents StoryContents | A container entity for the attributes this template should populate. |
updated_at Date | The time/date when the entity template was last updated. |
Epic
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.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Epic. |
archived Boolean | True/false boolean that indicates whether the Epic is archived or not. |
associated_groups Array [EpicAssociatedGroup] | An array containing Group IDs and Group-owned story counts for the Epic’s associated groups. |
comments Array [ThreadedComment] | A nested array of threaded comments. |
completed Boolean | A true/false boolean indicating if the Epic has been completed. |
completed_at Date or null | The time/date the Epic was completed. |
completed_at_override Date or null | A manual override for the time/date the Epic was completed. |
created_at Date or null | The time/date the Epic was created. |
deadline Date or null | The Epic’s deadline. |
description String | The Epic’s description. |
entity_type String | A string description of this resource. |
epic_state_id Integer | The ID of the Epic State. |
external_id String or null | This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers on this Epic. |
group_id UUID or null | Deprecated The ID of the group to associate with the epic. Use group_ids . |
group_ids Array [UUID] | An array of UUIDS for Groups to which this Epic is related. |
group_mention_ids Array [UUID] | An array of Group IDs that have been mentioned in the Epic description. |
id Integer | The unique ID of the Epic. |
label_ids Array [Integer] | An array of Label ids attached to the Epic. |
labels Array [LabelSlim] | An array of Labels attached to the Epic. |
member_mention_ids Array [UUID] | An array of Member IDs that have been mentioned in the Epic description. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
milestone_id Integer or null | Deprecated The ID of the Objective this Epic is related to. Use objective_ids . |
name String | The name of the Epic. |
objective_ids Array [Integer] | An array of IDs for Objectives to which this epic is related. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Epic. |
planned_start_date Date or null | The Epic’s planned start date. |
position Integer | The Epic’s relative position in the Epic workflow state. |
productboard_id UUID or null | The ID of the associated productboard feature. |
productboard_name String or null | The name of the associated productboard feature. |
productboard_plugin_id UUID or null | The ID of the associated productboard integration. |
productboard_url String or null | The URL of the associated productboard feature. |
project_ids Array [Integer] | The IDs of Projects related to this Epic. |
requested_by_id UUID | The ID of the Member that requested the epic. |
started Boolean | A true/false boolean indicating if the Epic has been started. |
started_at Date or null | The time/date the Epic was started. |
started_at_override Date or null | A manual override for the time/date the Epic was started. |
state String | Deprecated The workflow state that the Epic is in. |
stats EpicStats | A group of calculated values for this Epic. |
stories_without_projects Integer | The number of stories in this epic which are not associated with a project. |
updated_at Date or null | The time/date the Epic was updated. |
EpicAssociatedGroup
Name | Description |
---|---|
associated_stories_count Integer | The number of stories this Group owns in the Epic. |
group_id UUID | The Group ID of the associated group. |
EpicSearchResult
An Epic in search results. This is typed differently from Epic because the details=slim search argument will omit some fields.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Epic. |
archived Boolean | True/false boolean that indicates whether the Epic is archived or not. |
associated_groups Array [EpicAssociatedGroup] | An array containing Group IDs and Group-owned story counts for the Epic’s associated groups. |
comments Array [ThreadedComment] | A nested array of threaded comments. |
completed Boolean | A true/false boolean indicating if the Epic has been completed. |
completed_at Date or null | The time/date the Epic was completed. |
completed_at_override Date or null | A manual override for the time/date the Epic was completed. |
created_at Date or null | The time/date the Epic was created. |
deadline Date or null | The Epic’s deadline. |
description String | The Epic’s description. |
entity_type String | A string description of this resource. |
epic_state_id Integer | The ID of the Epic State. |
external_id String or null | This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers on this Epic. |
group_id UUID or null | Deprecated The ID of the group to associate with the epic. Use group_ids . |
group_ids Array [UUID] | An array of UUIDS for Groups to which this Epic is related. |
group_mention_ids Array [UUID] | An array of Group IDs that have been mentioned in the Epic description. |
id Integer | The unique ID of the Epic. |
label_ids Array [Integer] | An array of Label ids attached to the Epic. |
labels Array [LabelSlim] | An array of Labels attached to the Epic. |
member_mention_ids Array [UUID] | An array of Member IDs that have been mentioned in the Epic description. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
milestone_id Integer or null | Deprecated The ID of the Objective this Epic is related to. Use objective_ids . |
name String | The name of the Epic. |
objective_ids Array [Integer] | An array of IDs for Objectives to which this epic is related. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Epic. |
planned_start_date Date or null | The Epic’s planned start date. |
position Integer | The Epic’s relative position in the Epic workflow state. |
productboard_id UUID or null | The ID of the associated productboard feature. |
productboard_name String or null | The name of the associated productboard feature. |
productboard_plugin_id UUID or null | The ID of the associated productboard integration. |
productboard_url String or null | The URL of the associated productboard feature. |
project_ids Array [Integer] | The IDs of Projects related to this Epic. |
requested_by_id UUID | The ID of the Member that requested the epic. |
started Boolean | A true/false boolean indicating if the Epic has been started. |
started_at Date or null | The time/date the Epic was started. |
started_at_override Date or null | A manual override for the time/date the Epic was started. |
state String | Deprecated The workflow state that the Epic is in. |
stats EpicStats | A group of calculated values for this Epic. |
stories_without_projects Integer | The number of stories in this epic which are not associated with a project. |
updated_at Date or null | The time/date the Epic was updated. |
EpicSearchResults
The results of the Epic search query.
Name | Description |
---|---|
data Array [EpicSearchResult] | A list of search results. |
next String or null | The URL path and query string for the next page of search results. |
total Integer | The total number of matches for the search query. The first 1000 matches can be paged through via the API. |
EpicSlim
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 endpoint to fetch the unabridged payload for an Epic.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Epic. |
archived Boolean | True/false boolean that indicates whether the Epic is archived or not. |
associated_groups Array [EpicAssociatedGroup] | An array containing Group IDs and Group-owned story counts for the Epic’s associated groups. |
completed Boolean | A true/false boolean indicating if the Epic has been completed. |
completed_at Date or null | The time/date the Epic was completed. |
completed_at_override Date or null | A manual override for the time/date the Epic was completed. |
created_at Date or null | The time/date the Epic was created. |
deadline Date or null | The Epic’s deadline. |
description String | The Epic’s description. |
entity_type String | A string description of this resource. |
epic_state_id Integer | The ID of the Epic State. |
external_id String or null | This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers on this Epic. |
group_id UUID or null | Deprecated The ID of the group to associate with the epic. Use group_ids . |
group_ids Array [UUID] | An array of UUIDS for Groups to which this Epic is related. |
group_mention_ids Array [UUID] | An array of Group IDs that have been mentioned in the Epic description. |
id Integer | The unique ID of the Epic. |
label_ids Array [Integer] | An array of Label ids attached to the Epic. |
labels Array [LabelSlim] | An array of Labels attached to the Epic. |
member_mention_ids Array [UUID] | An array of Member IDs that have been mentioned in the Epic description. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
milestone_id Integer or null | Deprecated The ID of the Objective this Epic is related to. Use objective_ids . |
name String | The name of the Epic. |
objective_ids Array [Integer] | An array of IDs for Objectives to which this epic is related. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this new Epic. |
planned_start_date Date or null | The Epic’s planned start date. |
position Integer | The Epic’s relative position in the Epic workflow state. |
productboard_id UUID or null | The ID of the associated productboard feature. |
productboard_name String or null | The name of the associated productboard feature. |
productboard_plugin_id UUID or null | The ID of the associated productboard integration. |
productboard_url String or null | The URL of the associated productboard feature. |
project_ids Array [Integer] | The IDs of Projects related to this Epic. |
requested_by_id UUID | The ID of the Member that requested the epic. |
started Boolean | A true/false boolean indicating if the Epic has been started. |
started_at Date or null | The time/date the Epic was started. |
started_at_override Date or null | A manual override for the time/date the Epic was started. |
state String | Deprecated The workflow state that the Epic is in. |
stats EpicStats | A group of calculated values for this Epic. |
stories_without_projects Integer | The number of stories in this epic which are not associated with a project. |
updated_at Date or null | The time/date the Epic was updated. |
EpicState
Epic State is any of the at least 3 columns. Epic States correspond to one of 3 types: Unstarted, Started, or Done.
Name | Description |
---|---|
color Color | The hex color for this Epic State. |
created_at Date | The time/date the Epic State was created. |
description String | The description of what sort of Epics belong in that Epic State. |
entity_type String | A string description of this resource. |
id Integer | The unique ID of the Epic State. |
name String | The Epic State’s name. |
position Integer | The position that the Epic State is in, starting with 0 at the left. |
type String | The type of Epic State (Unstarted, Started, or Done) |
updated_at Date | When the Epic State was last updated. |
EpicStats
A group of calculated values for this Epic.
Name | Description |
---|---|
average_cycle_time Integer | The average cycle time (in seconds) of completed stories in this Epic. |
average_lead_time Integer | The average lead time (in seconds) of completed stories in this Epic. |
last_story_update Date or null | The date of the last update of a Story in this Epic. |
num_points Integer | The total number of points in this Epic. |
num_points_backlog Integer | The total number of backlog points in this Epic. |
num_points_done Integer | The total number of completed points in this Epic. |
num_points_started Integer | The total number of started points in this Epic. |
num_points_unstarted Integer | The total number of unstarted points in this Epic. |
num_related_documents Integer | The total number of documents associated with this Epic. |
num_stories_backlog Integer | The total number of backlog Stories in this Epic. |
num_stories_done Integer | The total number of done Stories in this Epic. |
num_stories_started Integer | The total number of started Stories in this Epic. |
num_stories_total Integer | The total number of Stories in this Epic. |
num_stories_unestimated Integer | The total number of Stories with no point estimate. |
num_stories_unstarted Integer | The total number of unstarted Stories in this Epic. |
EpicWorkflow
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.
Name | Description |
---|---|
created_at Date | The date the Epic Workflow was created. |
default_epic_state_id Integer | The unique ID of the default Epic State that new Epics are assigned by default. |
entity_type String | A string description of this resource. |
epic_states Array [EpicState] | A map of the Epic States in this Epic Workflow. |
id Integer | The unique ID of the Epic Workflow. |
updated_at Date | The date the Epic Workflow was updated. |
Group
A Group.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Group. |
archived Boolean | Whether or not the Group is archived. |
color Color or null | The hex color to be displayed with the Group (for example, “#ff0000”). |
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) or null | The color key to be displayed with the Group. |
description String | The description of the Group. |
display_icon Icon or null | Icons are used to attach images to Groups, Workspaces, Members, and Loading screens in the Shortcut web application. |
entity_type String | A string description of this resource. |
id UUID | The id of the Group. |
member_ids Array [UUID] | The Member IDs contain within the Group. |
mention_name String | The mention name of the Group. |
name String | The name of the Group. |
num_epics_started Integer | The number of epics assigned to the group which are in the started workflow state. |
num_stories Integer | The total number of stories assigned to the group. |
num_stories_backlog Integer | The number of stories assigned to the group which are in a backlog workflow state. |
num_stories_started Integer | The number of stories assigned to the group which are in a started workflow state. |
workflow_ids Array [Integer] | The Workflow IDs contained within the Group. |
History
A history item is a group of actions that represent a transactional change to a Story.
Name | Description |
---|---|
actions Array [undefined] | An array of actions that were performed for the change. |
automation_id UUID | The ID of the automation that performed the change. |
changed_at String | The date when the change occurred. |
external_id String | The ID of the webhook that handled the change. |
id UUID | The ID representing the change for the story. |
member_id UUID | The ID of the member who performed the change. |
primary_id undefined | The ID of the primary entity that has changed, if applicable. |
references Array [undefined] | 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. |
version Enum (v1) | The version of the change format. |
webhook_id String or null | The ID of the webhook that handled the change. |
HistoryActionBranchCreate
An action representing a VCS Branch being created.
Name | Description |
---|---|
action Enum (create) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
name String | The name of the VCS Branch that was pushed |
url String | The URL from the provider of the VCS Branch that was pushed |
HistoryActionBranchMerge
An action representing a VCS Branch being merged.
Name | Description |
---|---|
action Enum (merge) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
name String | The name of the VCS Branch that was pushed |
url String | The URL from the provider of the VCS Branch that was pushed |
HistoryActionBranchPush
An action representing a VCS Branch being pushed.
Name | Description |
---|---|
action Enum (push) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
name String | The name of the VCS Branch that was pushed |
url String | The URL from the provider of the VCS Branch that was pushed |
HistoryActionLabelCreate
An action representing a Label being created.
Name | Description |
---|---|
action Enum (create) | The action of the entity referenced. |
app_url String (2048) | The application URL of the Label. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
name String | The name of the Label. |
HistoryActionLabelDelete
An action representing a Label being deleted.
Name | Description |
---|---|
action Enum (delete) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
name String | The name of the Label. |
HistoryActionLabelUpdate
An action representing a Label being updated.
Name | Description |
---|---|
action Enum (update) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
HistoryActionProjectUpdate
An action representing a Project being updated.
Name | Description |
---|---|
action Enum (update) | The action of the entity referenced. |
app_url String (2048) | The application URL of the Project. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
name String | The name of the Project. |
HistoryActionPullRequest
An action representing various operations for a Pull Request.
Name | Description |
---|---|
action Enum (close, comment, open, reopen, sync, update) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
number Integer | The VCS Repository-specific ID for the Pull Request. |
title String | The title of the Pull Request. |
url String (2048) | The URL from the provider of the VCS Pull Request. |
HistoryActionStoryCommentCreate
An action representing a Story Comment being created.
Name | Description |
---|---|
action Enum (create) | The action of the entity referenced. |
app_url String (2048) | The application URL of the Story Comment. |
author_id UUID | The Member ID of who created the Story Comment. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
text String | The text of the Story Comment. |
HistoryActionStoryCreate
An action representing a Story being created.
Name | Description |
---|---|
action Enum (create) | The action of the entity referenced. |
app_url String (2048) | The application URL of the Story. |
blocked Boolean | Whether or not the Story is blocked by another Story. |
blocker Boolean | Whether or not the Story is blocking another Story. |
completed Boolean | Whether or not the Story is completed. |
custom_field_value_ids Array [UUID] | An array of Custom Field Enum Value ids on this Story. |
deadline String | The timestamp representing the Story’s deadline. |
description String | The description of the Story. |
entity_type String | The type of entity referenced. |
epic_id Integer | The Epic ID for this Story. |
estimate Integer | The estimate (or point value) for the Story. |
follower_ids Array [UUID] | An array of Member IDs for the followers of the Story. |
group_id UUID | The Team IDs for the followers of the Story. |
id Integer | The ID of the entity referenced. |
iteration_id Integer or null | The Iteration ID the Story is in. |
label_ids Array [Integer] | An array of Labels IDs attached to the Story. |
name String | The name of the Story. |
object_story_link_ids Array [Integer] | An array of Story IDs that are the object of a Story Link relationship. |
owner_ids Array [UUID] | An array of Member IDs that are the owners of the Story. |
project_id Integer | The Project ID of the Story is in. |
requested_by_id UUID | The ID of the Member that requested the Story. |
started Boolean | Whether or not the Story has been started. |
story_type Enum (bug, chore, feature) | The type of Story; either feature, bug, or chore. |
subject_story_link_ids Array [Integer] | An array of Story IDs that are the subject of a Story Link relationship. |
task_ids Array [Integer] | An array of Task IDs on this Story. |
workflow_state_id Integer | An array of Workflow State IDs attached to the Story. |
HistoryActionStoryDelete
An action representing a Story being deleted.
Name | Description |
---|---|
action Enum (delete) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
name String | The name of the Story. |
story_type Enum (bug, chore, feature) | The type of Story; either feature, bug, or chore. |
HistoryActionStoryLinkCreate
An action representing a Story Link being created.
Name | Description |
---|---|
action Enum (create) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
object_id Integer | The Story ID of the object Story. |
subject_id Integer | The Story ID of the subject Story. |
verb Enum (blocks, duplicates, relates to) | The verb describing the link’s relationship. |
HistoryActionStoryLinkDelete
An action representing a Story Link being deleted.
Name | Description |
---|---|
action Enum (delete) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
object_id Integer or null | The Story ID of the object Story. |
subject_id Integer or null | The Story ID of the subject Story. |
verb Enum (blocks, duplicates, relates to) | The verb describing the link’s relationship. |
HistoryActionStoryLinkUpdate
An action representing a Story Link being updated.
Name | Description |
---|---|
action Enum (update) | The action of the entity referenced. |
changes HistoryChangesStoryLink | The changes that have occurred as a result of the action. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
object_id Integer | The Story ID of the object Story. |
subject_id Integer | The Story ID of the subject Story. |
verb Enum (blocks, duplicates, relates to) | The verb describing the link’s relationship. |
HistoryActionStoryUpdate
An action representing a Story being updated.
Name | Description |
---|---|
action Enum (update) | The action of the entity referenced. |
app_url String (2048) | The application URL of the Story. |
changes HistoryChangesStory | The changes that have occurred as a result of the action. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
name String | The name of the Story. |
story_type Enum (bug, chore, feature) | The type of Story; either feature, bug, or chore. |
HistoryActionTaskCreate
An action representing a Task being created.
Name | Description |
---|---|
action Enum (create) | The action of the entity referenced. |
complete Boolean | Whether or not the Task is complete. |
deadline String | A timestamp that represent’s the Task’s deadline. |
description String | The description of the Task. |
entity_type String | The type of entity referenced. |
group_mention_ids Array [UUID] | An array of Groups IDs that represent which have been mentioned in the Task. |
id Integer | The ID of the entity referenced. |
mention_ids Array [UUID] | An array of Member IDs that represent who has been mentioned in the Task. |
owner_ids Array [UUID] | An array of Member IDs that represent the Task’s owners. |
HistoryActionTaskDelete
An action representing a Task being deleted.
Name | Description |
---|---|
action Enum (delete) | The action of the entity referenced. |
description String | The description of the Task being deleted. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
HistoryActionTaskUpdate
An action representing a Task being updated.
Name | Description |
---|---|
action Enum (update) | The action of the entity referenced. |
changes HistoryChangesTask | The changes that have occurred as a result of the action. |
complete Boolean | Whether or not the Task is complete. |
description String | The description of the Task. |
entity_type String | The type of entity referenced. |
id Integer | The ID of the entity referenced. |
story_id Integer | The Story ID that contains the Task. |
HistoryActionWorkspace2BulkUpdate
An action representing a bulk operation within a workspace2.
Name | Description |
---|---|
action Enum (bulk-update) | The action of the entity referenced. |
entity_type String | The type of entity referenced. |
id UUID | The ID of the entity referenced. |
name String | The name of the workspace2 in which the BulkUpdate occurred. |
HistoryChangesStory
The changes that have occurred as a result of the action.
Name | Description |
---|---|
archived StoryHistoryChangeOldNewBool | True if the Story has archived, otherwise false. |
blocked StoryHistoryChangeOldNewBool | True if the Story has archived, otherwise false. |
blocker StoryHistoryChangeOldNewBool | True if the Story has archived, otherwise false. |
branch_ids StoryHistoryChangeAddsRemovesInt | Task IDs that have been added or removed from the Story. |
commit_ids StoryHistoryChangeAddsRemovesInt | Task IDs that have been added or removed from the Story. |
completed StoryHistoryChangeOldNewBool | True if the Story has archived, otherwise false. |
custom_field_value_ids StoryHistoryChangeAddsRemovesUuid | Custom Field Enum Value IDs that have been added or removed from the Story. |
deadline StoryHistoryChangeOldNewStr | A timestamp that represents the Story’s deadline. |
description StoryHistoryChangeOldNewStr | A timestamp that represents the Story’s deadline. |
epic_id StoryHistoryChangeOldNewInt | The estimate value for the Story |
estimate StoryHistoryChangeOldNewInt | The estimate value for the Story |
follower_ids StoryHistoryChangeAddsRemovesUuid | Custom Field Enum Value IDs that have been added or removed from the Story. |
group_id StoryHistoryChangeOldNewUuid | The Team ID for the Story. |
iteration_id StoryHistoryChangeOldNewInt | The estimate value for the Story |
label_ids StoryHistoryChangeAddsRemovesInt | Task IDs that have been added or removed from the Story. |
mention_ids StoryHistoryChangeAddsRemovesUuid | Custom Field Enum Value IDs that have been added or removed from the Story. |
name StoryHistoryChangeOldNewStr | A timestamp that represents the Story’s deadline. |
object_story_link_ids StoryHistoryChangeAddsRemovesInt | Task IDs that have been added or removed from the Story. |
owner_ids StoryHistoryChangeAddsRemovesUuid | Custom Field Enum Value IDs that have been added or removed from the Story. |
project_id StoryHistoryChangeOldNewInt | The estimate value for the Story |
requested_by_id StoryHistoryChangeOldNewUuid | The Team ID for the Story. |
started StoryHistoryChangeOldNewBool | True if the Story has archived, otherwise false. |
story_type StoryHistoryChangeOldNewStr | A timestamp that represents the Story’s deadline. |
subject_story_link_ids StoryHistoryChangeAddsRemovesInt | Task IDs that have been added or removed from the Story. |
task_ids StoryHistoryChangeAddsRemovesInt | Task IDs that have been added or removed from the Story. |
workflow_state_id StoryHistoryChangeOldNewInt | The estimate value for the Story |
HistoryChangesStoryLink
The changes that have occurred as a result of the action.
Name | Description |
---|---|
object_id StoryHistoryChangeOldNewInt | The estimate value for the Story |
subject_id StoryHistoryChangeOldNewInt | The estimate value for the Story |
verb StoryHistoryChangeOldNewStr | A timestamp that represents the Story’s deadline. |
HistoryChangesTask
The changes that have occurred as a result of the action.
Name | Description |
---|---|
complete StoryHistoryChangeOldNewBool | True if the Story has archived, otherwise false. |
description StoryHistoryChangeOldNewStr | A timestamp that represents the Story’s deadline. |
mention_ids StoryHistoryChangeAddsRemovesUuid | Custom Field Enum Value IDs that have been added or removed from the Story. |
owner_ids StoryHistoryChangeAddsRemovesUuid | Custom Field Enum Value IDs that have been added or removed from the Story. |
HistoryReferenceBranch
A reference to a VCS Branch.
Name | Description |
---|---|
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
name String | The name of the entity referenced. |
url String (2048) | The external URL for the Branch. |
HistoryReferenceCommit
A reference to a VCS Commit.
Name | Description |
---|---|
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
message String | The message from the Commit. |
url String (2048) | The external URL for the Branch. |
HistoryReferenceCustomFieldEnumValue
A reference to a CustomField value asserted on a Story.
Name | Description |
---|---|
entity_type String | The type of entity referenced. |
enum_value_enabled Boolean or null | Whether or not the custom-field enum value is enabled. |
field_enabled Boolean | Whether or not the custom-field is enabled. |
field_id UUID | The public-id of the parent custom-field of this enum value. |
field_name String | The name as it is displayed to the user of the parent custom-field of this enum value. |
field_type String | The type variety of the parent custom-field of this enum value. |
id undefined | The ID of the entity referenced. |
string_value String or null | The custom-field enum value as a string. |
HistoryReferenceEpic
A reference to an Epic.
Name | Description |
---|---|
app_url String (2048) | The application URL of the Epic. |
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
name String | The name of the entity referenced. |
HistoryReferenceGeneral
A default reference for entity types that don’t have extra fields.
Name | Description |
---|---|
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
name String | The name of the entity referenced. |
HistoryReferenceGroup
A reference to a Group.
Name | Description |
---|---|
entity_type String | The type of entity referenced. |
id UUID | The ID of the entity referenced. |
name String | The name of the entity referenced. |
HistoryReferenceIteration
A reference to an Iteration.
Name | Description |
---|---|
app_url String (2048) | The application URL of the Iteration. |
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
name String | The name of the entity referenced. |
HistoryReferenceLabel
A reference to an Label.
Name | Description |
---|---|
app_url String (2048) | The application URL of the Label. |
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
name String | The name of the entity referenced. |
HistoryReferenceProject
A reference to an Project.
Name | Description |
---|---|
app_url String (2048) | The application URL of the Project. |
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
name String | The name of the entity referenced. |
HistoryReferenceStory
A reference to a Story.
Name | Description |
---|---|
app_url String (2048) | The application URL of the Story. |
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
name String | The name of the entity referenced. |
story_type Enum (bug, chore, feature) | If the referenced entity is a Story, either “bug”, “chore”, or “feature”. |
HistoryReferenceStoryTask
A reference to a Story Task.
Name | Description |
---|---|
description String | The description of the Story Task. |
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
HistoryReferenceWorkflowState
A references to a Story Workflow State.
Name | Description |
---|---|
entity_type String | The type of entity referenced. |
id undefined | The ID of the entity referenced. |
name String | The name of the entity referenced. |
type Enum (backlog, done, started, unstarted) | Either “backlog”, “unstarted”, “started”, or “done”. |
Icon
Icons are used to attach images to Groups, Workspaces, Members, and Loading screens in the Shortcut web application.
Name | Description |
---|---|
created_at Date | The time/date that the Icon was created. |
entity_type String | A string description of this resource. |
id UUID | The unique ID of the Icon. |
updated_at Date | The time/date that the Icon was updated. |
url String | The URL of the Icon. |
Identity
The Identity of the VCS user that authored the Commit.
Name | Description |
---|---|
entity_type String | A string description of this resource. |
name String or null | This is your login in VCS. |
type Enum (bitbucket, github, gitlab, slack) or null | The service this Identity is for. |
Iteration
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.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Iteration. |
created_at Date | The instant when this iteration was created. |
description String | The description of the iteration. |
end_date Date | The date this iteration ends. |
entity_type String | A string description of this resource |
follower_ids Array [UUID] | An array of UUIDs for any Members listed as Followers. |
group_ids Array [UUID] | An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI. |
group_mention_ids Array [UUID] | An array of Group IDs that have been mentioned in the Story description. |
id Integer | The ID of the iteration. |
label_ids Array [Integer] | An array of label ids attached to the iteration. |
labels Array [Label] | An array of labels attached to the iteration. |
member_mention_ids Array [UUID] | An array of Member IDs that have been mentioned in the Story description. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
name String | The name of the iteration. |
start_date Date | The date this iteration begins. |
stats IterationStats | A group of calculated values for this Iteration. |
status String | The status of the iteration. Values are either “unstarted”, “started”, or “done”. |
updated_at Date | The instant when this iteration was last updated. |
IterationAssociatedGroup
Name | Description |
---|---|
associated_stories_count Integer | The number of stories this Group owns in the Iteration. |
group_id UUID | The Group ID of the associated group. |
IterationSearchResults
The results of the Iteration search query.
Name | Description |
---|---|
data Array [IterationSlim] | A list of search results. |
next String or null | The URL path and query string for the next page of search results. |
total Integer | The total number of matches for the search query. The first 1000 matches can be paged through via the API. |
IterationSlim
IterationSlim represents the same resource as an Iteration, but is more light-weight. Use the Get Iteration endpoint to fetch the unabridged payload for an Iteration.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Iteration. |
created_at Date | The instant when this iteration was created. |
end_date Date | The date this iteration ends. |
entity_type String | A string description of this resource |
follower_ids Array [UUID] | An array of UUIDs for any Members listed as Followers. |
group_ids Array [UUID] | An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI. |
group_mention_ids Array [UUID] | An array of Group IDs that have been mentioned in the Story description. |
id Integer | The ID of the iteration. |
label_ids Array [Integer] | An array of label ids attached to the iteration. |
labels Array [Label] | An array of labels attached to the iteration. |
member_mention_ids Array [UUID] | An array of Member IDs that have been mentioned in the Story description. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
name String | The name of the iteration. |
start_date Date | The date this iteration begins. |
stats IterationStats | A group of calculated values for this Iteration. |
status String | The status of the iteration. Values are either “unstarted”, “started”, or “done”. |
updated_at Date | The instant when this iteration was last updated. |
IterationStats
A group of calculated values for this Iteration.
Name | Description |
---|---|
average_cycle_time Integer | The average cycle time (in seconds) of completed stories in this Iteration. |
average_lead_time Integer | The average lead time (in seconds) of completed stories in this Iteration. |
num_points Integer | The total number of points in this Iteration. |
num_points_backlog Integer | The total number of backlog points in this Iteration. |
num_points_done Integer | The total number of completed points in this Iteration. |
num_points_started Integer | The total number of started points in this Iteration. |
num_points_unstarted Integer | The total number of unstarted points in this Iteration. |
num_related_documents Integer | The total number of documents related to an Iteration |
num_stories_backlog Integer | The total number of backlog Stories in this Iteration. |
num_stories_done Integer | The total number of done Stories in this Iteration. |
num_stories_started Integer | The total number of started Stories in this Iteration. |
num_stories_unestimated Integer | The total number of Stories with no point estimate. |
num_stories_unstarted Integer | The total number of unstarted Stories in this Iteration. |
KeyResult
Name | Description |
---|---|
current_observed_value KeyResultValue | The starting value of the Key Result. |
current_target_value KeyResultValue | The starting value of the Key Result. |
id UUID | The ID of the Key Result. |
initial_observed_value KeyResultValue | The starting value of the Key Result. |
name String | The name of the Key Result. |
objective_id Integer | The Objective to which this Key Result belongs. |
progress Integer | The integer percentage of progress toward completion of the Key Result. |
type Enum (boolean, numeric, percent) | The type of the Key Result (numeric, percent, or boolean). |
KeyResultValue
The starting value of the Key Result.
Name | Description |
---|---|
boolean_value Boolean | The boolean value. |
numeric_value String | The numeric value, as a decimal string. No more than two decimal places are allowed. |
Label
A Label can be used to associate and filter Stories and Epics, and also create new Workspaces.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Label. |
archived Boolean | A true/false boolean indicating if the Label has been archived. |
color Color or null | The hex color to be displayed with the Label (for example, “#ff0000”). |
created_at Date or null | The time/date that the Label was created. |
description String or null | The description of the Label. |
entity_type String | A string description of this resource. |
external_id String or null | 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. |
id Integer | The unique ID of the Label. |
name String | The name of the Label. |
stats LabelStats | 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. |
updated_at Date or null | The time/date that the Label was updated. |
LabelSlim
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.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Label. |
archived Boolean | A true/false boolean indicating if the Label has been archived. |
color Color or null | The hex color to be displayed with the Label (for example, “#ff0000”). |
created_at Date or null | The time/date that the Label was created. |
description String or null | The description of the Label. |
entity_type String | A string description of this resource. |
external_id String or null | 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. |
id Integer | The unique ID of the Label. |
name String | The name of the Label. |
updated_at Date or null | The time/date that the Label was updated. |
LabelStats
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.
Name | Description |
---|---|
num_epics Integer | The total number of Epics with this Label. |
num_epics_completed Integer | The number of completed Epics associated with this Label. |
num_epics_in_progress Integer | The number of in progress epics associated with this label. |
num_epics_total Integer | The total number of Epics associated with this Label. |
num_epics_unstarted Integer | The number of unstarted epics associated with this label. |
num_points_backlog Integer | The total number of backlog points with this Label. |
num_points_completed Integer | The total number of completed points with this Label. |
num_points_in_progress Integer | The total number of in-progress points with this Label. |
num_points_total Integer | The total number of points with this Label. |
num_points_unstarted Integer | The total number of unstarted points with this Label. |
num_related_documents Integer | The total number of Documents associated this Label. |
num_stories_backlog Integer | The total number of stories backlog Stories with this Label. |
num_stories_completed Integer | The total number of completed Stories with this Label. |
num_stories_in_progress Integer | The total number of in-progress Stories with this Label. |
num_stories_total Integer | The total number of Stories with this Label. |
num_stories_unestimated Integer | The total number of Stories with no point estimate with this Label. |
num_stories_unstarted Integer | The total number of stories unstarted Stories with this Label. |
LinkedFile
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.
Name | Description |
---|---|
content_type String or null | The content type of the image (e.g. txt/plain). |
created_at Date | The time/date the LinkedFile was created. |
description String or null | The description of the file. |
entity_type String | A string description of this resource. |
group_mention_ids Array [UUID] | The groups that are mentioned in the description of the file. |
id Integer | The unique identifier for the file. |
member_mention_ids Array [UUID] | The members that are mentioned in the description of the file. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
name String | The name of the linked file. |
size Integer or null | The filesize, if the integration provided it. |
story_ids Array [Integer] | The IDs of the stories this file is attached to. |
thumbnail_url String or null | The URL of the file thumbnail, if the integration provided it. |
type String | The integration type (e.g. google, dropbox, box). |
updated_at Date | The time/date the LinkedFile was updated. |
uploader_id UUID | The UUID of the member that uploaded the file. |
url String | The URL of the file. |
MaxSearchResultsExceededError
Error returned when total maximum supported results have been reached.
Name | Description |
---|---|
error Enum (maximum-results-exceeded) | The name for this type of error, maximum-results-exceeded |
maximum-results Enum (1000) | The maximum number of search results supported, 1000 |
message String | An explanatory message: “A maximum of 1000 search results are supported.” |
Member
Details about an individual user within the Workspace.
Name | Description |
---|---|
created_at Date or null | The time/date the Member was created. |
disabled Boolean | True/false boolean indicating whether the Member has been disabled within the Workspace. |
entity_type String | A string description of this resource. |
group_ids Array [UUID] | The Member’s group ids |
id UUID | The Member’s ID in Shortcut. |
profile Profile | A group of Member profile details. |
role String | The Member’s role in the Workspace. |
state Enum (disabled, full, imported, partial) | 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. |
updated_at Date or null | The time/date the Member was last updated. |
MemberInfo
Name | Description |
---|---|
id UUID | |
mention_name String | |
name String | |
workspace2 BasicWorkspaceInfo |
Milestone
(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.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Milestone. |
archived Boolean | A boolean indicating whether the Milestone has been archived or not. |
categories Array [Category] | An array of Categories attached to the Milestone. |
completed Boolean | A true/false boolean indicating if the Milestone has been completed. |
completed_at Date or null | The time/date the Milestone was completed. |
completed_at_override Date or null | A manual override for the time/date the Milestone was completed. |
created_at Date | The time/date the Milestone was created. |
description String | The Milestone’s description. |
entity_type String | A string description of this resource. |
id Integer | The unique ID of the Milestone. |
key_result_ids Array [UUID] | The IDs of the Key Results associated with the Objective. |
name String | The name of the Milestone. |
position Integer | A number representing the position of the Milestone in relation to every other Milestone within the Workspace. |
started Boolean | A true/false boolean indicating if the Milestone has been started. |
started_at Date or null | The time/date the Milestone was started. |
started_at_override Date or null | A manual override for the time/date the Milestone was started. |
state String | The workflow state that the Milestone is in. |
stats MilestoneStats | A group of calculated values for this Milestone. |
updated_at Date | The time/date the Milestone was updated. |
MilestoneStats
A group of calculated values for this Milestone.
Name | Description |
---|---|
average_cycle_time Integer | The average cycle time (in seconds) of completed stories in this Milestone. |
average_lead_time Integer | The average lead time (in seconds) of completed stories in this Milestone. |
num_related_documents Integer | The number of related documents to this Milestone. |
Objective
An Objective is a collection of Epics that represent a release or some other large initiative that you are working on.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Objective. |
archived Boolean | A boolean indicating whether the Objective has been archived or not. |
categories Array [Category] | An array of Categories attached to the Objective. |
completed Boolean | A true/false boolean indicating if the Objectivehas been completed. |
completed_at Date or null | The time/date the Objective was completed. |
completed_at_override Date or null | A manual override for the time/date the Objective was completed. |
created_at Date | The time/date the Objective was created. |
description String | The Objective’s description. |
entity_type String | A string description of this resource. |
id Integer | The unique ID of the Objective. |
key_result_ids Array [UUID] | The IDs of the Key Results associated with the Objective. |
name String | The name of the Objective. |
position Integer | A number representing the position of the Objective in relation to every other Objective within the Workspace. |
started Boolean | A true/false boolean indicating if the Objective has been started. |
started_at Date or null | The time/date the Objective was started. |
started_at_override Date or null | A manual override for the time/date the Objective was started. |
state String | The workflow state that the Objective is in. |
stats ObjectiveStats | A group of calculated values for this Objective. |
updated_at Date | The time/date the Objective was updated. |
ObjectiveSearchResult
A Milestone in search results. This is typed differently from Milestone because the details=slim search argument will omit some fields.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Milestone. |
archived Boolean | A boolean indicating whether the Milestone has been archived or not. |
categories Array [Category] | An array of Categories attached to the Milestone. |
completed Boolean | A true/false boolean indicating if the Milestone has been completed. |
completed_at Date or null | The time/date the Milestone was completed. |
completed_at_override Date or null | A manual override for the time/date the Milestone was completed. |
created_at Date | The time/date the Milestone was created. |
description String | The Milestone’s description. |
entity_type String | A string description of this resource. |
id Integer | The unique ID of the Milestone. |
key_result_ids Array [UUID] | The IDs of the Key Results associated with the Objective. |
name String | The name of the Milestone. |
position Integer | A number representing the position of the Milestone in relation to every other Milestone within the Workspace. |
started Boolean | A true/false boolean indicating if the Milestone has been started. |
started_at Date or null | The time/date the Milestone was started. |
started_at_override Date or null | A manual override for the time/date the Milestone was started. |
state String | The workflow state that the Milestone is in. |
stats MilestoneStats | A group of calculated values for this Milestone. |
updated_at Date | The time/date the Milestone was updated. |
ObjectiveSearchResults
The results of the Objective search query.
Name | Description |
---|---|
data Array [ObjectiveSearchResult] | A list of search results. |
next String or null | The URL path and query string for the next page of search results. |
total Integer | The total number of matches for the search query. The first 1000 matches can be paged through via the API. |
ObjectiveStats
A group of calculated values for this Objective.
Name | Description |
---|---|
average_cycle_time Integer | The average cycle time (in seconds) of completed stories in this Objective. |
average_lead_time Integer | The average lead time (in seconds) of completed stories in this Objective. |
num_related_documents Integer | The number of related documents to this Objective. |
Profile
A group of Member profile details.
Name | Description |
---|---|
deactivated Boolean | A true/false boolean indicating whether the Member has been deactivated within Shortcut. |
display_icon Icon or null | Icons are used to attach images to Groups, Workspaces, Members, and Loading screens in the Shortcut web application. |
email_address String or null | The primary email address of the Member with the Organization. |
entity_type String | A string description of this resource. |
gravatar_hash String or null | This is the gravatar hash associated with email_address. |
id UUID | The unique identifier of the profile. |
is_owner Boolean | A boolean indicating whether this profile is an owner at their associated organization. |
mention_name String | The Member’s username within the Organization. |
name String or null | The Member’s name within the Organization. |
two_factor_auth_activated Boolean | If Two Factor Authentication is activated for this User. |
Project
Projects typically map to teams (such as Frontend, Backend, Mobile, Devops, etc) but can represent any open-ended product, component, or initiative.
Name | Description |
---|---|
abbreviation String or null | The Project abbreviation used in Story summaries. Should be kept to 3 characters at most. |
app_url String | The Shortcut application url for the Project. |
archived Boolean | True/false boolean indicating whether the Project is in an Archived state. |
color Color or null | The color associated with the Project in the Shortcut member interface. |
created_at Date or null | The time/date that the Project was created. |
days_to_thermometer Integer | The number of days before the thermometer appears in the Story summary. |
description String or null | The description of the Project. |
entity_type String | A string description of this resource. |
external_id String or null | 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. |
follower_ids Array [UUID] | An array of UUIDs for any Members listed as Followers. |
id Integer | The unique ID of the Project. |
iteration_length Integer | The number of weeks per iteration in this Project. |
name String | The name of the Project |
show_thermometer Boolean | Configuration to enable or disable thermometers in the Story summary. |
start_time Date | The date at which the Project was started. |
stats ProjectStats | A group of calculated values for this Project. |
team_id Integer | The ID of the team the project belongs to. |
updated_at Date or null | The time/date that the Project was last updated. |
workflow_id Integer | The ID of the workflow the project belongs to. |
ProjectStats
A group of calculated values for this Project.
Name | Description |
---|---|
num_points Integer | The total number of points in this Project. |
num_related_documents Integer | The total number of documents related to this Project |
num_stories Integer | The total number of stories in this Project. |
PullRequest
Corresponds to a VCS Pull Request attached to a Shortcut story.
Name | Description |
---|---|
branch_id Integer | The ID of the branch for the particular pull request. |
branch_name String | The name of the branch for the particular pull request. |
build_status String | The status of the Continuous Integration workflow for the pull request. |
closed Boolean | True/False boolean indicating whether the VCS pull request has been closed. |
created_at Date | The time/date the pull request was created. |
draft Boolean | True/False boolean indicating whether the VCS pull request is in the draft state. |
entity_type String | A string description of this resource. |
has_overlapping_stories Boolean | 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. |
id Integer | The unique ID associated with the pull request in Shortcut. |
merged Boolean | True/False boolean indicating whether the VCS pull request has been merged. |
num_added Integer | Number of lines added in the pull request, according to VCS. |
num_commits Integer or null | The number of commits on the pull request. |
num_modified Integer or null | Number of lines modified in the pull request, according to VCS. |
num_removed Integer | Number of lines removed in the pull request, according to VCS. |
number Integer | The pull request’s unique number ID in VCS. |
overlapping_stories Array [Integer] | An array of Story ids that have Pull Requests that change at least one of the same lines this Pull Request changes. |
repository_id Integer | The ID of the repository for the particular pull request. |
review_status String | The status of the review for the pull request. |
target_branch_id Integer | The ID of the target branch for the particular pull request. |
target_branch_name String | The name of the target branch for the particular pull request. |
title String | The title of the pull request. |
updated_at Date | The time/date the pull request was created. |
url String | The URL for the pull request. |
vcs_labels Array [PullRequestLabel] or null | An array of PullRequestLabels attached to the PullRequest. |
PullRequestLabel
Corresponds to a VCS Label associated with a Pull Request.
Name | Description |
---|---|
color Color | The color of the VCS label. |
description String or null | The description of the VCS label. |
entity_type String | A string description of this resource. |
id Integer | The unique ID of the VCS Label. |
name String | The name of the VCS label. |
RemoveCustomFieldParams
Name | Description |
---|---|
field_id UUID | The unique public ID for the CustomField. |
RemoveLabelParams
Request parameters for removing a Label from a Shortcut Story.
Name | Description |
---|---|
name String (128) | The name of the new Label to remove. |
Repository
Repository refers to a VCS repository.
Name | Description |
---|---|
created_at Date or null | The time/date the Repository was created. |
entity_type String | A string description of this resource. |
external_id String or null | The VCS unique identifier for the Repository. |
full_name String or null | The full name of the VCS repository. |
id Integer or null | The ID associated to the VCS repository in Shortcut. |
name String or null | The shorthand name of the VCS repository. |
type Enum (bitbucket, github, gitlab) | The VCS provider for the Repository. |
updated_at Date or null | The time/date the Repository was updated. |
url String or null | The URL of the Repository. |
SearchResults
The results of the multi-entity search query.
Name | Description |
---|---|
epics EpicSearchResults | The results of the Epic search query. |
iterations IterationSearchResults | The results of the Iteration search query. |
milestones ObjectiveSearchResults | The results of the Objective search query. |
stories StorySearchResults | The results of the Story search query. |
SearchStories
Name | Description |
---|---|
archived Boolean | A true/false boolean indicating whether the Story is in archived state. |
completed_at_end Date | Stories should have been completed on or before this date. |
completed_at_start Date | Stories should have been completed on or after this date. |
created_at_end Date | Stories should have been created on or before this date. |
created_at_start Date | Stories should have been created on or after this date. |
deadline_end Date | Stories should have a deadline on or before this date. |
deadline_start Date | Stories should have a deadline on or after this date. |
epic_id Integer or null | The Epic IDs that may be associated with the Stories. |
epic_ids Array [Integer] | The Epic IDs that may be associated with the Stories. |
estimate Integer | The number of estimate points associate with the Stories. |
external_id String (1024) | An ID or URL that references an external resource. Useful during imports. |
group_id UUID or null | The Group ID that is associated with the Stories |
group_ids Array [UUID] | The Group IDs that are associated with the Stories |
includes_description Boolean | Whether to include the story description in the response. |
iteration_id Integer or null | The Iteration ID that may be associated with the Stories. |
iteration_ids Array [Integer] | The Iteration IDs that may be associated with the Stories. |
label_ids Array [Integer] | The Label IDs that may be associated with the Stories. |
label_name String | The name of any associated Labels. |
owner_id UUID or null | An array of UUIDs for any Users who may be Owners of the Stories. |
owner_ids Array [UUID] | An array of UUIDs for any Users who may be Owners of the Stories. |
project_id Integer or null | The IDs for the Projects the Stories may be assigned to. |
project_ids Array [Integer or null] | The IDs for the Projects the Stories may be assigned to. |
requested_by_id UUID | The UUID of any Users who may have requested the Stories. |
story_type Enum (bug, chore, feature) | The type of Stories that you want returned. |
updated_at_end Date | Stories should have been updated on or before this date. |
updated_at_start Date | Stories should have been updated on or after this date. |
workflow_state_id Integer | The unique IDs of the specific Workflow States that the Stories should be in. |
workflow_state_types Array [Enum (backlog, done, started, unstarted)] | The type of Workflow State the Stories may be in. |
Story
Stories are the standard unit of work in Shortcut and represent individual features, bugs, and chores.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Story. |
archived Boolean | True if the story has been archived or not. |
blocked Boolean | A true/false boolean indicating if the Story is currently blocked. |
blocker Boolean | A true/false boolean indicating if the Story is currently a blocker of another story. |
branches Array [Branch] | An array of Git branches attached to the story. |
comments Array [StoryComment] | An array of comments attached to the story. |
commits Array [Commit] | An array of commits attached to the story. |
completed Boolean | A true/false boolean indicating if the Story has been completed. |
completed_at Date or null | The time/date the Story was completed. |
completed_at_override Date or null | A manual override for the time/date the Story was completed. |
created_at Date | The time/date the Story was created. |
custom_fields Array [StoryCustomField] | An array of CustomField value assertions for the story. |
cycle_time Integer | The cycle time (in seconds) of this story when complete. |
deadline Date or null | The due date of the story. |
description String | The description of the story. |
entity_type String | A string description of this resource. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_id String or null | 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. |
external_links Array [String] | An array of external links (strings) associated with a Story |
files Array [UploadedFile] | An array of files attached to the story. |
follower_ids Array [UUID] | An array of UUIDs for any Members listed as Followers. |
group_id UUID or null | The ID of the group associated with the story. |
group_mention_ids Array [UUID] | An array of Group IDs that have been mentioned in the Story description. |
id Integer | The unique ID of the Story. |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
label_ids Array [Integer] | An array of label ids attached to the story. |
labels Array [LabelSlim] | An array of labels attached to the story. |
lead_time Integer | The lead time (in seconds) of this story when complete. |
linked_files Array [LinkedFile] | An array of linked files attached to the story. |
member_mention_ids Array [UUID] | An array of Member IDs that have been mentioned in the Story description. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
moved_at Date or null | The time/date the Story was last changed workflow-state. |
name String | The name of the story. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
position Integer | A number representing the position of the story in relation to every other story in the current project. |
previous_iteration_ids Array [Integer] | The IDs of the iteration the story belongs to. |
project_id Integer or null | The ID of the project the story belongs to. |
pull_requests Array [PullRequest] | An array of Pull/Merge Requests attached to the story. |
requested_by_id UUID | The ID of the Member that requested the story. |
started Boolean | A true/false boolean indicating if the Story has been started. |
started_at Date or null | The time/date the Story was started. |
started_at_override Date or null | A manual override for the time/date the Story was started. |
stats StoryStats | The stats object for Stories |
story_links Array [TypedStoryLink] | An array of story links attached to the Story. |
story_template_id UUID or null | The ID of the story template used to create this story, or null if not created using a template. |
story_type String | The type of story (feature, bug, chore). |
synced_item SyncedItem | The synced item for the story. |
tasks Array [Task] | An array of tasks connected to the story. |
unresolved_blocker_comments Array [Integer] | The IDs of any unresolved blocker comments on the Story. |
updated_at Date or null | The time/date the Story was updated. |
workflow_id Integer | The ID of the workflow the story belongs to. |
workflow_state_id Integer | The ID of the workflow state the story is currently in. |
StoryComment
A Comment is any note added within the Comment field of a Story.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Comment. |
author_id UUID or null | The unique ID of the Member who is the Comment’s author. |
blocker Boolean | 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. |
created_at Date | The time/date when the Comment was created. |
deleted Boolean | True/false boolean indicating whether the Comment has been deleted. |
entity_type String | A string description of this resource. |
external_id String or null | 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. |
group_mention_ids Array [UUID] | The unique IDs of the Group who are mentioned in the Comment. |
id Integer | The unique ID of the Comment. |
linked_to_slack Boolean | Whether the Comment is currently the root of a thread that is linked to Slack. |
member_mention_ids Array [UUID] | The unique IDs of the Member who are mentioned in the Comment. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
parent_id Integer or null | The ID of the parent Comment this Comment is threaded under. |
position Integer | The Comments numerical position in the list from oldest to newest. |
story_id Integer | The ID of the Story on which the Comment appears. |
text String or null | The text of the Comment. In the case that the Comment has been deleted, this field can be set to nil. |
unblocks_parent Boolean | 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. |
updated_at Date or null | The time/date when the Comment was updated. |
StoryContents
A container entity for the attributes this template should populate.
Name | Description |
---|---|
custom_fields Array [CustomFieldValueParams] | An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
deadline Date | The due date of the story. |
description String | The description of the story. |
entity_type String | A string description of this resource. |
epic_id Integer | The ID of the epic the story belongs to. |
estimate Integer | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_links Array [String] | An array of external links connected to the story. |
files Array [UploadedFile] | An array of files attached to the story. |
follower_ids Array [UUID] | An array of UUIDs for any Members listed as Followers. |
group_id UUID | The ID of the group to which the story is assigned. |
iteration_id Integer | The ID of the iteration the story belongs to. |
label_ids Array [Integer] | An array of label ids attached to the story. |
labels Array [LabelSlim] | An array of labels attached to the story. |
linked_files Array [LinkedFile] | An array of linked files attached to the story. |
name String | The name of the story. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
project_id Integer | The ID of the project the story belongs to. |
story_type String | The type of story (feature, bug, chore). |
tasks Array [StoryContentsTask] | An array of tasks connected to the story. |
workflow_state_id Integer | The ID of the workflow state the story is currently in. |
StoryContentsTask
Name | Description |
---|---|
complete Boolean | True/false boolean indicating whether the Task has been completed. |
description String | Full text of the Task. |
external_id String or null | 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. |
owner_ids Array [UUID] | An array of UUIDs of the Owners of this Task. |
position Integer | The number corresponding to the Task’s position within a list of Tasks on a Story. |
StoryCustomField
Name | Description |
---|---|
field_id UUID | The unique public ID for a CustomField. |
value String | A string representation of the value, if applicable. |
value_id UUID | The unique public ID for a CustomFieldEnumValue. |
StoryHistoryChangeAddsRemovesInt
Task IDs that have been added or removed from the Story.
Name | Description |
---|---|
adds Array [Integer] | The values that have been added. |
removes Array [Integer] | The values that have been removed |
StoryHistoryChangeAddsRemovesUuid
Custom Field Enum Value IDs that have been added or removed from the Story.
Name | Description |
---|---|
adds Array [UUID] | The values that have been added. |
removes Array [UUID] | The values that have been removed |
StoryHistoryChangeOldNewBool
True if the Story has archived, otherwise false.
Name | Description |
---|---|
new Boolean | The new value. |
old Boolean | The old value. |
StoryHistoryChangeOldNewInt
The estimate value for the Story
Name | Description |
---|---|
new Integer | The new value. |
old Integer | The old value. |
StoryHistoryChangeOldNewStr
A timestamp that represents the Story’s deadline.
Name | Description |
---|---|
new String | The new value. |
old String or null | The old value. |
StoryHistoryChangeOldNewUuid
The Team ID for the Story.
Name | Description |
---|---|
new UUID | The new value. |
old UUID | The old value. |
StoryLink
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”.
Name | Description |
---|---|
created_at Date | The time/date when the Story Link was created. |
entity_type String | A string description of this resource. |
id Integer | The unique identifier of the Story Link. |
object_id Integer | The ID of the object Story. |
subject_id Integer | The ID of the subject Story. |
updated_at Date | The time/date when the Story Link was last updated. |
verb String | How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”. |
StoryReaction
Emoji reaction on a comment.
Name | Description |
---|---|
emoji String | Emoji text of the reaction. |
permission_ids Array [UUID] | Permissions who have reacted with this. |
StorySearchResult
A Story in search results. This is typed differently from Story because the details=slim search argument will omit some fields.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Story. |
archived Boolean | True if the story has been archived or not. |
blocked Boolean | A true/false boolean indicating if the Story is currently blocked. |
blocker Boolean | A true/false boolean indicating if the Story is currently a blocker of another story. |
branches Array [Branch] | An array of Git branches attached to the story. |
comment_ids Array [Integer] | An array of IDs of Comments attached to the story. |
comments Array [StoryComment] | An array of comments attached to the story. |
commits Array [Commit] | An array of commits attached to the story. |
completed Boolean | A true/false boolean indicating if the Story has been completed. |
completed_at Date or null | The time/date the Story was completed. |
completed_at_override Date or null | A manual override for the time/date the Story was completed. |
created_at Date | The time/date the Story was created. |
custom_fields Array [StoryCustomField] | An array of CustomField value assertions for the story. |
cycle_time Integer | The cycle time (in seconds) of this story when complete. |
deadline Date or null | The due date of the story. |
description String | The description of the story. |
entity_type String | A string description of this resource. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_id String or null | 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. |
external_links Array [String] | An array of external links (strings) associated with a Story |
file_ids Array [Integer] | An array of IDs of Files attached to the story. |
files Array [UploadedFile] | An array of files attached to the story. |
follower_ids Array [UUID] | An array of UUIDs for any Members listed as Followers. |
group_id UUID or null | The ID of the group associated with the story. |
group_mention_ids Array [UUID] | An array of Group IDs that have been mentioned in the Story description. |
id Integer | The unique ID of the Story. |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
label_ids Array [Integer] | An array of label ids attached to the story. |
labels Array [LabelSlim] | An array of labels attached to the story. |
lead_time Integer | The lead time (in seconds) of this story when complete. |
linked_file_ids Array [Integer] | An array of IDs of LinkedFiles attached to the story. |
linked_files Array [LinkedFile] | An array of linked files attached to the story. |
member_mention_ids Array [UUID] | An array of Member IDs that have been mentioned in the Story description. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
moved_at Date or null | The time/date the Story was last changed workflow-state. |
name String | The name of the story. |
num_tasks_completed Integer | The number of tasks on the story which are complete. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
position Integer | A number representing the position of the story in relation to every other story in the current project. |
previous_iteration_ids Array [Integer] | The IDs of the iteration the story belongs to. |
project_id Integer or null | The ID of the project the story belongs to. |
pull_requests Array [PullRequest] | An array of Pull/Merge Requests attached to the story. |
requested_by_id UUID | The ID of the Member that requested the story. |
started Boolean | A true/false boolean indicating if the Story has been started. |
started_at Date or null | The time/date the Story was started. |
started_at_override Date or null | A manual override for the time/date the Story was started. |
stats StoryStats | The stats object for Stories |
story_links Array [TypedStoryLink] | An array of story links attached to the Story. |
story_template_id UUID or null | The ID of the story template used to create this story, or null if not created using a template. |
story_type String | The type of story (feature, bug, chore). |
synced_item SyncedItem | The synced item for the story. |
task_ids Array [Integer] | An array of IDs of Tasks attached to the story. |
tasks Array [Task] | An array of tasks connected to the story. |
unresolved_blocker_comments Array [Integer] | The IDs of any unresolved blocker comments on the Story. |
updated_at Date or null | The time/date the Story was updated. |
workflow_id Integer | The ID of the workflow the story belongs to. |
workflow_state_id Integer | The ID of the workflow state the story is currently in. |
StorySearchResults
The results of the Story search query.
Name | Description |
---|---|
data Array [StorySearchResult] | A list of search results. |
next String or null | The URL path and query string for the next page of search results. |
total Integer | The total number of matches for the search query. The first 1000 matches can be paged through via the API. |
StorySlim
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 endpoint to fetch the unabridged payload for a Story.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Story. |
archived Boolean | True if the story has been archived or not. |
blocked Boolean | A true/false boolean indicating if the Story is currently blocked. |
blocker Boolean | A true/false boolean indicating if the Story is currently a blocker of another story. |
comment_ids Array [Integer] | An array of IDs of Comments attached to the story. |
completed Boolean | A true/false boolean indicating if the Story has been completed. |
completed_at Date or null | The time/date the Story was completed. |
completed_at_override Date or null | A manual override for the time/date the Story was completed. |
created_at Date | The time/date the Story was created. |
custom_fields Array [StoryCustomField] | An array of CustomField value assertions for the story. |
cycle_time Integer | The cycle time (in seconds) of this story when complete. |
deadline Date or null | The due date of the story. |
description String | The description of the Story. |
entity_type String | A string description of this resource. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_id String or null | 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. |
external_links Array [String] | An array of external links (strings) associated with a Story |
file_ids Array [Integer] | An array of IDs of Files attached to the story. |
follower_ids Array [UUID] | An array of UUIDs for any Members listed as Followers. |
group_id UUID or null | The ID of the group associated with the story. |
group_mention_ids Array [UUID] | An array of Group IDs that have been mentioned in the Story description. |
id Integer | The unique ID of the Story. |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
label_ids Array [Integer] | An array of label ids attached to the story. |
labels Array [LabelSlim] | An array of labels attached to the story. |
lead_time Integer | The lead time (in seconds) of this story when complete. |
linked_file_ids Array [Integer] | An array of IDs of LinkedFiles attached to the story. |
member_mention_ids Array [UUID] | An array of Member IDs that have been mentioned in the Story description. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
moved_at Date or null | The time/date the Story was last changed workflow-state. |
name String | The name of the story. |
num_tasks_completed Integer | The number of tasks on the story which are complete. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
position Integer | A number representing the position of the story in relation to every other story in the current project. |
previous_iteration_ids Array [Integer] | The IDs of the iteration the story belongs to. |
project_id Integer or null | The ID of the project the story belongs to. |
requested_by_id UUID | The ID of the Member that requested the story. |
started Boolean | A true/false boolean indicating if the Story has been started. |
started_at Date or null | The time/date the Story was started. |
started_at_override Date or null | A manual override for the time/date the Story was started. |
stats StoryStats | The stats object for Stories |
story_links Array [TypedStoryLink] | An array of story links attached to the Story. |
story_template_id UUID or null | The ID of the story template used to create this story, or null if not created using a template. |
story_type String | The type of story (feature, bug, chore). |
synced_item SyncedItem | The synced item for the story. |
task_ids Array [Integer] | An array of IDs of Tasks attached to the story. |
unresolved_blocker_comments Array [Integer] | The IDs of any unresolved blocker comments on the Story. |
updated_at Date or null | The time/date the Story was updated. |
workflow_id Integer | The ID of the workflow the story belongs to. |
workflow_state_id Integer | The ID of the workflow state the story is currently in. |
StoryStats
The stats object for Stories
Name | Description |
---|---|
num_related_documents Integer | The number of documents related to this Story. |
SyncedItem
The synced item for the story.
Name | Description |
---|---|
external_id String | The id used to reference an external entity. |
url String | The url to the external entity. |
Task
A Task on a Story.
Name | Description |
---|---|
complete Boolean | True/false boolean indicating whether the Task has been completed. |
completed_at Date or null | The time/date the Task was completed. |
created_at Date | The time/date the Task was created. |
description String | Full text of the Task. |
entity_type String | A string description of this resource. |
external_id String or null | 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. |
group_mention_ids Array [UUID] | An array of UUIDs of Groups mentioned in this Task. |
id Integer | The unique ID of the Task. |
member_mention_ids Array [UUID] | An array of UUIDs of Members mentioned in this Task. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
owner_ids Array [UUID] | An array of UUIDs of the Owners of this Task. |
position Integer | The number corresponding to the Task’s position within a list of Tasks on a Story. |
story_id Integer | The unique identifier of the parent Story. |
updated_at Date or null | The time/date the Task was updated. |
ThreadedComment
Comments associated with Epic Discussions.
Name | Description |
---|---|
app_url String | The Shortcut application url for the Comment. |
author_id UUID | The unique ID of the Member that authored the Comment. |
comments Array [ThreadedComment] | A nested array of threaded comments. |
created_at Date | The time/date the Comment was created. |
deleted Boolean | True/false boolean indicating whether the Comment is deleted. |
entity_type String | A string description of this resource. |
external_id String or null | 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. |
group_mention_ids Array [UUID] | An array of Group IDs that have been mentioned in this Comment. |
id Integer | The unique ID of the Comment. |
member_mention_ids Array [UUID] | An array of Member IDs that have been mentioned in this Comment. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
text String | The text of the Comment. |
updated_at Date | The time/date the Comment was updated. |
TypedStoryLink
The type of Story Link. The string can be subject or object.
Name | Description |
---|---|
created_at Date | The time/date when the Story Link was created. |
entity_type String | A string description of this resource. |
id Integer | The unique identifier of the Story Link. |
object_id Integer | The ID of the object Story. |
subject_id Integer | The ID of the subject Story. |
type String | This indicates whether the Story is the subject or object in the Story Link. |
updated_at Date | The time/date when the Story Link was last updated. |
verb String | How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”. |
UnusableEntitlementError
Name | Description |
---|---|
entitlement_tag String (63) | Short tag describing the unusable entitlement action taken by the user. |
message String (256) | Message displayed to the user on why their action failed. |
reason_tag Enum (entitlement-violation) | The tag for violating an entitlement action. |
UpdateCategory
Name | Description |
---|---|
archived Boolean | A true/false boolean indicating if the Category has been archived. |
color Color or null | The hex color to be displayed with the Category (for example, “#ff0000”). |
name String | The new name of the Category. |
UpdateComment
Name | Description |
---|---|
text String | The updated comment text. |
UpdateCustomField
Name | Description |
---|---|
after_id UUID | The ID of the CustomField we want to move this CustomField after. |
before_id UUID | The ID of the CustomField we want to move this CustomField before. |
description String | A description of the purpose of this field. |
enabled Boolean | Indicates whether the Field is enabled for the Workspace. Only enabled fields can be applied to Stories. |
icon_set_identifier String (63) | A frontend-controlled string that represents the icon for this custom field. |
name String (63) | A collection of objects representing reporting periods for years. |
values Array [UpdateCustomFieldEnumValue] | A collection of EnumValue objects representing the values in the domain of some Custom Field. |
UpdateCustomFieldEnumValue
Name | Description |
---|---|
color_key String or null | A color key associated with this EnumValue within the CustomField’s domain. |
enabled Boolean | Whether this EnumValue is enabled for its CustomField or not. Leaving this key out of the request leaves the current enabled state untouched. |
id UUID | The unique ID of an existing EnumValue within the CustomField’s domain. |
value String (63) | A string value within the domain of this Custom Field. |
UpdateEntityTemplate
Request parameters for changing either a template’s name or any of
the attributes it is designed to pre-populate.
Name | Description |
---|---|
name String (128) | The updated template name. |
story_contents UpdateStoryContents | Updated attributes for the template to populate. |
UpdateEpic
Name | Description |
---|---|
after_id Integer | The ID of the Epic we want to move this Epic after. |
archived Boolean | A true/false boolean indicating whether the Epic is in archived state. |
before_id Integer | The ID of the Epic we want to move this Epic before. |
completed_at_override Date or null | A manual override for the time/date the Epic was completed. |
deadline Date or null | The Epic’s deadline. |
description String (100000) | The Epic’s description. |
epic_state_id Integer | The ID of the Epic State. |
external_id String (128) | This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers on this Epic. |
group_id UUID or null | Deprecated The ID of the group to associate with the epic. Use group_ids . |
group_ids Array [UUID] | An array of UUIDS for Groups to which this Epic is related. |
labels Array [CreateLabelParams] | An array of Labels attached to the Epic. |
milestone_id Integer or null | Deprecated The ID of the Milestone this Epic is related to. Use objective_ids . |
name String (256) | The Epic’s name. |
objective_ids Array [Integer] | An array of IDs for Objectives to which this Epic is related. |
owner_ids Array [UUID] | An array of UUIDs for any members you want to add as Owners on this Epic. |
planned_start_date Date or null | The Epic’s planned start date. |
requested_by_id UUID | The ID of the member that requested the epic. |
started_at_override Date or null | A manual override for the time/date the Epic was started. |
state Enum (done, in progress, to do) | Deprecated The Epic’s state (to do, in progress, or done); will be ignored when epic_state_id is set. |
UpdateFile
Name | Description |
---|---|
created_at Date | The time/date that the file was uploaded. |
description String (4096) | The description of the file. |
external_id String (128) | An additional ID that you may wish to assign to the file. |
name String (1024) | The name of the file. |
updated_at Date | The time/date that the file was last updated. |
uploader_id UUID | The unique ID assigned to the Member who uploaded the file to Shortcut. |
UpdateGroup
Name | Description |
---|---|
archived Boolean or null | Whether or not this Group is archived. |
color Color or null | The color you wish to use for the Group in the system. |
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) | The color key you wish to use for the Group in the system. |
description String (4096) | The description of this Group. |
display_icon_id UUID or null | The Icon id for the avatar of this Group. |
member_ids Array [UUID] | The Member ids to add to this Group. |
mention_name String (63) | The mention name of this Group. |
name String (63) | The name of this Group. |
workflow_ids Array [Integer] | The Workflow ids to add to the Group. |
UpdateIteration
Name | Description |
---|---|
description String (100000) | The description of the Iteration. |
end_date String | The date this Iteration ends, e.g. 2019-07-05. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers. |
group_ids Array [UUID] | An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI. |
labels Array [CreateLabelParams] | An array of Labels attached to the Iteration. |
name String (256) | The name of this Iteration |
start_date String | The date this Iteration begins, e.g. 2019-07-01 |
UpdateKeyResult
Name | Description |
---|---|
initial_observed_value KeyResultValue | The starting value of the Key Result. |
name String (1024) | The name of the Key Result. |
observed_value KeyResultValue | The starting value of the Key Result. |
target_value KeyResultValue | The starting value of the Key Result. |
UpdateLabel
Name | Description |
---|---|
archived Boolean | A true/false boolean indicating if the Label has been archived. |
color Color or null | The hex color to be displayed with the Label (for example, “#ff0000”). |
description String (1024) | The new description of the label. |
name String (128) | The new name of the label. |
UpdateLinkedFile
Name | Description |
---|---|
description String (512) | The description of the file. |
name String | The name of the file. |
size Integer | The filesize, if the integration provided it. |
story_id Integer | The ID of the linked story. |
thumbnail_url String (2048) | The URL of the thumbnail, if the integration provided it. |
type Enum (box, dropbox, google, onedrive, url) | The integration type of the file (e.g. google, dropbox, box). |
uploader_id UUID | The UUID of the member that uploaded the file. |
url String (2048) | The URL of linked file. |
UpdateMilestone
Name | Description |
---|---|
after_id Integer | The ID of the Milestone we want to move this Milestone after. |
archived Boolean | A boolean indicating whether the Milestone is archived or not |
before_id Integer | The ID of the Milestone we want to move this Milestone before. |
categories Array [CreateCategoryParams] | An array of IDs of Categories attached to the Milestone. |
completed_at_override Date or null | A manual override for the time/date the Milestone was completed. |
description String (100000) | The Milestone’s description. |
name String (256) | The name of the Milestone. |
started_at_override Date or null | A manual override for the time/date the Milestone was started. |
state Enum (done, in progress, to do) | The workflow state that the Milestone is in. |
UpdateObjective
Name | Description |
---|---|
after_id Integer | The ID of the Objective we want to move this Objective after. |
archived Boolean | A boolean indicating whether the Objective is archived or not |
before_id Integer | The ID of the Objective we want to move this Objective before. |
categories Array [CreateCategoryParams] | An array of IDs of Categories attached to the Objective. |
completed_at_override Date or null | A manual override for the time/date the Objective was completed. |
description String (100000) | The Objective’s description. |
name String (256) | The name of the Objective. |
started_at_override Date or null | A manual override for the time/date the Objective was started. |
state Enum (done, in progress, to do) | The workflow state that the Objective is in. |
UpdateProject
Name | Description |
---|---|
abbreviation String | The Project abbreviation used in Story summaries. Should be kept to 3 characters at most. |
archived Boolean | A true/false boolean indicating whether the Story is in archived state. |
color Color | The color that represents the Project in the UI. |
days_to_thermometer Integer | The number of days before the thermometer appears in the Story summary. |
description String (100000) | The Project’s description. |
follower_ids Array [UUID] | An array of UUIDs for any Members you want to add as Followers. |
name String (128) | The Project’s name. |
show_thermometer Boolean | Configuration to enable or disable thermometers in the Story summary. |
team_id Integer | The ID of the team the project belongs to. |
UpdateStories
Name | Description |
---|---|
after_id Integer | The ID of the story that the stories are to be moved below. |
archived Boolean | If the Stories should be archived or not. |
before_id Integer | The ID of the story that the stories are to be moved before. |
custom_fields_add Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
custom_fields_remove Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
deadline Date or null | The due date of the story. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_links Array [String] | An array of External Links associated with this story. |
follower_ids_add Array [UUID] | The UUIDs of the new followers to be added. |
follower_ids_remove Array [UUID] | The UUIDs of the followers to be removed. |
group_id UUID or null | The Id of the Group the Stories should belong to. |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
labels_add Array [CreateLabelParams] | An array of labels to be added. |
labels_remove Array [CreateLabelParams] | An array of labels to be removed. |
move_to Enum (first, last) | One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state. |
owner_ids_add Array [UUID] | The UUIDs of the new owners to be added. |
owner_ids_remove Array [UUID] | The UUIDs of the owners to be removed. |
project_id Integer or null | The ID of the Project the Stories should belong to. |
requested_by_id UUID | The ID of the member that requested the story. |
story_ids Array [Integer] | The Ids of the Stories you wish to update. |
story_type Enum (bug, chore, feature) | The type of story (feature, bug, chore). |
workflow_state_id Integer | The ID of the workflow state to put the stories in. |
UpdateStory
Name | Description |
---|---|
after_id Integer | The ID of the story we want to move this story after. |
archived Boolean | True if the story is archived, otherwise false. |
before_id Integer | The ID of the story we want to move this story before. |
branch_ids Array [Integer] | An array of IDs of Branches attached to the story. |
commit_ids Array [Integer] | An array of IDs of Commits attached to the story. |
completed_at_override Date or null | A manual override for the time/date the Story was completed. |
custom_fields Array [CustomFieldValueParams] | A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
deadline Date or null | The due date of the story. |
description String (100000) | The description of the story. |
epic_id Integer or null | The ID of the epic the story belongs to. |
estimate Integer or null | The numeric point estimate of the story. Can also be null, which means unestimated. |
external_links Array [String] | An array of External Links associated with this story. |
file_ids Array [Integer] | An array of IDs of files attached to the story. |
follower_ids Array [UUID] | An array of UUIDs of the followers of this story. |
group_id UUID or null | The ID of the group to associate with this story |
iteration_id Integer or null | The ID of the iteration the story belongs to. |
labels Array [CreateLabelParams] | An array of labels attached to the story. |
linked_file_ids Array [Integer] | An array of IDs of linked files attached to the story. |
move_to Enum (first, last) | One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state. |
name String (512) | The title of the story. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
project_id Integer or null | The ID of the project the story belongs to. |
pull_request_ids Array [Integer] | An array of IDs of Pull/Merge Requests attached to the story. |
requested_by_id UUID | The ID of the member that requested the story. |
started_at_override Date or null | A manual override for the time/date the Story was started. |
story_type Enum (bug, chore, feature) | The type of story (feature, bug, chore). |
workflow_state_id Integer | The ID of the workflow state to put the story in. |
UpdateStoryComment
Name | Description |
---|---|
text String (100000) | The updated comment text. |
UpdateStoryContents
Updated attributes for the template to populate.
Name | Description |
---|---|
custom_fields Array [CustomFieldValueParams] | An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. |
deadline Date or null | The due date of the story. |
description String | The description of the story. |
epic_id Integer or null | The ID of the epic the to be populated. |
estimate Integer or null | The numeric point estimate to be populated. |
external_links Array [String] | An array of external links to be populated. |
file_ids Array [Integer] | An array of the attached file IDs to be populated. |
follower_ids Array [UUID] | An array of UUIDs for any Members listed as Followers. |
group_id UUID or null | The ID of the group to be populated. |
iteration_id Integer or null | The ID of the iteration the to be populated. |
labels Array [CreateLabelParams] | An array of labels to be populated by the template. |
linked_file_ids Array [Integer] | An array of the linked file IDs to be populated. |
name String | The name of the story. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
project_id Integer or null | The ID of the project the story belongs to. |
story_type String | The type of story (feature, bug, chore). |
tasks Array [BaseTaskParams] | An array of tasks to be populated by the template. |
workflow_state_id Integer or null | The ID of the workflow state to be populated. |
UpdateStoryLink
Name | Description |
---|---|
object_id Integer | The ID of the object Story. |
subject_id Integer | The ID of the subject Story. |
verb Enum (blocks, duplicates, relates to) | The type of link. |
UpdateTask
Name | Description |
---|---|
after_id Integer | Move task after this task ID. |
before_id Integer | Move task before this task ID. |
complete Boolean | A true/false boolean indicating whether the task is complete. |
description String (2048) | The Task’s description. |
owner_ids Array [UUID] | An array of UUIDs of the owners of this story. |
UploadedFile
An UploadedFile is any document uploaded to your Shortcut Workspace. Files attached from a third-party service are different: see the Linked Files endpoint.
Name | Description |
---|---|
content_type String | Free form string corresponding to a text or image file. |
created_at Date | The time/date that the file was created. |
description String or null | The description of the file. |
entity_type String | A string description of this resource. |
external_id String or null | 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. |
filename String | The name assigned to the file in Shortcut upon upload. |
group_mention_ids Array [UUID] | The unique IDs of the Groups who are mentioned in the file description. |
id Integer | The unique ID for the file. |
member_mention_ids Array [UUID] | The unique IDs of the Members who are mentioned in the file description. |
mention_ids Array [UUID] | Deprecated: use member_mention_ids . |
name String | The optional User-specified name of the file. |
size Integer | The size of the file. |
story_ids Array [Integer] | The unique IDs of the Stories associated with this file. |
thumbnail_url String or null | The url where the thumbnail of the file can be found in Shortcut. |
updated_at Date or null | The time/date that the file was updated. |
uploader_id UUID | The unique ID of the Member who uploaded the file. |
url String or null | The URL for the file. |
Workflow
Workflow is the array of defined Workflow States. Workflow can be queried using the API but must be updated in the Shortcut UI.
Name | Description |
---|---|
auto_assign_owner Boolean | Indicates if an owner is automatically assigned when an unowned story is started. |
created_at Date | The date the Workflow was created. |
default_state_id Integer | The unique ID of the default state that new Stories are entered into. |
description String | A description of the workflow. |
entity_type String | A string description of this resource. |
id Integer | The unique ID of the Workflow. |
name String | The name of the workflow. |
project_ids Array [Integer] | An array of IDs of projects within the Workflow. |
states Array [WorkflowState] | A map of the states in this Workflow. |
team_id Integer | The ID of the team the workflow belongs to. |
updated_at Date | The date the Workflow was updated. |
WorkflowState
Workflow State is any of the at least 3 columns. Workflow States correspond to one of 3 types: Unstarted, Started, or Done.
Name | Description |
---|---|
color Color | The hex color for this Workflow State. |
created_at Date | The time/date the Workflow State was created. |
description String | The description of what sort of Stories belong in that Workflow state. |
entity_type String | A string description of this resource. |
id Integer | The unique ID of the Workflow State. |
name String | The Workflow State’s name. |
num_stories Integer | The number of Stories currently in that Workflow State. |
num_story_templates Integer | The number of Story Templates associated with that Workflow State. |
position Integer | The position that the Workflow State is in, starting with 0 at the left. |
type String | The type of Workflow State (Unstarted, Started, or Finished) |
updated_at Date | When the Workflow State was last updated. |
verb String or null | The verb that triggers a move to that Workflow State when making VCS commits. |