Last updated: Saturday, December 21, 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 to shortcut.com domains instead,
  even if you made the request to api.clubhouse.io.

Updating your application

To update your application or scripts, you should:

1. Change your Clubhouse-Token header to Shortcut-Token. You can do this today.
2. 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.)
3. Change the API URL from https://api.clubhouse.io to https://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",
    "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",
    "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",
    "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",
    "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",
    "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"
  }
]

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.

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",
    "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",
      "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",
    "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",
  "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",
    "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",
    "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",
  "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",
    "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",
  "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",
  "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	This field is deprecated, and will always be false.
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.

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.

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.

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.

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.

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.

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.”

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.

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.

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).
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).
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).
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.

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.

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.

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.

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.

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.