NAV
API Documentation:


Last updated: Wednesday, November 20, 2024

We changed our name!

Clubhouse is now called Shortcut!

Changes to the REST API

This changes some things about the REST API:

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",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }
]

URL Parameters

Name Description
epic-public-id Integer Required. The unique ID of the Epic.

URL Query Params Parameters

Name Description
includes_description Boolean A true/false boolean indicating whether to return Stories with their descriptions.

Responses

Code Description
200 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

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 Stories which have a given External Link associated with them.

Definition

GET https://api.app.shortcut.com/api/v3/external-link/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/external-link/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value": "foo",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "cycle_time": 123,
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "external_links": [],
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "lead_time": 123,
    "linked_file_ids": [123],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_tasks_completed": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "previous_iteration_ids": [123],
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stats": {
      "num_related_documents": 123
    },
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_template_id": "12345678-9012-3456-7890-123456789012",
    "story_type": "foo",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }
]

URL Query Params Parameters

Name Description
external_link String (2048) Required. The external link associated with one or more stories.

Responses

Code Description
200 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Files

List Files

List Files returns a list of all UploadedFiles in the workspace.

Definition

GET https://api.app.shortcut.com/api/v3/files

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/files"

Example Response

[
  {
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "filename": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }
]

Responses

Code Description
200 [ UploadedFile, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Upload Files

Upload Files uploads one or many files and optionally associates them with a story.
Use the multipart/form-data content-type to upload.
Each file key should contain a separate file.
Each UploadedFile’s name comes from the Content-Disposition header “filename” directive for that field.

Definition

POST https://api.app.shortcut.com/api/v3/files

Example Request

curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -F 'story_id=123' \
  -F 'file0=@/path/to/file.gif;filename=myFileNameOverride.gif' \
  -L "https://api.app.shortcut.com/api/v3/files"

Example Response

[
  {
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "filename": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }
]

Form Parameters

Name Description
story_id Integer The story ID that these files will be associated with.
file0 File Required. A file upload. At least one is required.
file1 File Optional additional files.
file2 File Optional additional files.
file3 File Optional additional files.

Responses

Code Description
201 [ UploadedFile, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get File

Get File returns information about the selected UploadedFile.

Definition

GET https://api.app.shortcut.com/api/v3/files/{file-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/files/{file-public-id}"

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "filename": "foo",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "size": 123,
  "story_ids": [123],
  "thumbnail_url": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "url": "foo"
}

URL Parameters

Name Description
file-public-id Integer Required. The File’s unique ID.

Responses

Code Description
200 UploadedFile
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update File

Update File updates the properties of an UploadedFile (but not its content).

Definition

PUT https://api.app.shortcut.com/api/v3/files/{file-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "created_at": "2016-12-31T12:30:00Z", "description": null, "external_id": null, "name": null, "updated_at": "2016-12-31T12:30:00Z", "uploader_id": "12345678-9012-3456-7890-123456789012" }' \
  -L "https://api.app.shortcut.com/api/v3/files/{file-public-id}"

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "filename": "foo",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "size": 123,
  "story_ids": [123],
  "thumbnail_url": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "url": "foo"
}

URL Parameters

Name Description
file-public-id Integer Required. The unique ID assigned to the file in Shortcut.

Body Parameters

Name Description
created_at Date The time/date that the file was uploaded.
description String (4096) The description of the file.
external_id String (128) An additional ID that you may wish to assign to the file.
name String (1024) The name of the file.
updated_at Date The time/date that the file was last updated.
uploader_id UUID The unique ID assigned to the Member who uploaded the file to Shortcut.

Responses

Code Description
200 UploadedFile
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete File

Delete File deletes a previously uploaded file.

Definition

DELETE https://api.app.shortcut.com/api/v3/files/{file-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/files/{file-public-id}"

URL Parameters

Name Description
file-public-id Integer Required. The File’s unique ID.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Groups

List Groups

A group in our API maps to a “Team” within the Shortcut Product. A Team is a collection of Users that can be associated to Stories, Epics, and Iterations within Shortcut.

Definition

GET https://api.app.shortcut.com/api/v3/groups

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/groups"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "description": "foo",
    "display_icon": {
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": "12345678-9012-3456-7890-123456789012",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo"
    },
    "entity_type": "foo",
    "id": "12345678-9012-3456-7890-123456789012",
    "member_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_name": "foo",
    "name": "foo",
    "num_epics_started": 123,
    "num_stories": 123,
    "num_stories_backlog": 123,
    "num_stories_started": 123,
    "workflow_ids": [123]
  }
]

Responses

Code Description
200 [ Group, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Group

Definition

POST https://api.app.shortcut.com/api/v3/groups

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "color": "#6515dd", "color_key": "black", "description": null, "display_icon_id": "12345678-9012-3456-7890-123456789012", "member_ids": ["12345678-9012-3456-7890-123456789012"], "mention_name": null, "name": null, "workflow_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v3/groups"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "color_key": "black",
  "description": "foo",
  "display_icon": {
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": "12345678-9012-3456-7890-123456789012",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  },
  "entity_type": "foo",
  "id": "12345678-9012-3456-7890-123456789012",
  "member_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_name": "foo",
  "name": "foo",
  "num_epics_started": 123,
  "num_stories": 123,
  "num_stories_backlog": 123,
  "num_stories_started": 123,
  "workflow_ids": [123]
}

Body Parameters

Name Description
color Color The color you wish to use for the Group in the system.
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) The color key you wish to use for the Group in the system.
description String (4096) The description of the Group.
display_icon_id UUID The Icon id for the avatar of this Group.
member_ids Array [UUID] The Member ids to add to this Group.
mention_name String (63) Required. The mention name of this Group.
name String (63) Required. The name of this Group.
workflow_ids Array [Integer] The Workflow ids to add to the Group.

Responses

Code Description
201 Group
400 Schema mismatch
403 UnusableEntitlementError
404 Resource does not exist
422 Unprocessable

Get Group

Definition

GET https://api.app.shortcut.com/api/v3/groups/{group-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/groups/{group-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "color_key": "black",
  "description": "foo",
  "display_icon": {
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": "12345678-9012-3456-7890-123456789012",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  },
  "entity_type": "foo",
  "id": "12345678-9012-3456-7890-123456789012",
  "member_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_name": "foo",
  "name": "foo",
  "num_epics_started": 123,
  "num_stories": 123,
  "num_stories_backlog": 123,
  "num_stories_started": 123,
  "workflow_ids": [123]
}

URL Parameters

Name Description
group-public-id UUID Required. The unique ID of the Group.

Responses

Code Description
200 Group
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Group

Definition

PUT https://api.app.shortcut.com/api/v3/groups/{group-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "color": "#6515dd", "color_key": "black", "description": null, "display_icon_id": "12345678-9012-3456-7890-123456789012", "member_ids": ["12345678-9012-3456-7890-123456789012"], "mention_name": null, "name": null, "workflow_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v3/groups/{group-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "color_key": "black",
  "description": "foo",
  "display_icon": {
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": "12345678-9012-3456-7890-123456789012",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  },
  "entity_type": "foo",
  "id": "12345678-9012-3456-7890-123456789012",
  "member_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_name": "foo",
  "name": "foo",
  "num_epics_started": 123,
  "num_stories": 123,
  "num_stories_backlog": 123,
  "num_stories_started": 123,
  "workflow_ids": [123]
}

URL Parameters

Name Description
group-public-id UUID Required. The unique ID of the Group.

Body Parameters

Name Description
archived Boolean or null Whether or not this Group is archived.
color Color or null The color you wish to use for the Group in the system.
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) The color key you wish to use for the Group in the system.
description String (4096) The description of this Group.
display_icon_id UUID or null The Icon id for the avatar of this Group.
member_ids Array [UUID] The Member ids to add to this Group.
mention_name String (63) The mention name of this Group.
name String (63) The name of this Group.
workflow_ids Array [Integer] The Workflow ids to add to the Group.

Responses

Code Description
200 Group
400 Schema mismatch
403 UnusableEntitlementError
404 Resource does not exist
422 Unprocessable

List Group Stories

List the Stories assigned to the Group. (By default, limited to 1,000).

Definition

GET https://api.app.shortcut.com/api/v3/groups/{group-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/groups/{group-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value": "foo",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "cycle_time": 123,
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "external_links": [],
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "lead_time": 123,
    "linked_file_ids": [123],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_tasks_completed": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "previous_iteration_ids": [123],
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stats": {
      "num_related_documents": 123
    },
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_template_id": "12345678-9012-3456-7890-123456789012",
    "story_type": "foo",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }
]

URL Parameters

Name Description
group-public-id UUID Required. The unique ID of the Group.

URL Query Params Parameters

Name Description
limit Integer The maximum number of results to return. (Defaults to 1000, max 1000)
offset Integer The offset at which to begin returning results. (Defaults to 0)

Responses

Code Description
200 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Iterations

List Iterations

Definition

GET https://api.app.shortcut.com/api/v3/iterations

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/iterations"

Example Response

[
  {
    "app_url": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "end_date": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "stats": {
        "num_epics": 123,
        "num_epics_completed": 123,
        "num_epics_in_progress": 123,
        "num_epics_total": 123,
        "num_epics_unstarted": 123,
        "num_points_backlog": 123,
        "num_points_completed": 123,
        "num_points_in_progress": 123,
        "num_points_total": 123,
        "num_points_unstarted": 123,
        "num_related_documents": 123,
        "num_stories_backlog": 123,
        "num_stories_completed": 123,
        "num_stories_in_progress": 123,
        "num_stories_total": 123,
        "num_stories_unestimated": 123,
        "num_stories_unstarted": 123
      },
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "start_date": "2016-12-31T12:30:00Z",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "num_points": 123,
      "num_points_backlog": 123,
      "num_points_done": 123,
      "num_points_started": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_done": 123,
      "num_stories_started": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "status": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

Responses

Code Description
200 [ IterationSlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Iteration

Definition

POST https://api.app.shortcut.com/api/v3/iterations

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "description": null, "end_date": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_ids": ["12345678-9012-3456-7890-123456789012"], "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "name": null, "start_date": "foo" }' \
  -L "https://api.app.shortcut.com/api/v3/iterations"

Example Response

{
  "app_url": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "end_date": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "label_ids": [123],
  "labels": [{
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_epics_completed": 123,
      "num_epics_in_progress": 123,
      "num_epics_total": 123,
      "num_epics_unstarted": 123,
      "num_points_backlog": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "start_date": "2016-12-31T12:30:00Z",
  "stats": {
    "average_cycle_time": 123,
    "average_lead_time": 123,
    "num_points": 123,
    "num_points_backlog": 123,
    "num_points_done": 123,
    "num_points_started": 123,
    "num_points_unstarted": 123,
    "num_related_documents": 123,
    "num_stories_backlog": 123,
    "num_stories_done": 123,
    "num_stories_started": 123,
    "num_stories_unestimated": 123,
    "num_stories_unstarted": 123
  },
  "status": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

Body Parameters

Name Description
description String (100000) The description of the Iteration.
end_date String Required. The date this Iteration ends, e.g. 2019-07-01.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers.
group_ids Array [UUID] An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
labels Array [CreateLabelParams] An array of Labels attached to the Iteration.
name String (256) Required. The name of this Iteration.
start_date String Required. The date this Iteration begins, e.g. 2019-07-01.

Responses

Code Description
201 Iteration
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Disable Iterations

Disables Iterations for the current workspace

Definition

PUT https://api.app.shortcut.com/api/v3/iterations/disable

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/iterations/disable"

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Enable Iterations

Enables Iterations for the current workspace

Definition

PUT https://api.app.shortcut.com/api/v3/iterations/enable

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/iterations/enable"

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Iteration

Definition

GET https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}"

Example Response

{
  "app_url": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "end_date": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "label_ids": [123],
  "labels": [{
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_epics_completed": 123,
      "num_epics_in_progress": 123,
      "num_epics_total": 123,
      "num_epics_unstarted": 123,
      "num_points_backlog": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "start_date": "2016-12-31T12:30:00Z",
  "stats": {
    "average_cycle_time": 123,
    "average_lead_time": 123,
    "num_points": 123,
    "num_points_backlog": 123,
    "num_points_done": 123,
    "num_points_started": 123,
    "num_points_unstarted": 123,
    "num_related_documents": 123,
    "num_stories_backlog": 123,
    "num_stories_done": 123,
    "num_stories_started": 123,
    "num_stories_unestimated": 123,
    "num_stories_unstarted": 123
  },
  "status": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
iteration-public-id Integer Required. The unique ID of the Iteration.

Responses

Code Description
200 Iteration
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Iteration

Definition

PUT https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "description": null, "end_date": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_ids": ["12345678-9012-3456-7890-123456789012"], "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "name": null, "start_date": "foo" }' \
  -L "https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}"

Example Response

{
  "app_url": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "end_date": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "label_ids": [123],
  "labels": [{
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_epics_completed": 123,
      "num_epics_in_progress": 123,
      "num_epics_total": 123,
      "num_epics_unstarted": 123,
      "num_points_backlog": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "start_date": "2016-12-31T12:30:00Z",
  "stats": {
    "average_cycle_time": 123,
    "average_lead_time": 123,
    "num_points": 123,
    "num_points_backlog": 123,
    "num_points_done": 123,
    "num_points_started": 123,
    "num_points_unstarted": 123,
    "num_related_documents": 123,
    "num_stories_backlog": 123,
    "num_stories_done": 123,
    "num_stories_started": 123,
    "num_stories_unestimated": 123,
    "num_stories_unstarted": 123
  },
  "status": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
iteration-public-id Integer Required. The unique ID of the Iteration.

Body Parameters

Name Description
description String (100000) The description of the Iteration.
end_date String The date this Iteration ends, e.g. 2019-07-05.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers.
group_ids Array [UUID] An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
labels Array [CreateLabelParams] An array of Labels attached to the Iteration.
name String (256) The name of this Iteration
start_date String The date this Iteration begins, e.g. 2019-07-01

Responses

Code Description
200 Iteration
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Iteration

Definition

DELETE https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}"

URL Parameters

Name Description
iteration-public-id Integer Required. The unique ID of the Iteration.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Iteration Stories

Get a list of all Stories in an Iteration.

Definition

GET https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/iterations/{iteration-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value": "foo",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "cycle_time": 123,
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "external_links": [],
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "lead_time": 123,
    "linked_file_ids": [123],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_tasks_completed": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "previous_iteration_ids": [123],
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stats": {
      "num_related_documents": 123
    },
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_template_id": "12345678-9012-3456-7890-123456789012",
    "story_type": "foo",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }
]

URL Parameters

Name Description
iteration-public-id Integer Required. The unique ID of the Iteration.

URL Query Params Parameters

Name Description
includes_description Boolean A true/false boolean indicating whether to return Stories with their descriptions.

Responses

Code Description
200 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Key-Results

Get Key Result

Get Key Result returns information about a chosen Key Result.

Definition

GET https://api.app.shortcut.com/api/v3/key-results/{key-result-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/key-results/{key-result-public-id}"

Example Response

{
  "current_observed_value": {
    "boolean_value": true,
    "numeric_value": "foo"
  },
  "current_target_value": {
    "boolean_value": true,
    "numeric_value": "foo"
  },
  "id": "12345678-9012-3456-7890-123456789012",
  "initial_observed_value": {
    "boolean_value": true,
    "numeric_value": "foo"
  },
  "name": "foo",
  "objective_id": 123,
  "progress": 123,
  "type": "boolean"
}

URL Parameters

Name Description
key-result-public-id UUID Required. The ID of the Key Result.

Responses

Code Description
200 KeyResult
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Key Result

Update Key Result allows updating a Key Result’s name or initial, observed, or target values.

Definition

PUT https://api.app.shortcut.com/api/v3/key-results/{key-result-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "initial_observed_value": { "boolean_value": true, "numeric_value": "foo" }, "name": null, "observed_value": { "boolean_value": true, "numeric_value": "foo" }, "target_value": { "boolean_value": true, "numeric_value": "foo" } }' \
  -L "https://api.app.shortcut.com/api/v3/key-results/{key-result-public-id}"

Example Response

{
  "current_observed_value": {
    "boolean_value": true,
    "numeric_value": "foo"
  },
  "current_target_value": {
    "boolean_value": true,
    "numeric_value": "foo"
  },
  "id": "12345678-9012-3456-7890-123456789012",
  "initial_observed_value": {
    "boolean_value": true,
    "numeric_value": "foo"
  },
  "name": "foo",
  "objective_id": 123,
  "progress": 123,
  "type": "boolean"
}

URL Parameters

Name Description
key-result-public-id UUID Required. The ID of the Key Result.

Body Parameters

Name Description
initial_observed_value KeyResultValue The starting value of the Key Result.
name String (1024) The name of the Key Result.
observed_value KeyResultValue The starting value of the Key Result.
target_value KeyResultValue The starting value of the Key Result.

Responses

Code Description
200 KeyResult
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Labels

List Labels

List Labels returns a list of all Labels and their attributes.

Definition

GET https://api.app.shortcut.com/api/v3/labels

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/labels"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stats": {
      "num_epics": 123,
      "num_epics_completed": 123,
      "num_epics_in_progress": 123,
      "num_epics_total": 123,
      "num_epics_unstarted": 123,
      "num_points_backlog": 123,
      "num_points_completed": 123,
      "num_points_in_progress": 123,
      "num_points_total": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_completed": 123,
      "num_stories_in_progress": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Query Params Parameters

Name Description
slim Boolean A true/false boolean indicating if the slim versions of the Label should be returned.

Responses

Code Description
200 [ Label, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Label

Create Label allows you to create a new Label in Shortcut.

Definition

POST https://api.app.shortcut.com/api/v3/labels

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "color": "#6515dd", "description": null, "external_id": null, "name": null }' \
  -L "https://api.app.shortcut.com/api/v3/labels"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "stats": {
    "num_epics": 123,
    "num_epics_completed": 123,
    "num_epics_in_progress": 123,
    "num_epics_total": 123,
    "num_epics_unstarted": 123,
    "num_points_backlog": 123,
    "num_points_completed": 123,
    "num_points_in_progress": 123,
    "num_points_total": 123,
    "num_points_unstarted": 123,
    "num_related_documents": 123,
    "num_stories_backlog": 123,
    "num_stories_completed": 123,
    "num_stories_in_progress": 123,
    "num_stories_total": 123,
    "num_stories_unestimated": 123,
    "num_stories_unstarted": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

Body Parameters

Name Description
color Color The hex color to be displayed with the Label (for example, “#ff0000”).
description String (1024) The description of the new Label.
external_id String (128) This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here.
name String (128) Required. The name of the new Label.

Responses

Code Description
201 Label
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Label

Get Label returns information about the selected Label.

Definition

GET https://api.app.shortcut.com/api/v3/labels/{label-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "stats": {
    "num_epics": 123,
    "num_epics_completed": 123,
    "num_epics_in_progress": 123,
    "num_epics_total": 123,
    "num_epics_unstarted": 123,
    "num_points_backlog": 123,
    "num_points_completed": 123,
    "num_points_in_progress": 123,
    "num_points_total": 123,
    "num_points_unstarted": 123,
    "num_related_documents": 123,
    "num_stories_backlog": 123,
    "num_stories_completed": 123,
    "num_stories_in_progress": 123,
    "num_stories_total": 123,
    "num_stories_unestimated": 123,
    "num_stories_unstarted": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
label-public-id Integer Required. The unique ID of the Label.

Responses

Code Description
200 Label
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Label

Update Label allows you to replace a Label name with another name. If you try to name a Label something that already exists, you will receive a 422 response.

Definition

PUT https://api.app.shortcut.com/api/v3/labels/{label-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "color": "#6515dd", "description": null, "name": null }' \
  -L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "stats": {
    "num_epics": 123,
    "num_epics_completed": 123,
    "num_epics_in_progress": 123,
    "num_epics_total": 123,
    "num_epics_unstarted": 123,
    "num_points_backlog": 123,
    "num_points_completed": 123,
    "num_points_in_progress": 123,
    "num_points_total": 123,
    "num_points_unstarted": 123,
    "num_related_documents": 123,
    "num_stories_backlog": 123,
    "num_stories_completed": 123,
    "num_stories_in_progress": 123,
    "num_stories_total": 123,
    "num_stories_unestimated": 123,
    "num_stories_unstarted": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
label-public-id Integer Required. The unique ID of the Label you wish to update.

Body Parameters

Name Description
archived Boolean A true/false boolean indicating if the Label has been archived.
color Color or null The hex color to be displayed with the Label (for example, “#ff0000”).
description String (1024) The new description of the label.
name String (128) The new name of the label.

Responses

Code Description
200 Label
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Label

Delete Label can be used to delete any Label.

Definition

DELETE https://api.app.shortcut.com/api/v3/labels/{label-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}"

URL Parameters

Name Description
label-public-id Integer Required. The unique ID of the Label.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Label Epics

List all of the Epics with the Label.

Definition

GET https://api.app.shortcut.com/api/v3/labels/{label-public-id}/epics

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}/epics"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "associated_groups": [{
      "associated_stories_count": 123,
      "group_id": "12345678-9012-3456-7890-123456789012"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_state_id": 123,
    "external_id": "foo",
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "milestone_id": 123,
    "name": "foo",
    "objective_ids": [123],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "planned_start_date": "2016-12-31T12:30:00Z",
    "position": 123,
    "productboard_id": "12345678-9012-3456-7890-123456789012",
    "productboard_name": "foo",
    "productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
    "productboard_url": "foo",
    "project_ids": [123],
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "last_story_update": "2016-12-31T12:30:00Z",
      "num_points": 123,
      "num_points_backlog": 123,
      "num_points_done": 123,
      "num_points_started": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_done": 123,
      "num_stories_started": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "stories_without_projects": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Parameters

Name Description
label-public-id Integer Required. The unique ID of the Label.

Responses

Code Description
200 [ EpicSlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Label Stories

List all of the Stories with the Label.

Definition

GET https://api.app.shortcut.com/api/v3/labels/{label-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/labels/{label-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value": "foo",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "cycle_time": 123,
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "external_links": [],
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "lead_time": 123,
    "linked_file_ids": [123],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_tasks_completed": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "previous_iteration_ids": [123],
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stats": {
      "num_related_documents": 123
    },
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_template_id": "12345678-9012-3456-7890-123456789012",
    "story_type": "foo",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }
]

URL Parameters

Name Description
label-public-id Integer Required. The unique ID of the Label.

URL Query Params Parameters

Name Description
includes_description Boolean A true/false boolean indicating whether to return Stories with their descriptions.

Responses

Code Description
200 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Linked-Files

List Linked Files

List Linked Files returns a list of all Linked-Files and their attributes.

Definition

GET https://api.app.shortcut.com/api/v3/linked-files

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/linked-files"

Example Response

[
  {
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }
]

Responses

Code Description
200 [ LinkedFile, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Linked File

Create Linked File allows you to create a new Linked File in Shortcut.

Definition

POST https://api.app.shortcut.com/api/v3/linked-files

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "content_type": null, "description": null, "name": null, "size": 123, "story_id": 123, "thumbnail_url": null, "type": "box", "uploader_id": "12345678-9012-3456-7890-123456789012", "url": null }' \
  -L "https://api.app.shortcut.com/api/v3/linked-files"

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "size": 123,
  "story_ids": [123],
  "thumbnail_url": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "url": "foo"
}

Body Parameters

Name Description
content_type String (128) The content type of the image (e.g. txt/plain).
description String (512) The description of the file.
name String (256) Required. The name of the file.
size Integer The filesize, if the integration provided it.
story_id Integer The ID of the linked story.
thumbnail_url String (2048) The URL of the thumbnail, if the integration provided it.
type Enum (box, dropbox, google, onedrive, url) Required. The integration type of the file (e.g. google, dropbox, box).
uploader_id UUID The UUID of the member that uploaded the file.
url String (2048) Required. The URL of linked file.

Responses

Code Description
201 LinkedFile
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Linked File

Get File returns information about the selected Linked File.

Definition

GET https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}"

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "size": 123,
  "story_ids": [123],
  "thumbnail_url": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "url": "foo"
}

URL Parameters

Name Description
linked-file-public-id Integer Required. The unique identifier of the linked file.

Responses

Code Description
200 LinkedFile
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Linked File

Updated Linked File allows you to update properties of a previously attached Linked-File.

Definition

PUT https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "description": null, "name": "foo", "size": 123, "story_id": 123, "thumbnail_url": null, "type": "box", "uploader_id": "12345678-9012-3456-7890-123456789012", "url": null }' \
  -L "https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}"

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "size": 123,
  "story_ids": [123],
  "thumbnail_url": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader_id": "12345678-9012-3456-7890-123456789012",
  "url": "foo"
}

URL Parameters

Name Description
linked-file-public-id Integer Required. The unique identifier of the linked file.

Body Parameters

Name Description
description String (512) The description of the file.
name String The name of the file.
size Integer The filesize, if the integration provided it.
story_id Integer The ID of the linked story.
thumbnail_url String (2048) The URL of the thumbnail, if the integration provided it.
type Enum (box, dropbox, google, onedrive, url) The integration type of the file (e.g. google, dropbox, box).
uploader_id UUID The UUID of the member that uploaded the file.
url String (2048) The URL of linked file.

Responses

Code Description
200 LinkedFile
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Linked File

Delete Linked File can be used to delete any previously attached Linked-File.

Definition

DELETE https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/linked-files/{linked-file-public-id}"

URL Parameters

Name Description
linked-file-public-id Integer Required. The unique identifier of the linked file.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Member

Get Current Member Info

Returns information about the authenticated member.

Definition

GET https://api.app.shortcut.com/api/v3/member

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/member"

Example Response

{
  "id": "12345678-9012-3456-7890-123456789012",
  "mention_name": "foo",
  "name": "foo",
  "workspace2": {
    "estimate_scale": [123],
    "url_slug": "foo"
  }
}

Responses

Code Description
200 MemberInfo
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Members

List Members

Returns information about members of the Workspace.

Definition

GET https://api.app.shortcut.com/api/v3/members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "entity_type": "foo",
    "group_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": "12345678-9012-3456-7890-123456789012",
    "profile": {
      "deactivated": true,
      "display_icon": {
        "created_at": "2016-12-31T12:30:00Z",
        "entity_type": "foo",
        "id": "12345678-9012-3456-7890-123456789012",
        "updated_at": "2016-12-31T12:30:00Z",
        "url": "foo"
      },
      "email_address": "foo",
      "entity_type": "foo",
      "gravatar_hash": "foo",
      "id": "12345678-9012-3456-7890-123456789012",
      "is_owner": true,
      "mention_name": "foo",
      "name": "foo",
      "two_factor_auth_activated": true
    },
    "role": "foo",
    "state": "disabled",
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Query Params Parameters

Name Description
org-public-id UUID The unique ID of the Organization to limit the list to.

Responses

Code Description
200 [ Member, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Member

Returns information about a Member.

Definition

GET https://api.app.shortcut.com/api/v3/members/{member-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/members/{member-public-id}"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "disabled": true,
  "entity_type": "foo",
  "group_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": "12345678-9012-3456-7890-123456789012",
  "profile": {
    "deactivated": true,
    "display_icon": {
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": "12345678-9012-3456-7890-123456789012",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo"
    },
    "email_address": "foo",
    "entity_type": "foo",
    "gravatar_hash": "foo",
    "id": "12345678-9012-3456-7890-123456789012",
    "is_owner": true,
    "mention_name": "foo",
    "name": "foo",
    "two_factor_auth_activated": true
  },
  "role": "foo",
  "state": "disabled",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
member-public-id UUID Required. The Member’s unique ID.

URL Query Params Parameters

Name Description
org-public-id UUID The unique ID of the Organization to limit the lookup to.

Responses

Code Description
200 Member
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Milestones

List Milestones

(Deprecated: Use ‘List Objectives’) List Milestones returns a list of all Milestones and their attributes.

Definition

GET https://api.app.shortcut.com/api/v3/milestones

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/milestones"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "categories": [{
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "id": 123,
    "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "position": 123,
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "num_related_documents": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

Responses

Code Description
200 [ Milestone, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Milestone

(Deprecated: Use ‘Create Objective’) Create Milestone allows you to create a new Milestone in Shortcut.

Definition

POST https://api.app.shortcut.com/api/v3/milestones

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "categories": [{ "color": "#6515dd", "external_id": null, "name": null }], "completed_at_override": "2016-12-31T12:30:00Z", "description": null, "name": null, "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
  -L "https://api.app.shortcut.com/api/v3/milestones"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "categories": [{
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "position": 123,
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "stats": {
    "average_cycle_time": 123,
    "average_lead_time": 123,
    "num_related_documents": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

Body Parameters

Name Description
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Milestone.
completed_at_override Date A manual override for the time/date the Milestone was completed.
description String (100000) The Milestone’s description.
name String (256) Required. The name of the Milestone.
started_at_override Date A manual override for the time/date the Milestone was started.
state Enum (done, in progress, to do) The workflow state that the Milestone is in.

Responses

Code Description
201 Milestone
400 Schema mismatch
403 UnusableEntitlementError
404 Resource does not exist
422 Unprocessable

Get Milestone

(Deprecated: Use ‘Get Objective’) Get Milestone returns information about a chosen Milestone.

Definition

GET https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "categories": [{
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "position": 123,
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "stats": {
    "average_cycle_time": 123,
    "average_lead_time": 123,
    "num_related_documents": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
milestone-public-id Integer Required. The ID of the Milestone.

Responses

Code Description
200 Milestone
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Milestone

(Deprecated: Use ‘Update Objective’) Update Milestone can be used to update Milestone properties.

Definition

PUT https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "after_id": 123, "archived": true, "before_id": 123, "categories": [{ "color": "#6515dd", "external_id": null, "name": null }], "completed_at_override": "2016-12-31T12:30:00Z", "description": null, "name": null, "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
  -L "https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "categories": [{
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "position": 123,
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "stats": {
    "average_cycle_time": 123,
    "average_lead_time": 123,
    "num_related_documents": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
milestone-public-id Integer Required. The ID of the Milestone.

Body Parameters

Name Description
after_id Integer The ID of the Milestone we want to move this Milestone after.
archived Boolean A boolean indicating whether the Milestone is archived or not
before_id Integer The ID of the Milestone we want to move this Milestone before.
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Milestone.
completed_at_override Date or null A manual override for the time/date the Milestone was completed.
description String (100000) The Milestone’s description.
name String (256) The name of the Milestone.
started_at_override Date or null A manual override for the time/date the Milestone was started.
state Enum (done, in progress, to do) The workflow state that the Milestone is in.

Responses

Code Description
200 Milestone
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Milestone

(Deprecated: Use ‘Delete Objective’) Delete Milestone can be used to delete any Milestone.

Definition

DELETE https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}"

URL Parameters

Name Description
milestone-public-id Integer Required. The ID of the Milestone.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Milestone Epics

(Deprecated: Use ‘List Objective Epics’) List all of the Epics within the Milestone.

Definition

GET https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}/epics

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/milestones/{milestone-public-id}/epics"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "associated_groups": [{
      "associated_stories_count": 123,
      "group_id": "12345678-9012-3456-7890-123456789012"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_state_id": 123,
    "external_id": "foo",
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "milestone_id": 123,
    "name": "foo",
    "objective_ids": [123],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "planned_start_date": "2016-12-31T12:30:00Z",
    "position": 123,
    "productboard_id": "12345678-9012-3456-7890-123456789012",
    "productboard_name": "foo",
    "productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
    "productboard_url": "foo",
    "project_ids": [123],
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "last_story_update": "2016-12-31T12:30:00Z",
      "num_points": 123,
      "num_points_backlog": 123,
      "num_points_done": 123,
      "num_points_started": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_done": 123,
      "num_stories_started": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "stories_without_projects": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Parameters

Name Description
milestone-public-id Integer Required. The ID of the Milestone.

Responses

Code Description
200 [ EpicSlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Objectives

List Objectives

List Objectives returns a list of all Objectives and their attributes.

Definition

GET https://api.app.shortcut.com/api/v3/objectives

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/objectives"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "categories": [{
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "id": 123,
    "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "position": 123,
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "num_related_documents": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

Responses

Code Description
200 [ Objective, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Objective

Create Objective allows you to create a new Objective in Shortcut.

Definition

POST https://api.app.shortcut.com/api/v3/objectives

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "categories": [{ "color": "#6515dd", "external_id": null, "name": null }], "completed_at_override": "2016-12-31T12:30:00Z", "description": null, "name": null, "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
  -L "https://api.app.shortcut.com/api/v3/objectives"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "categories": [{
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "position": 123,
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "stats": {
    "average_cycle_time": 123,
    "average_lead_time": 123,
    "num_related_documents": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

Body Parameters

Name Description
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Objective.
completed_at_override Date A manual override for the time/date the Objective was completed.
description String (100000) The Objective’s description.
name String (256) Required. The name of the Objective.
started_at_override Date A manual override for the time/date the Objective was started.
state Enum (done, in progress, to do) The workflow state that the Objective is in.

Responses

Code Description
201 Objective
400 Schema mismatch
403 UnusableEntitlementError
404 Resource does not exist
422 Unprocessable

Get Objective

Get Objective returns information about a chosen Objective.

Definition

GET https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "categories": [{
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "position": 123,
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "stats": {
    "average_cycle_time": 123,
    "average_lead_time": 123,
    "num_related_documents": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
objective-public-id Integer Required. The ID of the Objective.

Responses

Code Description
200 Objective
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Objective

Update Objective can be used to update Objective properties.

Definition

PUT https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "after_id": 123, "archived": true, "before_id": 123, "categories": [{ "color": "#6515dd", "external_id": null, "name": null }], "completed_at_override": "2016-12-31T12:30:00Z", "description": null, "name": null, "started_at_override": "2016-12-31T12:30:00Z", "state": "done" }' \
  -L "https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "categories": [{
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "id": 123,
  "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
  "name": "foo",
  "position": 123,
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "foo",
  "stats": {
    "average_cycle_time": 123,
    "average_lead_time": 123,
    "num_related_documents": 123
  },
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
objective-public-id Integer Required. The ID of the Objective.

Body Parameters

Name Description
after_id Integer The ID of the Objective we want to move this Objective after.
archived Boolean A boolean indicating whether the Objective is archived or not
before_id Integer The ID of the Objective we want to move this Objective before.
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Objective.
completed_at_override Date or null A manual override for the time/date the Objective was completed.
description String (100000) The Objective’s description.
name String (256) The name of the Objective.
started_at_override Date or null A manual override for the time/date the Objective was started.
state Enum (done, in progress, to do) The workflow state that the Objective is in.

Responses

Code Description
200 Objective
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Objective

Delete Objective can be used to delete any Objective.

Definition

DELETE https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}"

URL Parameters

Name Description
objective-public-id Integer Required. The ID of the Objective.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Objective Epics

List all of the Epics within the Objective.

Definition

GET https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}/epics

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/objectives/{objective-public-id}/epics"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "associated_groups": [{
      "associated_stories_count": 123,
      "group_id": "12345678-9012-3456-7890-123456789012"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_state_id": 123,
    "external_id": "foo",
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "milestone_id": 123,
    "name": "foo",
    "objective_ids": [123],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "planned_start_date": "2016-12-31T12:30:00Z",
    "position": 123,
    "productboard_id": "12345678-9012-3456-7890-123456789012",
    "productboard_name": "foo",
    "productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
    "productboard_url": "foo",
    "project_ids": [123],
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "last_story_update": "2016-12-31T12:30:00Z",
      "num_points": 123,
      "num_points_backlog": 123,
      "num_points_done": 123,
      "num_points_started": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_done": 123,
      "num_stories_started": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "stories_without_projects": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Parameters

Name Description
objective-public-id Integer Required. The ID of the Objective.

Responses

Code Description
200 [ EpicSlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Projects

List Projects

List Projects returns a list of all Projects and their attributes.

Definition

GET https://api.app.shortcut.com/api/v3/projects

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/projects"

Example Response

[
  {
    "abbreviation": "foo",
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "days_to_thermometer": 123,
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_length": 123,
    "name": "foo",
    "show_thermometer": true,
    "start_time": "2016-12-31T12:30:00Z",
    "stats": {
      "num_points": 123,
      "num_related_documents": 123,
      "num_stories": 123
    },
    "team_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123
  }
]

Responses

Code Description
200 [ Project, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Project

Create Project is used to create a new Shortcut Project.

Definition

POST https://api.app.shortcut.com/api/v3/projects

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "abbreviation": null, "color": "#6515dd", "created_at": "2016-12-31T12:30:00Z", "description": null, "external_id": null, "follower_ids": ["12345678-9012-3456-7890-123456789012"], "iteration_length": 123, "name": null, "start_time": "2016-12-31T12:30:00Z", "team_id": 123, "updated_at": "2016-12-31T12:30:00Z" }' \
  -L "https://api.app.shortcut.com/api/v3/projects"

Example Response

{
  "abbreviation": "foo",
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "created_at": "2016-12-31T12:30:00Z",
  "days_to_thermometer": 123,
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "iteration_length": 123,
  "name": "foo",
  "show_thermometer": true,
  "start_time": "2016-12-31T12:30:00Z",
  "stats": {
    "num_points": 123,
    "num_related_documents": 123,
    "num_stories": 123
  },
  "team_id": 123,
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_id": 123
}

Body Parameters

Name Description
abbreviation String (63) The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.
color Color The color you wish to use for the Project in the system.
created_at Date Defaults to the time/date it is created but can be set to reflect another date.
description String (100000) The Project description.
external_id String (128) This field can be set to another unique ID. In the case that the Project has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Epic.
iteration_length Integer The number of weeks per iteration in this Project.
name String (128) Required. The name of the Project.
start_time Date The date at which the Project was started.
team_id Integer Required. The ID of the team the project belongs to.
updated_at Date Defaults to the time/date it is created but can be set to reflect another date.

Responses

Code Description
201 Project
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Project

Get Project returns information about the selected Project.

Definition

GET https://api.app.shortcut.com/api/v3/projects/{project-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/projects/{project-public-id}"

Example Response

{
  "abbreviation": "foo",
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "created_at": "2016-12-31T12:30:00Z",
  "days_to_thermometer": 123,
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "iteration_length": 123,
  "name": "foo",
  "show_thermometer": true,
  "start_time": "2016-12-31T12:30:00Z",
  "stats": {
    "num_points": 123,
    "num_related_documents": 123,
    "num_stories": 123
  },
  "team_id": 123,
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_id": 123
}

URL Parameters

Name Description
project-public-id Integer Required. The unique ID of the Project.

Responses

Code Description
200 Project
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Project

Update Project can be used to change properties of a Project.

Definition

PUT https://api.app.shortcut.com/api/v3/projects/{project-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "abbreviation": "foo", "archived": true, "color": "#6515dd", "days_to_thermometer": 123, "description": null, "follower_ids": ["12345678-9012-3456-7890-123456789012"], "name": null, "show_thermometer": true, "team_id": 123 }' \
  -L "https://api.app.shortcut.com/api/v3/projects/{project-public-id}"

Example Response

{
  "abbreviation": "foo",
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "created_at": "2016-12-31T12:30:00Z",
  "days_to_thermometer": 123,
  "description": "foo",
  "entity_type": "foo",
  "external_id": "foo",
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "iteration_length": 123,
  "name": "foo",
  "show_thermometer": true,
  "start_time": "2016-12-31T12:30:00Z",
  "stats": {
    "num_points": 123,
    "num_related_documents": 123,
    "num_stories": 123
  },
  "team_id": 123,
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_id": 123
}

URL Parameters

Name Description
project-public-id Integer Required. The unique ID of the Project.

Body Parameters

Name Description
abbreviation String The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.
archived Boolean A true/false boolean indicating whether the Story is in archived state.
color Color The color that represents the Project in the UI.
days_to_thermometer Integer The number of days before the thermometer appears in the Story summary.
description String (100000) The Project’s description.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers.
name String (128) The Project’s name.
show_thermometer Boolean Configuration to enable or disable thermometers in the Story summary.
team_id Integer The ID of the team the project belongs to.

Responses

Code Description
200 Project
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Project

Delete Project can be used to delete a Project. Projects can only be deleted if all associated Stories are moved or deleted. In the case that the Project cannot be deleted, you will receive a 422 response.

Definition

DELETE https://api.app.shortcut.com/api/v3/projects/{project-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/projects/{project-public-id}"

URL Parameters

Name Description
project-public-id Integer Required. The unique ID of the Project.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Stories

List Stories returns a list of all Stories in a selected Project and their attributes.

Definition

GET https://api.app.shortcut.com/api/v3/projects/{project-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/projects/{project-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value": "foo",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "cycle_time": 123,
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "external_links": [],
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "lead_time": 123,
    "linked_file_ids": [123],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_tasks_completed": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "previous_iteration_ids": [123],
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stats": {
      "num_related_documents": 123
    },
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_template_id": "12345678-9012-3456-7890-123456789012",
    "story_type": "foo",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }
]

URL Parameters

Name Description
project-public-id Integer Required. The unique ID of the Project.

URL Query Params Parameters

Name Description
includes_description Boolean A true/false boolean indicating whether to return Stories with their descriptions.

Responses

Code Description
200 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Repositories

List Repositories

List Repositories returns a list of all Repositories and their attributes.

Definition

GET https://api.app.shortcut.com/api/v3/repositories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/repositories"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "external_id": "foo",
    "full_name": "foo",
    "id": 123,
    "name": "foo",
    "type": "bitbucket",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }
]

Responses

Code Description
200 [ Repository, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Repository

Get Repository returns information about the selected Repository.

Definition

GET https://api.app.shortcut.com/api/v3/repositories/{repo-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/repositories/{repo-public-id}"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "foo",
  "external_id": "foo",
  "full_name": "foo",
  "id": 123,
  "name": "foo",
  "type": "bitbucket",
  "updated_at": "2016-12-31T12:30:00Z",
  "url": "foo"
}

URL Parameters

Name Description
repo-public-id Integer Required. The unique ID of the Repository.

Responses

Code Description
200 Repository
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Search

Search

Search lets you search Epics and Stories based on desired parameters. Since ordering of the results can change over time (due to search ranking decay, new Epics and Stories being created), the next value from the previous response can be used as the path and query string for the next page to ensure stable ordering.

Definition

GET https://api.app.shortcut.com/api/v3/search

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/search"

Example Response

{
  "epics": {
    "data": [{
      "app_url": "foo",
      "archived": true,
      "associated_groups": [{
        "associated_stories_count": 123,
        "group_id": "12345678-9012-3456-7890-123456789012"
      }],
      "comments": [{
        "app_url": "foo",
        "author_id": "12345678-9012-3456-7890-123456789012",
        "comments": [Recursive],
        "created_at": "2016-12-31T12:30:00Z",
        "deleted": true,
        "entity_type": "foo",
        "external_id": "foo",
        "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "id": 123,
        "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "text": "foo",
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "completed": true,
      "completed_at": "2016-12-31T12:30:00Z",
      "completed_at_override": "2016-12-31T12:30:00Z",
      "created_at": "2016-12-31T12:30:00Z",
      "deadline": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "epic_state_id": 123,
      "external_id": "foo",
      "follower_ids": ["12345678-9012-3456-7890-123456789012"],
      "group_id": "12345678-9012-3456-7890-123456789012",
      "group_ids": ["12345678-9012-3456-7890-123456789012"],
      "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "id": 123,
      "label_ids": [123],
      "labels": [{
        "app_url": "foo",
        "archived": true,
        "color": "#6515dd",
        "created_at": "2016-12-31T12:30:00Z",
        "description": "foo",
        "entity_type": "foo",
        "external_id": "foo",
        "id": 123,
        "name": "foo",
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "milestone_id": 123,
      "name": "foo",
      "objective_ids": [123],
      "owner_ids": ["12345678-9012-3456-7890-123456789012"],
      "planned_start_date": "2016-12-31T12:30:00Z",
      "position": 123,
      "productboard_id": "12345678-9012-3456-7890-123456789012",
      "productboard_name": "foo",
      "productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
      "productboard_url": "foo",
      "project_ids": [123],
      "requested_by_id": "12345678-9012-3456-7890-123456789012",
      "started": true,
      "started_at": "2016-12-31T12:30:00Z",
      "started_at_override": "2016-12-31T12:30:00Z",
      "state": "foo",
      "stats": {
        "average_cycle_time": 123,
        "average_lead_time": 123,
        "last_story_update": "2016-12-31T12:30:00Z",
        "num_points": 123,
        "num_points_backlog": 123,
        "num_points_done": 123,
        "num_points_started": 123,
        "num_points_unstarted": 123,
        "num_related_documents": 123,
        "num_stories_backlog": 123,
        "num_stories_done": 123,
        "num_stories_started": 123,
        "num_stories_total": 123,
        "num_stories_unestimated": 123,
        "num_stories_unstarted": 123
      },
      "stories_without_projects": 123,
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "next": "foo",
    "total": 123
  },
  "iterations": {
    "data": [{
      "app_url": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "end_date": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "follower_ids": ["12345678-9012-3456-7890-123456789012"],
      "group_ids": ["12345678-9012-3456-7890-123456789012"],
      "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "id": 123,
      "label_ids": [123],
      "labels": [{
        "app_url": "foo",
        "archived": true,
        "color": "#6515dd",
        "created_at": "2016-12-31T12:30:00Z",
        "description": "foo",
        "entity_type": "foo",
        "external_id": "foo",
        "id": 123,
        "name": "foo",
        "stats": {
          "num_epics": 123,
          "num_epics_completed": 123,
          "num_epics_in_progress": 123,
          "num_epics_total": 123,
          "num_epics_unstarted": 123,
          "num_points_backlog": 123,
          "num_points_completed": 123,
          "num_points_in_progress": 123,
          "num_points_total": 123,
          "num_points_unstarted": 123,
          "num_related_documents": 123,
          "num_stories_backlog": 123,
          "num_stories_completed": 123,
          "num_stories_in_progress": 123,
          "num_stories_total": 123,
          "num_stories_unestimated": 123,
          "num_stories_unstarted": 123
        },
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "name": "foo",
      "start_date": "2016-12-31T12:30:00Z",
      "stats": {
        "average_cycle_time": 123,
        "average_lead_time": 123,
        "num_points": 123,
        "num_points_backlog": 123,
        "num_points_done": 123,
        "num_points_started": 123,
        "num_points_unstarted": 123,
        "num_related_documents": 123,
        "num_stories_backlog": 123,
        "num_stories_done": 123,
        "num_stories_started": 123,
        "num_stories_unestimated": 123,
        "num_stories_unstarted": 123
      },
      "status": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "next": "foo",
    "total": 123
  },
  "milestones": {
    "data": [{
      "app_url": "foo",
      "archived": true,
      "categories": [{
        "archived": true,
        "color": "#6515dd",
        "created_at": "2016-12-31T12:30:00Z",
        "entity_type": "foo",
        "external_id": "foo",
        "id": 123,
        "name": "foo",
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "completed": true,
      "completed_at": "2016-12-31T12:30:00Z",
      "completed_at_override": "2016-12-31T12:30:00Z",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "id": 123,
      "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
      "name": "foo",
      "position": 123,
      "started": true,
      "started_at": "2016-12-31T12:30:00Z",
      "started_at_override": "2016-12-31T12:30:00Z",
      "state": "foo",
      "stats": {
        "average_cycle_time": 123,
        "average_lead_time": 123,
        "num_related_documents": 123
      },
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "next": "foo",
    "total": 123
  },
  "stories": {
    "data": [{
      "app_url": "foo",
      "archived": true,
      "blocked": true,
      "blocker": true,
      "branches": [{
        "created_at": "2016-12-31T12:30:00Z",
        "deleted": true,
        "entity_type": "foo",
        "id": 123,
        "merged_branch_ids": [123],
        "name": "foo",
        "persistent": true,
        "pull_requests": [{
          "branch_id": 123,
          "branch_name": "foo",
          "build_status": "foo",
          "closed": true,
          "created_at": "2016-12-31T12:30:00Z",
          "draft": true,
          "entity_type": "foo",
          "has_overlapping_stories": true,
          "id": 123,
          "merged": true,
          "num_added": 123,
          "num_commits": 123,
          "num_modified": 123,
          "num_removed": 123,
          "number": 123,
          "overlapping_stories": [123],
          "repository_id": 123,
          "review_status": "foo",
          "target_branch_id": 123,
          "target_branch_name": "foo",
          "title": "foo",
          "updated_at": "2016-12-31T12:30:00Z",
          "url": "foo",
          "vcs_labels": [{
            "color": "#6515dd",
            "description": "foo",
            "entity_type": "foo",
            "id": 123,
            "name": "foo"
          }]
        }],
        "repository_id": 123,
        "updated_at": "2016-12-31T12:30:00Z",
        "url": "foo"
      }],
      "comment_ids": [123],
      "comments": [{
        "app_url": "foo",
        "author_id": "12345678-9012-3456-7890-123456789012",
        "blocker": true,
        "created_at": "2016-12-31T12:30:00Z",
        "deleted": true,
        "entity_type": "foo",
        "external_id": "foo",
        "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "id": 123,
        "linked_to_slack": true,
        "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "parent_id": 123,
        "position": 123,
        "story_id": 123,
        "text": "foo",
        "unblocks_parent": true,
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "commits": [{
        "author_email": "foo",
        "author_id": "12345678-9012-3456-7890-123456789012",
        "author_identity": {
          "entity_type": "foo",
          "name": "foo",
          "type": "bitbucket"
        },
        "created_at": "2016-12-31T12:30:00Z",
        "entity_type": "foo",
        "hash": "foo",
        "id": 123,
        "message": "foo",
        "repository_id": 123,
        "timestamp": "2016-12-31T12:30:00Z",
        "updated_at": "2016-12-31T12:30:00Z",
        "url": "foo"
      }],
      "completed": true,
      "completed_at": "2016-12-31T12:30:00Z",
      "completed_at_override": "2016-12-31T12:30:00Z",
      "created_at": "2016-12-31T12:30:00Z",
      "custom_fields": [{
        "field_id": "12345678-9012-3456-7890-123456789012",
        "value": "foo",
        "value_id": "12345678-9012-3456-7890-123456789012"
      }],
      "cycle_time": 123,
      "deadline": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "epic_id": 123,
      "estimate": 123,
      "external_id": "foo",
      "external_links": [],
      "file_ids": [123],
      "files": [{
        "content_type": "foo",
        "created_at": "2016-12-31T12:30:00Z",
        "description": "foo",
        "entity_type": "foo",
        "external_id": "foo",
        "filename": "foo",
        "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "id": 123,
        "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "name": "foo",
        "size": 123,
        "story_ids": [123],
        "thumbnail_url": "foo",
        "updated_at": "2016-12-31T12:30:00Z",
        "uploader_id": "12345678-9012-3456-7890-123456789012",
        "url": "foo"
      }],
      "follower_ids": ["12345678-9012-3456-7890-123456789012"],
      "group_id": "12345678-9012-3456-7890-123456789012",
      "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "id": 123,
      "iteration_id": 123,
      "label_ids": [123],
      "labels": [{
        "app_url": "foo",
        "archived": true,
        "color": "#6515dd",
        "created_at": "2016-12-31T12:30:00Z",
        "description": "foo",
        "entity_type": "foo",
        "external_id": "foo",
        "id": 123,
        "name": "foo",
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "lead_time": 123,
      "linked_file_ids": [123],
      "linked_files": [{
        "content_type": "foo",
        "created_at": "2016-12-31T12:30:00Z",
        "description": "foo",
        "entity_type": "foo",
        "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "id": 123,
        "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "name": "foo",
        "size": 123,
        "story_ids": [123],
        "thumbnail_url": "foo",
        "type": "foo",
        "updated_at": "2016-12-31T12:30:00Z",
        "uploader_id": "12345678-9012-3456-7890-123456789012",
        "url": "foo"
      }],
      "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "moved_at": "2016-12-31T12:30:00Z",
      "name": "foo",
      "num_tasks_completed": 123,
      "owner_ids": ["12345678-9012-3456-7890-123456789012"],
      "position": 123,
      "previous_iteration_ids": [123],
      "project_id": 123,
      "pull_requests": [{
        "branch_id": 123,
        "branch_name": "foo",
        "build_status": "foo",
        "closed": true,
        "created_at": "2016-12-31T12:30:00Z",
        "draft": true,
        "entity_type": "foo",
        "has_overlapping_stories": true,
        "id": 123,
        "merged": true,
        "num_added": 123,
        "num_commits": 123,
        "num_modified": 123,
        "num_removed": 123,
        "number": 123,
        "overlapping_stories": [123],
        "repository_id": 123,
        "review_status": "foo",
        "target_branch_id": 123,
        "target_branch_name": "foo",
        "title": "foo",
        "updated_at": "2016-12-31T12:30:00Z",
        "url": "foo",
        "vcs_labels": [{
          "color": "#6515dd",
          "description": "foo",
          "entity_type": "foo",
          "id": 123,
          "name": "foo"
        }]
      }],
      "requested_by_id": "12345678-9012-3456-7890-123456789012",
      "started": true,
      "started_at": "2016-12-31T12:30:00Z",
      "started_at_override": "2016-12-31T12:30:00Z",
      "stats": {
        "num_related_documents": 123
      },
      "story_links": [{
        "created_at": "2016-12-31T12:30:00Z",
        "entity_type": "foo",
        "id": 123,
        "object_id": 123,
        "subject_id": 123,
        "type": "foo",
        "updated_at": "2016-12-31T12:30:00Z",
        "verb": "foo"
      }],
      "story_template_id": "12345678-9012-3456-7890-123456789012",
      "story_type": "foo",
      "synced_item": {
        "external_id": "foo",
        "url": "foo"
      },
      "task_ids": [123],
      "tasks": [{
        "complete": true,
        "completed_at": "2016-12-31T12:30:00Z",
        "created_at": "2016-12-31T12:30:00Z",
        "description": "foo",
        "entity_type": "foo",
        "external_id": "foo",
        "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "id": 123,
        "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "mention_ids": ["12345678-9012-3456-7890-123456789012"],
        "owner_ids": ["12345678-9012-3456-7890-123456789012"],
        "position": 123,
        "story_id": 123,
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "unresolved_blocker_comments": [123],
      "updated_at": "2016-12-31T12:30:00Z",
      "workflow_id": 123,
      "workflow_state_id": 123
    }],
    "next": "foo",
    "total": 123
  }
}

URL Query Params Parameters

Name Description
query String Required. See our help center article on search operators
page_size Integer The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail Enum (full, slim) The amount of detail included in each result item.
“full” will include all descriptions and comments and more fields on
related items such as pull requests, branches and tasks.
“slim” omits larger fulltext fields such as descriptions and comments
and only references related items by id.
The default is “full”.
next String The next page token.
entity_types Array [Enum (epic, iteration, milestone, objective, story)] A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

Code Description
200 SearchResults
400 Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError
404 Resource does not exist
422 Unprocessable

Search Epics

Search Epics lets you search Epics based on desired parameters. Since ordering of stories can change over time (due to search ranking decay, new Epics being created), the next value from the previous response can be used as the path and query string for the next page to ensure stable ordering.

Definition

GET https://api.app.shortcut.com/api/v3/search/epics

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/search/epics"

Example Response

{
  "data": [{
    "app_url": "foo",
    "archived": true,
    "associated_groups": [{
      "associated_stories_count": 123,
      "group_id": "12345678-9012-3456-7890-123456789012"
    }],
    "comments": [{
      "app_url": "foo",
      "author_id": "12345678-9012-3456-7890-123456789012",
      "comments": [Recursive],
      "created_at": "2016-12-31T12:30:00Z",
      "deleted": true,
      "entity_type": "foo",
      "external_id": "foo",
      "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "id": 123,
      "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "text": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_state_id": 123,
    "external_id": "foo",
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "milestone_id": 123,
    "name": "foo",
    "objective_ids": [123],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "planned_start_date": "2016-12-31T12:30:00Z",
    "position": 123,
    "productboard_id": "12345678-9012-3456-7890-123456789012",
    "productboard_name": "foo",
    "productboard_plugin_id": "12345678-9012-3456-7890-123456789012",
    "productboard_url": "foo",
    "project_ids": [123],
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "last_story_update": "2016-12-31T12:30:00Z",
      "num_points": 123,
      "num_points_backlog": 123,
      "num_points_done": 123,
      "num_points_started": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_done": 123,
      "num_stories_started": 123,
      "num_stories_total": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "stories_without_projects": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "next": "foo",
  "total": 123
}

URL Query Params Parameters

Name Description
query String Required. See our help center article on search operators
page_size Integer The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail Enum (full, slim) The amount of detail included in each result item.
“full” will include all descriptions and comments and more fields on
related items such as pull requests, branches and tasks.
“slim” omits larger fulltext fields such as descriptions and comments
and only references related items by id.
The default is “full”.
next String The next page token.
entity_types Array [Enum (epic, iteration, milestone, objective, story)] A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

Code Description
200 EpicSearchResults
400 Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError
404 Resource does not exist
422 Unprocessable

Search Iterations

Search Iterations lets you search Iterations based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Iterations being created), the next value from the previous response can be used as the path and query string for the next page to ensure stable ordering.

Definition

GET https://api.app.shortcut.com/api/v3/search/iterations

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/search/iterations"

Example Response

{
  "data": [{
    "app_url": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "end_date": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "stats": {
        "num_epics": 123,
        "num_epics_completed": 123,
        "num_epics_in_progress": 123,
        "num_epics_total": 123,
        "num_epics_unstarted": 123,
        "num_points_backlog": 123,
        "num_points_completed": 123,
        "num_points_in_progress": 123,
        "num_points_total": 123,
        "num_points_unstarted": 123,
        "num_related_documents": 123,
        "num_stories_backlog": 123,
        "num_stories_completed": 123,
        "num_stories_in_progress": 123,
        "num_stories_total": 123,
        "num_stories_unestimated": 123,
        "num_stories_unstarted": 123
      },
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "start_date": "2016-12-31T12:30:00Z",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "num_points": 123,
      "num_points_backlog": 123,
      "num_points_done": 123,
      "num_points_started": 123,
      "num_points_unstarted": 123,
      "num_related_documents": 123,
      "num_stories_backlog": 123,
      "num_stories_done": 123,
      "num_stories_started": 123,
      "num_stories_unestimated": 123,
      "num_stories_unstarted": 123
    },
    "status": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "next": "foo",
  "total": 123
}

URL Query Params Parameters

Name Description
query String Required. See our help center article on search operators
page_size Integer The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail Enum (full, slim) The amount of detail included in each result item.
“full” will include all descriptions and comments and more fields on
related items such as pull requests, branches and tasks.
“slim” omits larger fulltext fields such as descriptions and comments
and only references related items by id.
The default is “full”.
next String The next page token.
entity_types Array [Enum (epic, iteration, milestone, objective, story)] A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

Code Description
200 IterationSearchResults
400 Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError
404 Resource does not exist
422 Unprocessable

Search Milestones

Search Milestones lets you search Milestones based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Milestones being created), the next value from the previous response can be used as the path and query string for the next page to ensure stable ordering.

Definition

GET https://api.app.shortcut.com/api/v3/search/milestones

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/search/milestones"

Example Response

{
  "data": [{
    "app_url": "foo",
    "archived": true,
    "categories": [{
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "id": 123,
    "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "position": 123,
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "num_related_documents": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "next": "foo",
  "total": 123
}

URL Query Params Parameters

Name Description
query String Required. See our help center article on search operators
page_size Integer The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail Enum (full, slim) The amount of detail included in each result item.
“full” will include all descriptions and comments and more fields on
related items such as pull requests, branches and tasks.
“slim” omits larger fulltext fields such as descriptions and comments
and only references related items by id.
The default is “full”.
next String The next page token.
entity_types Array [Enum (epic, iteration, milestone, objective, story)] A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

Code Description
200 ObjectiveSearchResults
400 Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError
404 Resource does not exist
422 Unprocessable

Search Objectives

Search Objectives lets you search Objectives based on desired parameters. Since ordering of results can change over time (due to search ranking decay, new Objectives being created), the next value from the previous response can be used as the path and query string for the next page to ensure stable ordering.

Definition

GET https://api.app.shortcut.com/api/v3/search/objectives

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/search/objectives"

Example Response

{
  "data": [{
    "app_url": "foo",
    "archived": true,
    "categories": [{
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "id": 123,
    "key_result_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "position": 123,
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "foo",
    "stats": {
      "average_cycle_time": 123,
      "average_lead_time": 123,
      "num_related_documents": 123
    },
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "next": "foo",
  "total": 123
}

URL Query Params Parameters

Name Description
query String Required. See our help center article on search operators
page_size Integer The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail Enum (full, slim) The amount of detail included in each result item.
“full” will include all descriptions and comments and more fields on
related items such as pull requests, branches and tasks.
“slim” omits larger fulltext fields such as descriptions and comments
and only references related items by id.
The default is “full”.
next String The next page token.
entity_types Array [Enum (epic, iteration, milestone, objective, story)] A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

Code Description
200 ObjectiveSearchResults
400 Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError
404 Resource does not exist
422 Unprocessable

Search Stories

Search Stories lets you search Stories based on desired parameters. Since ordering of stories can change over time (due to search ranking decay, new stories being created), the next value from the previous response can be used as the path and query string for the next page to ensure stable ordering.

Definition

GET https://api.app.shortcut.com/api/v3/search/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/search/stories"

Example Response

{
  "data": [{
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": [{
      "created_at": "2016-12-31T12:30:00Z",
      "deleted": true,
      "entity_type": "foo",
      "id": 123,
      "merged_branch_ids": [123],
      "name": "foo",
      "persistent": true,
      "pull_requests": [{
        "branch_id": 123,
        "branch_name": "foo",
        "build_status": "foo",
        "closed": true,
        "created_at": "2016-12-31T12:30:00Z",
        "draft": true,
        "entity_type": "foo",
        "has_overlapping_stories": true,
        "id": 123,
        "merged": true,
        "num_added": 123,
        "num_commits": 123,
        "num_modified": 123,
        "num_removed": 123,
        "number": 123,
        "overlapping_stories": [123],
        "repository_id": 123,
        "review_status": "foo",
        "target_branch_id": 123,
        "target_branch_name": "foo",
        "title": "foo",
        "updated_at": "2016-12-31T12:30:00Z",
        "url": "foo",
        "vcs_labels": [{
          "color": "#6515dd",
          "description": "foo",
          "entity_type": "foo",
          "id": 123,
          "name": "foo"
        }]
      }],
      "repository_id": 123,
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo"
    }],
    "comment_ids": [123],
    "comments": [{
      "app_url": "foo",
      "author_id": "12345678-9012-3456-7890-123456789012",
      "blocker": true,
      "created_at": "2016-12-31T12:30:00Z",
      "deleted": true,
      "entity_type": "foo",
      "external_id": "foo",
      "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "id": 123,
      "linked_to_slack": true,
      "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "parent_id": 123,
      "position": 123,
      "story_id": 123,
      "text": "foo",
      "unblocks_parent": true,
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "commits": [{
      "author_email": "foo",
      "author_id": "12345678-9012-3456-7890-123456789012",
      "author_identity": {
        "entity_type": "foo",
        "name": "foo",
        "type": "bitbucket"
      },
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "hash": "foo",
      "id": 123,
      "message": "foo",
      "repository_id": 123,
      "timestamp": "2016-12-31T12:30:00Z",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo"
    }],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value": "foo",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "cycle_time": 123,
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "external_links": [],
    "file_ids": [123],
    "files": [{
      "content_type": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "filename": "foo",
      "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "id": 123,
      "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "name": "foo",
      "size": 123,
      "story_ids": [123],
      "thumbnail_url": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "uploader_id": "12345678-9012-3456-7890-123456789012",
      "url": "foo"
    }],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "lead_time": 123,
    "linked_file_ids": [123],
    "linked_files": [{
      "content_type": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "id": 123,
      "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "name": "foo",
      "size": 123,
      "story_ids": [123],
      "thumbnail_url": "foo",
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "uploader_id": "12345678-9012-3456-7890-123456789012",
      "url": "foo"
    }],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_tasks_completed": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "previous_iteration_ids": [123],
    "project_id": 123,
    "pull_requests": [{
      "branch_id": 123,
      "branch_name": "foo",
      "build_status": "foo",
      "closed": true,
      "created_at": "2016-12-31T12:30:00Z",
      "draft": true,
      "entity_type": "foo",
      "has_overlapping_stories": true,
      "id": 123,
      "merged": true,
      "num_added": 123,
      "num_commits": 123,
      "num_modified": 123,
      "num_removed": 123,
      "number": 123,
      "overlapping_stories": [123],
      "repository_id": 123,
      "review_status": "foo",
      "target_branch_id": 123,
      "target_branch_name": "foo",
      "title": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo",
      "vcs_labels": [{
        "color": "#6515dd",
        "description": "foo",
        "entity_type": "foo",
        "id": 123,
        "name": "foo"
      }]
    }],
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stats": {
      "num_related_documents": 123
    },
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_template_id": "12345678-9012-3456-7890-123456789012",
    "story_type": "foo",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "tasks": [{
      "complete": true,
      "completed_at": "2016-12-31T12:30:00Z",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "id": 123,
      "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "mention_ids": ["12345678-9012-3456-7890-123456789012"],
      "owner_ids": ["12345678-9012-3456-7890-123456789012"],
      "position": 123,
      "story_id": 123,
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }],
  "next": "foo",
  "total": 123
}

URL Query Params Parameters

Name Description
query String Required. See our help center article on search operators
page_size Integer The number of search results to include in a page. Minimum of 1 and maximum of 25.
detail Enum (full, slim) The amount of detail included in each result item.
“full” will include all descriptions and comments and more fields on
related items such as pull requests, branches and tasks.
“slim” omits larger fulltext fields such as descriptions and comments
and only references related items by id.
The default is “full”.
next String The next page token.
entity_types Array [Enum (epic, iteration, milestone, objective, story)] A collection of entity_types to search. Defaults to story and epic. Supports: epic, iteration, objective, story.

Responses

Code Description
200 StorySearchResults
400 Either: (1) Schema mismatch or (2) Maximum of 1000 search results exceeded MaxSearchResultsExceededError
404 Resource does not exist
422 Unprocessable

Stories

Create Story

Create Story is used to add a new story to your Shortcut Workspace.
This endpoint requires that either workflow_state_id or project_id be provided, but will reject the request if both or neither are specified. The workflow_state_id has been marked as required and is the recommended field to specify because we are in the process of sunsetting Projects in Shortcut.

Definition

POST https://api.app.shortcut.com/api/v3/stories

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "comments": [{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": null, "parent_id": 123, "text": null, "updated_at": "2016-12-31T12:30:00Z" }], "completed_at_override": "2016-12-31T12:30:00Z", "created_at": "2016-12-31T12:30:00Z", "custom_fields": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_id": 123, "estimate": 123, "external_id": null, "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "linked_file_ids": [123], "move_to": "first", "name": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "requested_by_id": "12345678-9012-3456-7890-123456789012", "source_task_id": 123, "started_at_override": "2016-12-31T12:30:00Z", "story_links": [{ "object_id": 123, "subject_id": 123, "verb": "blocks" }], "story_template_id": "12345678-9012-3456-7890-123456789012", "story_type": "bug", "tasks": [{ "complete": true, "created_at": "2016-12-31T12:30:00Z", "description": null, "external_id": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "updated_at": "2016-12-31T12:30:00Z" }], "updated_at": "2016-12-31T12:30:00Z", "workflow_state_id": 123 }' \
  -L "https://api.app.shortcut.com/api/v3/stories"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "blocked": true,
  "blocker": true,
  "branches": [{
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "name": "foo",
    "persistent": true,
    "pull_requests": [{
      "branch_id": 123,
      "branch_name": "foo",
      "build_status": "foo",
      "closed": true,
      "created_at": "2016-12-31T12:30:00Z",
      "draft": true,
      "entity_type": "foo",
      "has_overlapping_stories": true,
      "id": 123,
      "merged": true,
      "num_added": 123,
      "num_commits": 123,
      "num_modified": 123,
      "num_removed": 123,
      "number": 123,
      "overlapping_stories": [123],
      "repository_id": 123,
      "review_status": "foo",
      "target_branch_id": 123,
      "target_branch_name": "foo",
      "title": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo",
      "vcs_labels": [{
        "color": "#6515dd",
        "description": "foo",
        "entity_type": "foo",
        "id": 123,
        "name": "foo"
      }]
    }],
    "repository_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "comments": [{
    "app_url": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "blocker": true,
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "linked_to_slack": true,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "parent_id": 123,
    "position": 123,
    "story_id": 123,
    "text": "foo",
    "unblocks_parent": true,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "commits": [{
    "author_email": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "author_identity": {
      "entity_type": "foo",
      "name": "foo",
      "type": "bitbucket"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "hash": "foo",
    "id": 123,
    "message": "foo",
    "repository_id": 123,
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "custom_fields": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value": "foo",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }],
  "cycle_time": 123,
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "epic_id": 123,
  "estimate": 123,
  "external_id": "foo",
  "external_links": [],
  "files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "filename": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_id": "12345678-9012-3456-7890-123456789012",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "iteration_id": 123,
  "label_ids": [123],
  "labels": [{
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "lead_time": 123,
  "linked_files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "moved_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "previous_iteration_ids": [123],
  "project_id": 123,
  "pull_requests": [{
    "branch_id": 123,
    "branch_name": "foo",
    "build_status": "foo",
    "closed": true,
    "created_at": "2016-12-31T12:30:00Z",
    "draft": true,
    "entity_type": "foo",
    "has_overlapping_stories": true,
    "id": 123,
    "merged": true,
    "num_added": 123,
    "num_commits": 123,
    "num_modified": 123,
    "num_removed": 123,
    "number": 123,
    "overlapping_stories": [123],
    "repository_id": 123,
    "review_status": "foo",
    "target_branch_id": 123,
    "target_branch_name": "foo",
    "title": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo",
    "vcs_labels": [{
      "color": "#6515dd",
      "description": "foo",
      "entity_type": "foo",
      "id": 123,
      "name": "foo"
    }]
  }],
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "stats": {
    "num_related_documents": 123
  },
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": 123,
    "object_id": 123,
    "subject_id": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo"
  }],
  "story_template_id": "12345678-9012-3456-7890-123456789012",
  "story_type": "foo",
  "synced_item": {
    "external_id": "foo",
    "url": "foo"
  },
  "tasks": [{
    "complete": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "unresolved_blocker_comments": [123],
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_id": 123,
  "workflow_state_id": 123
}

Body Parameters

Name Description
archived Boolean Controls the story’s archived state.
comments Array [CreateStoryCommentParams] An array of comments to add to the story.
completed_at_override Date A manual override for the time/date the Story was completed.
created_at Date The time/date the Story was created.
custom_fields Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
deadline Date or null The due date of the story.
description String (100000) The description of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_id String (1024) This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
external_links Array [String] An array of External Links associated with this story.
file_ids Array [Integer] An array of IDs of files attached to the story.
follower_ids Array [UUID] An array of UUIDs of the followers of this story.
group_id UUID or null The id of the group to associate with this story.
iteration_id Integer or null The ID of the iteration the story belongs to.
labels Array [CreateLabelParams] An array of labels attached to the story.
linked_file_ids Array [Integer] An array of IDs of linked files attached to the story.
move_to Enum (first, last) One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state.
name String (512) Required. The name of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
project_id Integer or null The ID of the project the story belongs to.
requested_by_id UUID The ID of the member that requested the story.
source_task_id Integer or null Given this story was converted from a task in another story, this is the original task ID that was converted to this story.
started_at_override Date A manual override for the time/date the Story was started.
story_links Array [CreateStoryLinkParams] An array of story links attached to the story.
story_template_id UUID or null The id of the story template used to create this story, if applicable. This is just an association; no content from the story template is inherited by the story simply by setting this field.
story_type Enum (bug, chore, feature) The type of story (feature, bug, chore).
tasks Array [CreateTaskParams] An array of tasks connected to the story.
updated_at Date The time/date the Story was updated.
workflow_state_id Integer The ID of the workflow state the story will be in.

Responses

Code Description
201 Story
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Multiple Stories

Create Multiple Stories allows you to create multiple stories in a single request using the same syntax as Create Story.

Definition

POST https://api.app.shortcut.com/api/v3/stories/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "stories": [{ "archived": true, "comments": [{
    "author_id": "12345678-9012-3456-7890-123456789012",
    "created_at": "2016-12-31T12:30:00Z",
    "external_id": null,
    "parent_id": 123,
    "text": null,
    "updated_at": "2016-12-31T12:30:00Z"
  }], "completed_at_override": "2016-12-31T12:30:00Z", "created_at": "2016-12-31T12:30:00Z", "custom_fields": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value": "foo",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }], "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_id": 123, "estimate": 123, "external_id": null, "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{
    "color": "#6515dd",
    "description": null,
    "external_id": null,
    "name": null
  }], "linked_file_ids": [123], "move_to": "first", "name": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "requested_by_id": "12345678-9012-3456-7890-123456789012", "source_task_id": 123, "started_at_override": "2016-12-31T12:30:00Z", "story_links": [{
    "object_id": 123,
    "subject_id": 123,
    "verb": "blocks"
  }], "story_template_id": "12345678-9012-3456-7890-123456789012", "story_type": "bug", "tasks": [{
    "complete": true,
    "created_at": "2016-12-31T12:30:00Z",
    "description": null,
    "external_id": null,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "updated_at": "2016-12-31T12:30:00Z"
  }], "updated_at": "2016-12-31T12:30:00Z", "workflow_state_id": 123 }] }' \
  -L "https://api.app.shortcut.com/api/v3/stories/bulk"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value": "foo",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "cycle_time": 123,
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "external_links": [],
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "lead_time": 123,
    "linked_file_ids": [123],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_tasks_completed": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "previous_iteration_ids": [123],
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stats": {
      "num_related_documents": 123
    },
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_template_id": "12345678-9012-3456-7890-123456789012",
    "story_type": "foo",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }
]

Body Parameters

Name Description
stories Array [CreateStoryParams] Required. An array of stories to be created.

Responses

Code Description
201 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Multiple Stories

Update Multiple Stories allows you to make changes to numerous stories at once.

Definition

PUT https://api.app.shortcut.com/api/v3/stories/bulk

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "after_id": 123, "archived": true, "before_id": 123, "custom_fields_add": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "custom_fields_remove": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "epic_id": 123, "estimate": 123, "external_links": [], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels_add": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "labels_remove": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "move_to": "first", "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "requested_by_id": "12345678-9012-3456-7890-123456789012", "story_ids": [123], "story_type": "bug", "workflow_state_id": 123 }' \
  -L "https://api.app.shortcut.com/api/v3/stories/bulk"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value": "foo",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "cycle_time": 123,
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "external_links": [],
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "lead_time": 123,
    "linked_file_ids": [123],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_tasks_completed": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "previous_iteration_ids": [123],
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stats": {
      "num_related_documents": 123
    },
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_template_id": "12345678-9012-3456-7890-123456789012",
    "story_type": "foo",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }
]

Body Parameters

Name Description
after_id Integer The ID of the story that the stories are to be moved below.
archived Boolean If the Stories should be archived or not.
before_id Integer The ID of the story that the stories are to be moved before.
custom_fields_add Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
custom_fields_remove Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
deadline Date or null The due date of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_links Array [String] An array of External Links associated with this story.
follower_ids_add Array [UUID] The UUIDs of the new followers to be added.
follower_ids_remove Array [UUID] The UUIDs of the followers to be removed.
group_id UUID or null The Id of the Group the Stories should belong to.
iteration_id Integer or null The ID of the iteration the story belongs to.
labels_add Array [CreateLabelParams] An array of labels to be added.
labels_remove Array [CreateLabelParams] An array of labels to be removed.
move_to Enum (first, last) One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state.
owner_ids_add Array [UUID] The UUIDs of the new owners to be added.
owner_ids_remove Array [UUID] The UUIDs of the owners to be removed.
project_id Integer or null The ID of the Project the Stories should belong to.
requested_by_id UUID The ID of the member that requested the story.
story_ids Array [Integer] Required. The Ids of the Stories you wish to update.
story_type Enum (bug, chore, feature) The type of story (feature, bug, chore).
workflow_state_id Integer The ID of the workflow state to put the stories in.

Responses

Code Description
200 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Multiple Stories

Delete Multiple Stories allows you to delete multiple archived stories at once.

Definition

DELETE https://api.app.shortcut.com/api/v3/stories/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "story_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v3/stories/bulk"

Body Parameters

Name Description
story_ids Array [Integer] Required. An array of IDs of Stories to delete.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Story From Template

Create Story From Template is used to add a new story derived from a template to your Shortcut Workspace.

Definition

POST https://api.app.shortcut.com/api/v3/stories/from-template

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "comments": [{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": null, "parent_id": 123, "text": null, "updated_at": "2016-12-31T12:30:00Z" }], "completed_at_override": "2016-12-31T12:30:00Z", "created_at": "2016-12-31T12:30:00Z", "custom_fields": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "custom_fields_add": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "custom_fields_remove": [{ "field_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_id": 123, "estimate": 123, "external_id": null, "external_links": [], "external_links_add": [], "external_links_remove": [], "file_ids": [123], "file_ids_add": [123], "file_ids_remove": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "labels_add": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "labels_remove": [{ "name": null }], "linked_file_ids": [123], "linked_file_ids_add": [123], "linked_file_ids_remove": [123], "move_to": "first", "name": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "requested_by_id": "12345678-9012-3456-7890-123456789012", "source_task_id": 123, "started_at_override": "2016-12-31T12:30:00Z", "story_links": [{ "object_id": 123, "subject_id": 123, "verb": "blocks" }], "story_template_id": "12345678-9012-3456-7890-123456789012", "story_type": "bug", "tasks": [{ "complete": true, "created_at": "2016-12-31T12:30:00Z", "description": null, "external_id": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "updated_at": "2016-12-31T12:30:00Z" }], "updated_at": "2016-12-31T12:30:00Z", "workflow_state_id": 123 }' \
  -L "https://api.app.shortcut.com/api/v3/stories/from-template"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "blocked": true,
  "blocker": true,
  "branches": [{
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "name": "foo",
    "persistent": true,
    "pull_requests": [{
      "branch_id": 123,
      "branch_name": "foo",
      "build_status": "foo",
      "closed": true,
      "created_at": "2016-12-31T12:30:00Z",
      "draft": true,
      "entity_type": "foo",
      "has_overlapping_stories": true,
      "id": 123,
      "merged": true,
      "num_added": 123,
      "num_commits": 123,
      "num_modified": 123,
      "num_removed": 123,
      "number": 123,
      "overlapping_stories": [123],
      "repository_id": 123,
      "review_status": "foo",
      "target_branch_id": 123,
      "target_branch_name": "foo",
      "title": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo",
      "vcs_labels": [{
        "color": "#6515dd",
        "description": "foo",
        "entity_type": "foo",
        "id": 123,
        "name": "foo"
      }]
    }],
    "repository_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "comments": [{
    "app_url": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "blocker": true,
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "linked_to_slack": true,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "parent_id": 123,
    "position": 123,
    "story_id": 123,
    "text": "foo",
    "unblocks_parent": true,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "commits": [{
    "author_email": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "author_identity": {
      "entity_type": "foo",
      "name": "foo",
      "type": "bitbucket"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "hash": "foo",
    "id": 123,
    "message": "foo",
    "repository_id": 123,
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "custom_fields": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value": "foo",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }],
  "cycle_time": 123,
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "epic_id": 123,
  "estimate": 123,
  "external_id": "foo",
  "external_links": [],
  "files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "filename": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_id": "12345678-9012-3456-7890-123456789012",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "iteration_id": 123,
  "label_ids": [123],
  "labels": [{
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "lead_time": 123,
  "linked_files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "moved_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "previous_iteration_ids": [123],
  "project_id": 123,
  "pull_requests": [{
    "branch_id": 123,
    "branch_name": "foo",
    "build_status": "foo",
    "closed": true,
    "created_at": "2016-12-31T12:30:00Z",
    "draft": true,
    "entity_type": "foo",
    "has_overlapping_stories": true,
    "id": 123,
    "merged": true,
    "num_added": 123,
    "num_commits": 123,
    "num_modified": 123,
    "num_removed": 123,
    "number": 123,
    "overlapping_stories": [123],
    "repository_id": 123,
    "review_status": "foo",
    "target_branch_id": 123,
    "target_branch_name": "foo",
    "title": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo",
    "vcs_labels": [{
      "color": "#6515dd",
      "description": "foo",
      "entity_type": "foo",
      "id": 123,
      "name": "foo"
    }]
  }],
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "stats": {
    "num_related_documents": 123
  },
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": 123,
    "object_id": 123,
    "subject_id": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo"
  }],
  "story_template_id": "12345678-9012-3456-7890-123456789012",
  "story_type": "foo",
  "synced_item": {
    "external_id": "foo",
    "url": "foo"
  },
  "tasks": [{
    "complete": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "unresolved_blocker_comments": [123],
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_id": 123,
  "workflow_state_id": 123
}

Body Parameters

Name Description
archived Boolean Controls the story’s archived state.
comments Array [CreateStoryCommentParams] An array of comments to add to the story.
completed_at_override Date A manual override for the time/date the Story was completed.
created_at Date The time/date the Story was created.
custom_fields Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
custom_fields_add Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. These will be added to any fields provided by the template. Cannot be used in conjunction with custom_fields.
custom_fields_remove Array [RemoveCustomFieldParams] A map specifying a CustomField ID. These will be removed from any fields provided by the template. Cannot be used in conjunction with custom_fields.
deadline Date or null The due date of the story.
description String (100000) The description of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_id String (1024) This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
external_links Array [String] An array of External Links associated with this story.
external_links_add Array [String] An array of External Links associated with this story. These will be added to any links provided by the template. Cannot be used in conjunction with external_links.
external_links_remove Array [String] An array of External Links associated with this story. These will be removed from any links provided by the template. Cannot be used in conjunction with external_links.
file_ids Array [Integer] An array of IDs of files attached to the story.
file_ids_add Array [Integer] An array of IDs of files attached to the story in addition to files from the template. Cannot be used in conjunction with file_ids.
file_ids_remove Array [Integer] An array of IDs of files removed from files from the template. Cannot be used in conjunction with file_ids.
follower_ids Array [UUID] An array of UUIDs of the followers of this story.
follower_ids_add Array [UUID] The UUIDs of the new followers to be added in addition to followers from the template. Cannot be used in conjunction with follower_ids.
follower_ids_remove Array [UUID] The UUIDs of the new followers to be removed from followers from the template. Cannot be used in conjunction with follower_ids.
group_id UUID or null The id of the group to associate with this story.
iteration_id Integer or null The ID of the iteration the story belongs to.
labels Array [CreateLabelParams] An array of labels attached to the story.
labels_add Array [CreateLabelParams] An array of labels attached to the story in addition to the labels provided by the template. Cannot be used in conjunction with labels.
labels_remove Array [RemoveLabelParams] An array of labels to remove from the labels provided by the template. Cannot be used in conjunction with labels.
linked_file_ids Array [Integer] An array of IDs of linked files attached to the story.
linked_file_ids_add Array [Integer] An array of IDs of linked files attached to the story in addition to files from the template. Cannot be used in conjunction with linked_files.
linked_file_ids_remove Array [Integer] An array of IDs of linked files removed from files from the template. Cannot be used in conjunction with linked_files.
move_to Enum (first, last) One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state.
name String (512) The name of the story. Must be provided if the template does not provide a name.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
owner_ids_add Array [UUID] The UUIDs of the new owners to be added in addition to owners from the template. Cannot be used in conjunction with owners.
owner_ids_remove Array [UUID] The UUIDs of the new owners to be removed from owners from the template. Cannot be used in conjunction with owners.
project_id Integer or null The ID of the project the story belongs to.
requested_by_id UUID The ID of the member that requested the story.
source_task_id Integer or null Given this story was converted from a task in another story, this is the original task ID that was converted to this story.
started_at_override Date A manual override for the time/date the Story was started.
story_links Array [CreateStoryLinkParams] An array of story links attached to the story.
story_template_id UUID Required. The id of the story template used to create this story.
story_type Enum (bug, chore, feature) The type of story (feature, bug, chore).
tasks Array [CreateTaskParams] An array of tasks connected to the story.
updated_at Date The time/date the Story was updated.
workflow_state_id Integer The ID of the workflow state the story will be in.

Responses

Code Description
201 Story
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Search Stories (Old)

Search Stories lets you search Stories based on desired parameters.

Definition

POST https://api.app.shortcut.com/api/v3/stories/search

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "completed_at_end": "2016-12-31T12:30:00Z", "completed_at_start": "2016-12-31T12:30:00Z", "created_at_end": "2016-12-31T12:30:00Z", "created_at_start": "2016-12-31T12:30:00Z", "deadline_end": "2016-12-31T12:30:00Z", "deadline_start": "2016-12-31T12:30:00Z", "epic_id": 123, "epic_ids": [123], "estimate": 123, "external_id": null, "group_id": "12345678-9012-3456-7890-123456789012", "group_ids": ["12345678-9012-3456-7890-123456789012"], "includes_description": true, "iteration_id": 123, "iteration_ids": [123], "label_ids": [123], "label_name": "foo", "owner_id": "12345678-9012-3456-7890-123456789012", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "project_ids": [123], "requested_by_id": "12345678-9012-3456-7890-123456789012", "story_type": "bug", "updated_at_end": "2016-12-31T12:30:00Z", "updated_at_start": "2016-12-31T12:30:00Z", "workflow_state_id": 123, "workflow_state_types": ["backlog"] }' \
  -L "https://api.app.shortcut.com/api/v3/stories/search"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "comment_ids": [123],
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "completed_at_override": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value": "foo",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "cycle_time": 123,
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic_id": 123,
    "estimate": 123,
    "external_id": "foo",
    "external_links": [],
    "file_ids": [123],
    "follower_ids": ["12345678-9012-3456-7890-123456789012"],
    "group_id": "12345678-9012-3456-7890-123456789012",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "iteration_id": 123,
    "label_ids": [123],
    "labels": [{
      "app_url": "foo",
      "archived": true,
      "color": "#6515dd",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "external_id": "foo",
      "id": 123,
      "name": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "lead_time": 123,
    "linked_file_ids": [123],
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "num_tasks_completed": 123,
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "previous_iteration_ids": [123],
    "project_id": 123,
    "requested_by_id": "12345678-9012-3456-7890-123456789012",
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stats": {
      "num_related_documents": 123
    },
    "story_links": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "foo",
      "id": 123,
      "object_id": 123,
      "subject_id": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "verb": "foo"
    }],
    "story_template_id": "12345678-9012-3456-7890-123456789012",
    "story_type": "foo",
    "synced_item": {
      "external_id": "foo",
      "url": "foo"
    },
    "task_ids": [123],
    "unresolved_blocker_comments": [123],
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_id": 123,
    "workflow_state_id": 123
  }
]

Body Parameters

Name Description
archived Boolean A true/false boolean indicating whether the Story is in archived state.
completed_at_end Date Stories should have been completed on or before this date.
completed_at_start Date Stories should have been completed on or after this date.
created_at_end Date Stories should have been created on or before this date.
created_at_start Date Stories should have been created on or after this date.
deadline_end Date Stories should have a deadline on or before this date.
deadline_start Date Stories should have a deadline on or after this date.
epic_id Integer or null The Epic IDs that may be associated with the Stories.
epic_ids Array [Integer] The Epic IDs that may be associated with the Stories.
estimate Integer The number of estimate points associate with the Stories.
external_id String (1024) An ID or URL that references an external resource. Useful during imports.
group_id UUID or null The Group ID that is associated with the Stories
group_ids Array [UUID] The Group IDs that are associated with the Stories
includes_description Boolean Whether to include the story description in the response.
iteration_id Integer or null The Iteration ID that may be associated with the Stories.
iteration_ids Array [Integer] The Iteration IDs that may be associated with the Stories.
label_ids Array [Integer] The Label IDs that may be associated with the Stories.
label_name String The name of any associated Labels.
owner_id UUID or null An array of UUIDs for any Users who may be Owners of the Stories.
owner_ids Array [UUID] An array of UUIDs for any Users who may be Owners of the Stories.
project_id Integer or null The IDs for the Projects the Stories may be assigned to.
project_ids Array [Integer or null] The IDs for the Projects the Stories may be assigned to.
requested_by_id UUID The UUID of any Users who may have requested the Stories.
story_type Enum (bug, chore, feature) The type of Stories that you want returned.
updated_at_end Date Stories should have been updated on or before this date.
updated_at_start Date Stories should have been updated on or after this date.
workflow_state_id Integer The unique IDs of the specific Workflow States that the Stories should be in.
workflow_state_types Array [Enum (backlog, done, started, unstarted)] The type of Workflow State the Stories may be in.

Responses

Code Description
201 [ StorySlim, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Story

Get Story returns information about a chosen Story.

Definition

GET https://api.app.shortcut.com/api/v3/stories/{story-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "blocked": true,
  "blocker": true,
  "branches": [{
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "name": "foo",
    "persistent": true,
    "pull_requests": [{
      "branch_id": 123,
      "branch_name": "foo",
      "build_status": "foo",
      "closed": true,
      "created_at": "2016-12-31T12:30:00Z",
      "draft": true,
      "entity_type": "foo",
      "has_overlapping_stories": true,
      "id": 123,
      "merged": true,
      "num_added": 123,
      "num_commits": 123,
      "num_modified": 123,
      "num_removed": 123,
      "number": 123,
      "overlapping_stories": [123],
      "repository_id": 123,
      "review_status": "foo",
      "target_branch_id": 123,
      "target_branch_name": "foo",
      "title": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo",
      "vcs_labels": [{
        "color": "#6515dd",
        "description": "foo",
        "entity_type": "foo",
        "id": 123,
        "name": "foo"
      }]
    }],
    "repository_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "comments": [{
    "app_url": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "blocker": true,
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "linked_to_slack": true,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "parent_id": 123,
    "position": 123,
    "story_id": 123,
    "text": "foo",
    "unblocks_parent": true,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "commits": [{
    "author_email": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "author_identity": {
      "entity_type": "foo",
      "name": "foo",
      "type": "bitbucket"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "hash": "foo",
    "id": 123,
    "message": "foo",
    "repository_id": 123,
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "custom_fields": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value": "foo",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }],
  "cycle_time": 123,
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "epic_id": 123,
  "estimate": 123,
  "external_id": "foo",
  "external_links": [],
  "files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "filename": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_id": "12345678-9012-3456-7890-123456789012",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "iteration_id": 123,
  "label_ids": [123],
  "labels": [{
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "lead_time": 123,
  "linked_files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "moved_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "previous_iteration_ids": [123],
  "project_id": 123,
  "pull_requests": [{
    "branch_id": 123,
    "branch_name": "foo",
    "build_status": "foo",
    "closed": true,
    "created_at": "2016-12-31T12:30:00Z",
    "draft": true,
    "entity_type": "foo",
    "has_overlapping_stories": true,
    "id": 123,
    "merged": true,
    "num_added": 123,
    "num_commits": 123,
    "num_modified": 123,
    "num_removed": 123,
    "number": 123,
    "overlapping_stories": [123],
    "repository_id": 123,
    "review_status": "foo",
    "target_branch_id": 123,
    "target_branch_name": "foo",
    "title": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo",
    "vcs_labels": [{
      "color": "#6515dd",
      "description": "foo",
      "entity_type": "foo",
      "id": 123,
      "name": "foo"
    }]
  }],
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "stats": {
    "num_related_documents": 123
  },
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": 123,
    "object_id": 123,
    "subject_id": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo"
  }],
  "story_template_id": "12345678-9012-3456-7890-123456789012",
  "story_type": "foo",
  "synced_item": {
    "external_id": "foo",
    "url": "foo"
  },
  "tasks": [{
    "complete": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "unresolved_blocker_comments": [123],
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_id": 123,
  "workflow_state_id": 123
}

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story.

Responses

Code Description
200 Story
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Story

Update Story can be used to update Story properties.

Definition

PUT https://api.app.shortcut.com/api/v3/stories/{story-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "after_id": 123, "archived": true, "before_id": 123, "branch_ids": [123], "commit_ids": [123], "completed_at_override": "2016-12-31T12:30:00Z", "custom_fields": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value": "foo", "value_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "description": null, "epic_id": 123, "estimate": 123, "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "group_id": "12345678-9012-3456-7890-123456789012", "iteration_id": 123, "labels": [{ "color": "#6515dd", "description": null, "external_id": null, "name": null }], "linked_file_ids": [123], "move_to": "first", "name": null, "owner_ids": ["12345678-9012-3456-7890-123456789012"], "project_id": 123, "pull_request_ids": [123], "requested_by_id": "12345678-9012-3456-7890-123456789012", "started_at_override": "2016-12-31T12:30:00Z", "story_type": "bug", "workflow_state_id": 123 }' \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "blocked": true,
  "blocker": true,
  "branches": [{
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "id": 123,
    "merged_branch_ids": [123],
    "name": "foo",
    "persistent": true,
    "pull_requests": [{
      "branch_id": 123,
      "branch_name": "foo",
      "build_status": "foo",
      "closed": true,
      "created_at": "2016-12-31T12:30:00Z",
      "draft": true,
      "entity_type": "foo",
      "has_overlapping_stories": true,
      "id": 123,
      "merged": true,
      "num_added": 123,
      "num_commits": 123,
      "num_modified": 123,
      "num_removed": 123,
      "number": 123,
      "overlapping_stories": [123],
      "repository_id": 123,
      "review_status": "foo",
      "target_branch_id": 123,
      "target_branch_name": "foo",
      "title": "foo",
      "updated_at": "2016-12-31T12:30:00Z",
      "url": "foo",
      "vcs_labels": [{
        "color": "#6515dd",
        "description": "foo",
        "entity_type": "foo",
        "id": 123,
        "name": "foo"
      }]
    }],
    "repository_id": 123,
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "comments": [{
    "app_url": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "blocker": true,
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "linked_to_slack": true,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "parent_id": 123,
    "position": 123,
    "story_id": 123,
    "text": "foo",
    "unblocks_parent": true,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "commits": [{
    "author_email": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "author_identity": {
      "entity_type": "foo",
      "name": "foo",
      "type": "bitbucket"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "hash": "foo",
    "id": 123,
    "message": "foo",
    "repository_id": 123,
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo"
  }],
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "completed_at_override": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "custom_fields": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value": "foo",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }],
  "cycle_time": 123,
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "foo",
  "epic_id": 123,
  "estimate": 123,
  "external_id": "foo",
  "external_links": [],
  "files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "filename": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "follower_ids": ["12345678-9012-3456-7890-123456789012"],
  "group_id": "12345678-9012-3456-7890-123456789012",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "iteration_id": 123,
  "label_ids": [123],
  "labels": [{
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "lead_time": 123,
  "linked_files": [{
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "name": "foo",
    "size": 123,
    "story_ids": [123],
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader_id": "12345678-9012-3456-7890-123456789012",
    "url": "foo"
  }],
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "moved_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "owner_ids": ["12345678-9012-3456-7890-123456789012"],
  "position": 123,
  "previous_iteration_ids": [123],
  "project_id": 123,
  "pull_requests": [{
    "branch_id": 123,
    "branch_name": "foo",
    "build_status": "foo",
    "closed": true,
    "created_at": "2016-12-31T12:30:00Z",
    "draft": true,
    "entity_type": "foo",
    "has_overlapping_stories": true,
    "id": 123,
    "merged": true,
    "num_added": 123,
    "num_commits": 123,
    "num_modified": 123,
    "num_removed": 123,
    "number": 123,
    "overlapping_stories": [123],
    "repository_id": 123,
    "review_status": "foo",
    "target_branch_id": 123,
    "target_branch_name": "foo",
    "title": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "url": "foo",
    "vcs_labels": [{
      "color": "#6515dd",
      "description": "foo",
      "entity_type": "foo",
      "id": 123,
      "name": "foo"
    }]
  }],
  "requested_by_id": "12345678-9012-3456-7890-123456789012",
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "stats": {
    "num_related_documents": 123
  },
  "story_links": [{
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "foo",
    "id": 123,
    "object_id": 123,
    "subject_id": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo"
  }],
  "story_template_id": "12345678-9012-3456-7890-123456789012",
  "story_type": "foo",
  "synced_item": {
    "external_id": "foo",
    "url": "foo"
  },
  "tasks": [{
    "complete": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "external_id": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "position": 123,
    "story_id": 123,
    "updated_at": "2016-12-31T12:30:00Z"
  }],
  "unresolved_blocker_comments": [123],
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_id": 123,
  "workflow_state_id": 123
}

URL Parameters

Name Description
story-public-id Integer Required. The unique identifier of this story.

Body Parameters

Name Description
after_id Integer The ID of the story we want to move this story after.
archived Boolean True if the story is archived, otherwise false.
before_id Integer The ID of the story we want to move this story before.
branch_ids Array [Integer] An array of IDs of Branches attached to the story.
commit_ids Array [Integer] An array of IDs of Commits attached to the story.
completed_at_override Date or null A manual override for the time/date the Story was completed.
custom_fields Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
deadline Date or null The due date of the story.
description String (100000) The description of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_links Array [String] An array of External Links associated with this story.
file_ids Array [Integer] An array of IDs of files attached to the story.
follower_ids Array [UUID] An array of UUIDs of the followers of this story.
group_id UUID or null The ID of the group to associate with this story
iteration_id Integer or null The ID of the iteration the story belongs to.
labels Array [CreateLabelParams] An array of labels attached to the story.
linked_file_ids Array [Integer] An array of IDs of linked files attached to the story.
move_to Enum (first, last) One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state.
name String (512) The title of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
project_id Integer or null The ID of the project the story belongs to.
pull_request_ids Array [Integer] An array of IDs of Pull/Merge Requests attached to the story.
requested_by_id UUID The ID of the member that requested the story.
started_at_override Date or null A manual override for the time/date the Story was started.
story_type Enum (bug, chore, feature) The type of story (feature, bug, chore).
workflow_state_id Integer The ID of the workflow state to put the story in.

Responses

Code Description
200 Story
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Story

Delete Story can be used to delete any Story.

Definition

DELETE https://api.app.shortcut.com/api/v3/stories/{story-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}"

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

List Story Comment

Lists Comments associated with a Story

Definition

GET https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments"

Example Response

[
  {
    "app_url": "foo",
    "author_id": "12345678-9012-3456-7890-123456789012",
    "blocker": true,
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "foo",
    "external_id": "foo",
    "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "id": 123,
    "linked_to_slack": true,
    "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "mention_ids": ["12345678-9012-3456-7890-123456789012"],
    "parent_id": 123,
    "position": 123,
    "story_id": 123,
    "text": "foo",
    "unblocks_parent": true,
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Comment is in.

Responses

Code Description
200 [ StoryComment, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Story Comment

Create Comment allows you to create a Comment on any Story.

Definition

POST https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "author_id": "12345678-9012-3456-7890-123456789012", "created_at": "2016-12-31T12:30:00Z", "external_id": null, "parent_id": 123, "text": null, "updated_at": "2016-12-31T12:30:00Z" }' \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments"

Example Response

{
  "app_url": "foo",
  "author_id": "12345678-9012-3456-7890-123456789012",
  "blocker": true,
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "foo",
  "external_id": "foo",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "linked_to_slack": true,
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "parent_id": 123,
  "position": 123,
  "story_id": 123,
  "text": "foo",
  "unblocks_parent": true,
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Comment is in.

Body Parameters

Name Description
author_id UUID The Member ID of the Comment’s author. Defaults to the user identified by the API token.
created_at Date Defaults to the time/date the comment is created, but can be set to reflect another date.
external_id String (1024) This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.
parent_id Integer or null The ID of the Comment that this comment is threaded under.
text String (100000) Required. The comment text.
updated_at Date Defaults to the time/date the comment is last updated, but can be set to reflect another date.

Responses

Code Description
201 StoryComment
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Get Story Comment

Get Comment is used to get Comment information.

Definition

GET https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}"

Example Response

{
  "app_url": "foo",
  "author_id": "12345678-9012-3456-7890-123456789012",
  "blocker": true,
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "foo",
  "external_id": "foo",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "linked_to_slack": true,
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "parent_id": 123,
  "position": 123,
  "story_id": 123,
  "text": "foo",
  "unblocks_parent": true,
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Comment is in.
comment-public-id Integer Required. The ID of the Comment.

Responses

Code Description
200 StoryComment
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Update Story Comment

Update Comment replaces the text of the existing Comment.

Definition

PUT https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "text": null }' \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}"

Example Response

{
  "app_url": "foo",
  "author_id": "12345678-9012-3456-7890-123456789012",
  "blocker": true,
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "foo",
  "external_id": "foo",
  "group_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "id": 123,
  "linked_to_slack": true,
  "member_mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "mention_ids": ["12345678-9012-3456-7890-123456789012"],
  "parent_id": 123,
  "position": 123,
  "story_id": 123,
  "text": "foo",
  "unblocks_parent": true,
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Comment is in.
comment-public-id Integer Required. The ID of the Comment

Body Parameters

Name Description
text String (100000) Required. The updated comment text.

Responses

Code Description
200 StoryComment
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Story Comment

Delete a Comment from any story.

Definition

DELETE https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}"

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Comment is in.
comment-public-id Integer Required. The ID of the Comment.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Create Story Reaction

Create a reaction to a story comment.

Definition

POST https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "emoji": "foo" }' \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions"

Example Response

[
  {
    "emoji": "foo",
    "permission_ids": ["12345678-9012-3456-7890-123456789012"]
  }
]

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Comment is in.
comment-public-id Integer Required. The ID of the Comment.

Body Parameters

Name Description
emoji String Required. The emoji short-code to add / remove. E.g. :thumbsup::skin-tone-4:.

Responses

Code Description
201 [ StoryReaction, … ]
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

Delete Story Reaction

Delete a reaction from any story comment.

Definition

DELETE https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
  -d '{ "emoji": "foo" }' \
  -L "https://api.app.shortcut.com/api/v3/stories/{story-public-id}/comments/{comment-public-id}/reactions"

URL Parameters

Name Description
story-public-id Integer Required. The ID of the Story that the Comment is in.
comment-public-id Integer Required. The ID of the Comment.

Body Parameters

Name Description
emoji String Required. The emoji short-code to add / remove. E.g. :thumbsup::skin-tone-4:.

Responses

Code Description
204 No Content
400 Schema mismatch
404 Resource does not exist
422 Unprocessable

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:

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.

CreateCategory

Name Description
color Color The hex color to be displayed with the Category (for example, “#ff0000”).
external_id String (128) This field can be set to another unique ID. In the case that the Category has been imported from another tool, the ID in the other tool can be indicated here.
name String (128) The name of the new Category.

CreateCategoryParams

Request parameters for creating a Category with a Objective.

Name Description
color Color The hex color to be displayed with the Category (for example, “#ff0000”).
external_id String (128) This field can be set to another unique ID. In the case that the Category has been imported from another tool, the ID in the other tool can be indicated here.
name String (128) The name of the new Category.

CreateCommentComment

Name Description
author_id UUID The Member ID of the Comment’s author. Defaults to the user identified by the API token.
created_at Date Defaults to the time/date the comment is created, but can be set to reflect another date.
external_id String (128) This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.
text String (100000) The comment text.
updated_at Date Defaults to the time/date the comment is last updated, but can be set to reflect another date.

CreateEntityTemplate

Request parameters for creating an entirely new entity template.

Name Description
author_id UUID The id of the user creating this template.
name String (128) The name of the new entity template
story_contents CreateStoryContents A map of story attributes this template populates.

CreateEpic

Name Description
completed_at_override Date A manual override for the time/date the Epic was completed.
created_at Date Defaults to the time/date it is created but can be set to reflect another date.
deadline Date or null The Epic’s deadline.
description String (100000) The Epic’s description.
epic_state_id Integer The ID of the Epic State.
external_id String (128) This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers on this new Epic.
group_id UUID or null Deprecated The ID of the group to associate with the epic. Use group_ids.
group_ids Array [UUID] An array of UUIDS for Groups to which this Epic is related.
labels Array [CreateLabelParams] An array of Labels attached to the Epic.
milestone_id Integer or null Deprecated The ID of the Milestone this Epic is related to. Use objective_ids.
name String (256) The Epic’s name.
objective_ids Array [Integer] An array of IDs for Objectives to which this Epic is related.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Epic.
planned_start_date Date or null The Epic’s planned start date.
requested_by_id UUID The ID of the member that requested the epic.
started_at_override Date A manual override for the time/date the Epic was started.
state Enum (done, in progress, to do) Deprecated The Epic’s state (to do, in progress, or done); will be ignored when epic_state_id is set.
updated_at Date Defaults to the time/date it is created but can be set to reflect another date.

CreateEpicComment

Name Description
author_id UUID The Member ID of the Comment’s author. Defaults to the user identified by the API token.
created_at Date Defaults to the time/date the comment is created, but can be set to reflect another date.
external_id String (128) This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.
text String (100000) The comment text.
updated_at Date Defaults to the time/date the comment is last updated, but can be set to reflect another date.

CreateGroup

Name Description
color Color The color you wish to use for the Group in the system.
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) The color key you wish to use for the Group in the system.
description String (4096) The description of the Group.
display_icon_id UUID The Icon id for the avatar of this Group.
member_ids Array [UUID] The Member ids to add to this Group.
mention_name String (63) The mention name of this Group.
name String (63) The name of this Group.
workflow_ids Array [Integer] The Workflow ids to add to the Group.

CreateIteration

Name Description
description String (100000) The description of the Iteration.
end_date String The date this Iteration ends, e.g. 2019-07-01.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers.
group_ids Array [UUID] An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
labels Array [CreateLabelParams] An array of Labels attached to the Iteration.
name String (256) The name of this Iteration.
start_date String The date this Iteration begins, e.g. 2019-07-01.

CreateLabelParams

Request parameters for creating a Label on a Shortcut Story.

Name Description
color Color The hex color to be displayed with the Label (for example, “#ff0000”).
description String (1024) The description of the new Label.
external_id String (128) This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here.
name String (128) The name of the new Label.

CreateLinkedFile

Name Description
content_type String (128) The content type of the image (e.g. txt/plain).
description String (512) The description of the file.
name String (256) The name of the file.
size Integer The filesize, if the integration provided it.
story_id Integer The ID of the linked story.
thumbnail_url String (2048) The URL of the thumbnail, if the integration provided it.
type Enum (box, dropbox, google, onedrive, url) The integration type of the file (e.g. google, dropbox, box).
uploader_id UUID The UUID of the member that uploaded the file.
url String (2048) The URL of linked file.

CreateMilestone

Name Description
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Milestone.
completed_at_override Date A manual override for the time/date the Milestone was completed.
description String (100000) The Milestone’s description.
name String (256) The name of the Milestone.
started_at_override Date A manual override for the time/date the Milestone was started.
state Enum (done, in progress, to do) The workflow state that the Milestone is in.

CreateObjective

Name Description
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Objective.
completed_at_override Date A manual override for the time/date the Objective was completed.
description String (100000) The Objective’s description.
name String (256) The name of the Objective.
started_at_override Date A manual override for the time/date the Objective was started.
state Enum (done, in progress, to do) The workflow state that the Objective is in.

CreateOrDeleteStoryReaction

Name Description
emoji String The emoji short-code to add / remove. E.g. :thumbsup::skin-tone-4:.

CreateProject

Name Description
abbreviation String (63) The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.
color Color The color you wish to use for the Project in the system.
created_at Date Defaults to the time/date it is created but can be set to reflect another date.
description String (100000) The Project description.
external_id String (128) This field can be set to another unique ID. In the case that the Project has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Epic.
iteration_length Integer The number of weeks per iteration in this Project.
name String (128) The name of the Project.
start_time Date The date at which the Project was started.
team_id Integer The ID of the team the project belongs to.
updated_at Date Defaults to the time/date it is created but can be set to reflect another date.

CreateStories

Name Description
stories Array [CreateStoryParams] An array of stories to be created.

CreateStoryComment

Name Description
author_id UUID The Member ID of the Comment’s author. Defaults to the user identified by the API token.
created_at Date Defaults to the time/date the comment is created, but can be set to reflect another date.
external_id String (1024) This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.
parent_id Integer or null The ID of the Comment that this comment is threaded under.
text String (100000) The comment text.
updated_at Date Defaults to the time/date the comment is last updated, but can be set to reflect another date.

CreateStoryCommentParams

Request parameters for creating a Comment on a Shortcut Story.

Name Description
author_id UUID The Member ID of the Comment’s author. Defaults to the user identified by the API token.
created_at Date Defaults to the time/date the comment is created, but can be set to reflect another date.
external_id String (1024) This field can be set to another unique ID. In the case that the comment has been imported from another tool, the ID in the other tool can be indicated here.
parent_id Integer or null The ID of the Comment that this comment is threaded under.
text String (100000) The comment text.
updated_at Date Defaults to the time/date the comment is last updated, but can be set to reflect another date.

CreateStoryContents

A map of story attributes this template populates.

Name Description
custom_fields Array [CustomFieldValueParams] An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
deadline Date or null The due date of the story.
description String The description of the story.
epic_id Integer or null The ID of the epic the to be populated.
estimate Integer or null The numeric point estimate to be populated.
external_links Array [String] An array of external links to be populated.
file_ids Array [Integer] An array of the attached file IDs to be populated.
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
group_id UUID or null The ID of the group to be populated.
iteration_id Integer or null The ID of the iteration the to be populated.
labels Array [CreateLabelParams] An array of labels to be populated by the template.
linked_file_ids Array [Integer] An array of the linked file IDs to be populated.
name String (512) The name of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
project_id Integer The ID of the project the story belongs to.
story_type String The type of story (feature, bug, chore).
tasks Array [BaseTaskParams] An array of tasks to be populated by the template.
workflow_state_id Integer or null The ID of the workflow state to be populated.

CreateStoryFromTemplateParams

Request parameters for creating a story from a story template. These parameters are merged with the values derived from the template.

Name Description
archived Boolean Controls the story’s archived state.
comments Array [CreateStoryCommentParams] An array of comments to add to the story.
completed_at_override Date A manual override for the time/date the Story was completed.
created_at Date The time/date the Story was created.
custom_fields Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
custom_fields_add Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField. These will be added to any fields provided by the template. Cannot be used in conjunction with custom_fields.
custom_fields_remove Array [RemoveCustomFieldParams] A map specifying a CustomField ID. These will be removed from any fields provided by the template. Cannot be used in conjunction with custom_fields.
deadline Date or null The due date of the story.
description String (100000) The description of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_id String (1024) This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
external_links Array [String] An array of External Links associated with this story.
external_links_add Array [String] An array of External Links associated with this story. These will be added to any links provided by the template. Cannot be used in conjunction with external_links.
external_links_remove Array [String] An array of External Links associated with this story. These will be removed from any links provided by the template. Cannot be used in conjunction with external_links.
file_ids Array [Integer] An array of IDs of files attached to the story.
file_ids_add Array [Integer] An array of IDs of files attached to the story in addition to files from the template. Cannot be used in conjunction with file_ids.
file_ids_remove Array [Integer] An array of IDs of files removed from files from the template. Cannot be used in conjunction with file_ids.
follower_ids Array [UUID] An array of UUIDs of the followers of this story.
follower_ids_add Array [UUID] The UUIDs of the new followers to be added in addition to followers from the template. Cannot be used in conjunction with follower_ids.
follower_ids_remove Array [UUID] The UUIDs of the new followers to be removed from followers from the template. Cannot be used in conjunction with follower_ids.
group_id UUID or null The id of the group to associate with this story.
iteration_id Integer or null The ID of the iteration the story belongs to.
labels Array [CreateLabelParams] An array of labels attached to the story.
labels_add Array [CreateLabelParams] An array of labels attached to the story in addition to the labels provided by the template. Cannot be used in conjunction with labels.
labels_remove Array [RemoveLabelParams] An array of labels to remove from the labels provided by the template. Cannot be used in conjunction with labels.
linked_file_ids Array [Integer] An array of IDs of linked files attached to the story.
linked_file_ids_add Array [Integer] An array of IDs of linked files attached to the story in addition to files from the template. Cannot be used in conjunction with linked_files.
linked_file_ids_remove Array [Integer] An array of IDs of linked files removed from files from the template. Cannot be used in conjunction with linked_files.
move_to Enum (first, last) One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state.
name String (512) The name of the story. Must be provided if the template does not provide a name.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
owner_ids_add Array [UUID] The UUIDs of the new owners to be added in addition to owners from the template. Cannot be used in conjunction with owners.
owner_ids_remove Array [UUID] The UUIDs of the new owners to be removed from owners from the template. Cannot be used in conjunction with owners.
project_id Integer or null The ID of the project the story belongs to.
requested_by_id UUID The ID of the member that requested the story.
source_task_id Integer or null Given this story was converted from a task in another story, this is the original task ID that was converted to this story.
started_at_override Date A manual override for the time/date the Story was started.
story_links Array [CreateStoryLinkParams] An array of story links attached to the story.
story_template_id UUID The id of the story template used to create this story.
story_type Enum (bug, chore, feature) The type of story (feature, bug, chore).
tasks Array [CreateTaskParams] An array of tasks connected to the story.
updated_at Date The time/date the Story was updated.
workflow_state_id Integer The ID of the workflow state the story will be in.
Name Description
object_id Integer The ID of the object Story.
subject_id Integer The ID of the subject Story.
verb Enum (blocks, duplicates, relates to) The type of link.

CreateStoryLinkParams

Request parameters for creating a Story Link within a Story.

Name Description
object_id Integer The unique ID of the Story defined as object.
subject_id Integer The unique ID of the Story defined as subject.
verb Enum (blocks, duplicates, relates to) How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”.

CreateStoryParams

Request parameters for creating a story.

Name Description
archived Boolean Controls the story’s archived state.
comments Array [CreateStoryCommentParams] An array of comments to add to the story.
completed_at_override Date A manual override for the time/date the Story was completed.
created_at Date The time/date the Story was created.
custom_fields Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
deadline Date or null The due date of the story.
description String (100000) The description of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_id String (1024) This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
external_links Array [String] An array of External Links associated with this story.
file_ids Array [Integer] An array of IDs of files attached to the story.
follower_ids Array [UUID] An array of UUIDs of the followers of this story.
group_id UUID or null The id of the group to associate with this story.
iteration_id Integer or null The ID of the iteration the story belongs to.
labels Array [CreateLabelParams] An array of labels attached to the story.
linked_file_ids Array [Integer] An array of IDs of linked files attached to the story.
move_to Enum (first, last) One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state.
name String (512) The name of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
project_id Integer or null The ID of the project the story belongs to.
requested_by_id UUID The ID of the member that requested the story.
source_task_id Integer or null Given this story was converted from a task in another story, this is the original task ID that was converted to this story.
started_at_override Date A manual override for the time/date the Story was started.
story_links Array [CreateStoryLinkParams] An array of story links attached to the story.
story_template_id UUID or null The id of the story template used to create this story, if applicable. This is just an association; no content from the story template is inherited by the story simply by setting this field.
story_type Enum (bug, chore, feature) The type of story (feature, bug, chore).
tasks Array [CreateTaskParams] An array of tasks connected to the story.
updated_at Date The time/date the Story was updated.
workflow_state_id Integer The ID of the workflow state the story will be in.

CreateTask

Name Description
complete Boolean True/false boolean indicating whether the Task is completed. Defaults to false.
created_at Date Defaults to the time/date the Task is created but can be set to reflect another creation time/date.
description String (2048) The Task description.
external_id String (128) This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Task.
updated_at Date Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date.

CreateTaskParams

Request parameters for creating a Task on a Story.

Name Description
complete Boolean True/false boolean indicating whether the Task is completed. Defaults to false.
created_at Date Defaults to the time/date the Task is created but can be set to reflect another creation time/date.
description String (2048) The Task description.
external_id String (128) This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Task.
updated_at Date Defaults to the time/date the Task is created in Shortcut but can be set to reflect another time/date.

CustomField

Name Description
canonical_name String The canonical name for a Shortcut-defined field.
created_at Date The instant when this CustomField was created.
description String (512) A string description of the CustomField
enabled Boolean When true, the CustomField can be applied to entities in the Workspace.
entity_type Enum (custom-field) A string description of this resource.
field_type Enum (enum) The type of Custom Field, eg. ‘enum’.
icon_set_identifier String (63) A string that represents the icon that corresponds to this custom field.
id UUID The unique public ID for the CustomField.
name String (63) The name of the Custom Field.
position Integer An integer indicating the position of this Custom Field with respect to the other CustomField
updated_at Date The instant when this CustomField was last updated.
values Array [CustomFieldEnumValue] A collection of legal values for a CustomField.

CustomFieldEnumValue

Name Description
color_key String or null A color key associated with this CustomFieldEnumValue.
entity_type Enum (custom-field-enum-value) A string description of this resource.
id UUID The unique public ID for the Custom Field.
position Integer An integer indicating the position of this Value with respect to the other CustomFieldEnumValues in the enumeration.
value String (63) A string value within the domain of this Custom Field.

CustomFieldValueParams

Name Description
field_id UUID The unique public ID for the CustomField.
value String A literal value for the CustomField. Currently ignored.
value_id UUID The unique public ID for the CustomFieldEnumValue.

DataConflictError

Error returned when Datomic tx fails due to Datomc :db.error/cas-failed error

Name Description
error Enum (data-conflict-error)
message String An explanatory message: “The update failed due to a data conflict. Please refresh and try again.”

DeleteStories

Name Description
story_ids Array [Integer] An array of IDs of Stories to delete.

EntityTemplate

An entity template can be used to prefill various fields when creating new stories.

Name Description
author_id UUID The unique ID of the member who created the template.
created_at Date The time/date when the entity template was created.
entity_type String A string description of this resource.
id UUID The unique identifier for the entity template.
last_used_at Date The last time that someone created an entity using this template.
name String The template’s name.
story_contents StoryContents A container entity for the attributes this template should populate.
updated_at Date The time/date when the entity template was last updated.

Epic

An Epic is a collection of stories that together might make up a release, a objective, or some other large initiative that you are working on.

Name Description
app_url String The Shortcut application url for the Epic.
archived Boolean True/false boolean that indicates whether the Epic is archived or not.
associated_groups Array [EpicAssociatedGroup] An array containing Group IDs and Group-owned story counts for the Epic’s associated groups.
comments Array [ThreadedComment] A nested array of threaded comments.
completed Boolean A true/false boolean indicating if the Epic has been completed.
completed_at Date or null The time/date the Epic was completed.
completed_at_override Date or null A manual override for the time/date the Epic was completed.
created_at Date or null The time/date the Epic was created.
deadline Date or null The Epic’s deadline.
description String The Epic’s description.
entity_type String A string description of this resource.
epic_state_id Integer The ID of the Epic State.
external_id String or null This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers on this Epic.
group_id UUID or null Deprecated The ID of the group to associate with the epic. Use group_ids.
group_ids Array [UUID] An array of UUIDS for Groups to which this Epic is related.
group_mention_ids Array [UUID] An array of Group IDs that have been mentioned in the Epic description.
id Integer The unique ID of the Epic.
label_ids Array [Integer] An array of Label ids attached to the Epic.
labels Array [LabelSlim] An array of Labels attached to the Epic.
member_mention_ids Array [UUID] An array of Member IDs that have been mentioned in the Epic description.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
milestone_id Integer or null Deprecated The ID of the Objective this Epic is related to. Use objective_ids.
name String The name of the Epic.
objective_ids Array [Integer] An array of IDs for Objectives to which this epic is related.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Epic.
planned_start_date Date or null The Epic’s planned start date.
position Integer The Epic’s relative position in the Epic workflow state.
productboard_id UUID or null The ID of the associated productboard feature.
productboard_name String or null The name of the associated productboard feature.
productboard_plugin_id UUID or null The ID of the associated productboard integration.
productboard_url String or null The URL of the associated productboard feature.
project_ids Array [Integer] The IDs of Projects related to this Epic.
requested_by_id UUID The ID of the Member that requested the epic.
started Boolean A true/false boolean indicating if the Epic has been started.
started_at Date or null The time/date the Epic was started.
started_at_override Date or null A manual override for the time/date the Epic was started.
state String Deprecated The workflow state that the Epic is in.
stats EpicStats A group of calculated values for this Epic.
stories_without_projects Integer The number of stories in this epic which are not associated with a project.
updated_at Date or null The time/date the Epic was updated.

EpicAssociatedGroup

Name Description
associated_stories_count Integer The number of stories this Group owns in the Epic.
group_id UUID The Group ID of the associated group.

EpicSearchResult

An Epic in search results. This is typed differently from Epic because the details=slim search argument will omit some fields.

Name Description
app_url String The Shortcut application url for the Epic.
archived Boolean True/false boolean that indicates whether the Epic is archived or not.
associated_groups Array [EpicAssociatedGroup] An array containing Group IDs and Group-owned story counts for the Epic’s associated groups.
comments Array [ThreadedComment] A nested array of threaded comments.
completed Boolean A true/false boolean indicating if the Epic has been completed.
completed_at Date or null The time/date the Epic was completed.
completed_at_override Date or null A manual override for the time/date the Epic was completed.
created_at Date or null The time/date the Epic was created.
deadline Date or null The Epic’s deadline.
description String The Epic’s description.
entity_type String A string description of this resource.
epic_state_id Integer The ID of the Epic State.
external_id String or null This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers on this Epic.
group_id UUID or null Deprecated The ID of the group to associate with the epic. Use group_ids.
group_ids Array [UUID] An array of UUIDS for Groups to which this Epic is related.
group_mention_ids Array [UUID] An array of Group IDs that have been mentioned in the Epic description.
id Integer The unique ID of the Epic.
label_ids Array [Integer] An array of Label ids attached to the Epic.
labels Array [LabelSlim] An array of Labels attached to the Epic.
member_mention_ids Array [UUID] An array of Member IDs that have been mentioned in the Epic description.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
milestone_id Integer or null Deprecated The ID of the Objective this Epic is related to. Use objective_ids.
name String The name of the Epic.
objective_ids Array [Integer] An array of IDs for Objectives to which this epic is related.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Epic.
planned_start_date Date or null The Epic’s planned start date.
position Integer The Epic’s relative position in the Epic workflow state.
productboard_id UUID or null The ID of the associated productboard feature.
productboard_name String or null The name of the associated productboard feature.
productboard_plugin_id UUID or null The ID of the associated productboard integration.
productboard_url String or null The URL of the associated productboard feature.
project_ids Array [Integer] The IDs of Projects related to this Epic.
requested_by_id UUID The ID of the Member that requested the epic.
started Boolean A true/false boolean indicating if the Epic has been started.
started_at Date or null The time/date the Epic was started.
started_at_override Date or null A manual override for the time/date the Epic was started.
state String Deprecated The workflow state that the Epic is in.
stats EpicStats A group of calculated values for this Epic.
stories_without_projects Integer The number of stories in this epic which are not associated with a project.
updated_at Date or null The time/date the Epic was updated.

EpicSearchResults

The results of the Epic search query.

Name Description
data Array [EpicSearchResult] A list of search results.
next String or null The URL path and query string for the next page of search results.
total Integer The total number of matches for the search query. The first 1000 matches can be paged through via the API.

EpicSlim

EpicSlim represents the same resource as an Epic but is more light-weight, including all Epic fields except the comments array. The description string can be optionally included. Use the Get Epic endpoint to fetch the unabridged payload for an Epic.

Name Description
app_url String The Shortcut application url for the Epic.
archived Boolean True/false boolean that indicates whether the Epic is archived or not.
associated_groups Array [EpicAssociatedGroup] An array containing Group IDs and Group-owned story counts for the Epic’s associated groups.
completed Boolean A true/false boolean indicating if the Epic has been completed.
completed_at Date or null The time/date the Epic was completed.
completed_at_override Date or null A manual override for the time/date the Epic was completed.
created_at Date or null The time/date the Epic was created.
deadline Date or null The Epic’s deadline.
description String The Epic’s description.
entity_type String A string description of this resource.
epic_state_id Integer The ID of the Epic State.
external_id String or null This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers on this Epic.
group_id UUID or null Deprecated The ID of the group to associate with the epic. Use group_ids.
group_ids Array [UUID] An array of UUIDS for Groups to which this Epic is related.
group_mention_ids Array [UUID] An array of Group IDs that have been mentioned in the Epic description.
id Integer The unique ID of the Epic.
label_ids Array [Integer] An array of Label ids attached to the Epic.
labels Array [LabelSlim] An array of Labels attached to the Epic.
member_mention_ids Array [UUID] An array of Member IDs that have been mentioned in the Epic description.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
milestone_id Integer or null Deprecated The ID of the Objective this Epic is related to. Use objective_ids.
name String The name of the Epic.
objective_ids Array [Integer] An array of IDs for Objectives to which this epic is related.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this new Epic.
planned_start_date Date or null The Epic’s planned start date.
position Integer The Epic’s relative position in the Epic workflow state.
productboard_id UUID or null The ID of the associated productboard feature.
productboard_name String or null The name of the associated productboard feature.
productboard_plugin_id UUID or null The ID of the associated productboard integration.
productboard_url String or null The URL of the associated productboard feature.
project_ids Array [Integer] The IDs of Projects related to this Epic.
requested_by_id UUID The ID of the Member that requested the epic.
started Boolean A true/false boolean indicating if the Epic has been started.
started_at Date or null The time/date the Epic was started.
started_at_override Date or null A manual override for the time/date the Epic was started.
state String Deprecated The workflow state that the Epic is in.
stats EpicStats A group of calculated values for this Epic.
stories_without_projects Integer The number of stories in this epic which are not associated with a project.
updated_at Date or null The time/date the Epic was updated.

EpicState

Epic State is any of the at least 3 columns. Epic States correspond to one of 3 types: Unstarted, Started, or Done.

Name Description
color Color The hex color for this Epic State.
created_at Date The time/date the Epic State was created.
description String The description of what sort of Epics belong in that Epic State.
entity_type String A string description of this resource.
id Integer The unique ID of the Epic State.
name String The Epic State’s name.
position Integer The position that the Epic State is in, starting with 0 at the left.
type String The type of Epic State (Unstarted, Started, or Done)
updated_at Date When the Epic State was last updated.

EpicStats

A group of calculated values for this Epic.

Name Description
average_cycle_time Integer The average cycle time (in seconds) of completed stories in this Epic.
average_lead_time Integer The average lead time (in seconds) of completed stories in this Epic.
last_story_update Date or null The date of the last update of a Story in this Epic.
num_points Integer The total number of points in this Epic.
num_points_backlog Integer The total number of backlog points in this Epic.
num_points_done Integer The total number of completed points in this Epic.
num_points_started Integer The total number of started points in this Epic.
num_points_unstarted Integer The total number of unstarted points in this Epic.
num_related_documents Integer The total number of documents associated with this Epic.
num_stories_backlog Integer The total number of backlog Stories in this Epic.
num_stories_done Integer The total number of done Stories in this Epic.
num_stories_started Integer The total number of started Stories in this Epic.
num_stories_total Integer The total number of Stories in this Epic.
num_stories_unestimated Integer The total number of Stories with no point estimate.
num_stories_unstarted Integer The total number of unstarted Stories in this Epic.

EpicWorkflow

Epic Workflow is the array of defined Epic States. Epic Workflow can be queried using the API but must be updated in the Shortcut UI.

Name Description
created_at Date The date the Epic Workflow was created.
default_epic_state_id Integer The unique ID of the default Epic State that new Epics are assigned by default.
entity_type String A string description of this resource.
epic_states Array [EpicState] A map of the Epic States in this Epic Workflow.
id Integer The unique ID of the Epic Workflow.
updated_at Date The date the Epic Workflow was updated.

Group

A Group.

Name Description
app_url String The Shortcut application url for the Group.
archived Boolean Whether or not the Group is archived.
color Color or null The hex color to be displayed with the Group (for example, “#ff0000”).
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) or null The color key to be displayed with the Group.
description String The description of the Group.
display_icon Icon or null Icons are used to attach images to Groups, Workspaces, Members, and Loading screens in the Shortcut web application.
entity_type String A string description of this resource.
id UUID The id of the Group.
member_ids Array [UUID] The Member IDs contain within the Group.
mention_name String The mention name of the Group.
name String The name of the Group.
num_epics_started Integer The number of epics assigned to the group which are in the started workflow state.
num_stories Integer The total number of stories assigned to the group.
num_stories_backlog Integer The number of stories assigned to the group which are in a backlog workflow state.
num_stories_started Integer The number of stories assigned to the group which are in a started workflow state.
workflow_ids Array [Integer] The Workflow IDs contained within the Group.

History

A history item is a group of actions that represent a transactional change to a Story.

Name Description
actions Array [undefined] An array of actions that were performed for the change.
automation_id UUID The ID of the automation that performed the change.
changed_at String The date when the change occurred.
external_id String The ID of the webhook that handled the change.
id UUID The ID representing the change for the story.
member_id UUID The ID of the member who performed the change.
primary_id undefined The ID of the primary entity that has changed, if applicable.
references Array [undefined] An array of objects affected by the change. Reference objects provide basic information for the entities reference in the history actions. Some have specific fields, but they always contain an id, entity_type, and a name.
version Enum (v1) The version of the change format.
webhook_id String or null The ID of the webhook that handled the change.

HistoryActionBranchCreate

An action representing a VCS Branch being created.

Name Description
action Enum (create) The action of the entity referenced.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
name String The name of the VCS Branch that was pushed
url String The URL from the provider of the VCS Branch that was pushed

HistoryActionBranchMerge

An action representing a VCS Branch being merged.

Name Description
action Enum (merge) The action of the entity referenced.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
name String The name of the VCS Branch that was pushed
url String The URL from the provider of the VCS Branch that was pushed

HistoryActionBranchPush

An action representing a VCS Branch being pushed.

Name Description
action Enum (push) The action of the entity referenced.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
name String The name of the VCS Branch that was pushed
url String The URL from the provider of the VCS Branch that was pushed

HistoryActionLabelCreate

An action representing a Label being created.

Name Description
action Enum (create) The action of the entity referenced.
app_url String (2048) The application URL of the Label.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
name String The name of the Label.

HistoryActionLabelDelete

An action representing a Label being deleted.

Name Description
action Enum (delete) The action of the entity referenced.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
name String The name of the Label.

HistoryActionLabelUpdate

An action representing a Label being updated.

Name Description
action Enum (update) The action of the entity referenced.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.

HistoryActionProjectUpdate

An action representing a Project being updated.

Name Description
action Enum (update) The action of the entity referenced.
app_url String (2048) The application URL of the Project.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
name String The name of the Project.

HistoryActionPullRequest

An action representing various operations for a Pull Request.

Name Description
action Enum (close, comment, open, reopen, sync, update) The action of the entity referenced.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
number Integer The VCS Repository-specific ID for the Pull Request.
title String The title of the Pull Request.
url String (2048) The URL from the provider of the VCS Pull Request.

HistoryActionStoryCommentCreate

An action representing a Story Comment being created.

Name Description
action Enum (create) The action of the entity referenced.
app_url String (2048) The application URL of the Story Comment.
author_id UUID The Member ID of who created the Story Comment.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
text String The text of the Story Comment.

HistoryActionStoryCreate

An action representing a Story being created.

Name Description
action Enum (create) The action of the entity referenced.
app_url String (2048) The application URL of the Story.
blocked Boolean Whether or not the Story is blocked by another Story.
blocker Boolean Whether or not the Story is blocking another Story.
completed Boolean Whether or not the Story is completed.
custom_field_value_ids Array [UUID] An array of Custom Field Enum Value ids on this Story.
deadline String The timestamp representing the Story’s deadline.
description String The description of the Story.
entity_type String The type of entity referenced.
epic_id Integer The Epic ID for this Story.
estimate Integer The estimate (or point value) for the Story.
follower_ids Array [UUID] An array of Member IDs for the followers of the Story.
group_id UUID The Team IDs for the followers of the Story.
id Integer The ID of the entity referenced.
iteration_id Integer or null The Iteration ID the Story is in.
label_ids Array [Integer] An array of Labels IDs attached to the Story.
name String The name of the Story.
object_story_link_ids Array [Integer] An array of Story IDs that are the object of a Story Link relationship.
owner_ids Array [UUID] An array of Member IDs that are the owners of the Story.
project_id Integer The Project ID of the Story is in.
requested_by_id UUID The ID of the Member that requested the Story.
started Boolean Whether or not the Story has been started.
story_type Enum (bug, chore, feature) The type of Story; either feature, bug, or chore.
subject_story_link_ids Array [Integer] An array of Story IDs that are the subject of a Story Link relationship.
task_ids Array [Integer] An array of Task IDs on this Story.
workflow_state_id Integer An array of Workflow State IDs attached to the Story.

HistoryActionStoryDelete

An action representing a Story being deleted.

Name Description
action Enum (delete) The action of the entity referenced.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
name String The name of the Story.
story_type Enum (bug, chore, feature) The type of Story; either feature, bug, or chore.

HistoryActionStoryLinkCreate

An action representing a Story Link being created.

Name Description
action Enum (create) The action of the entity referenced.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
object_id Integer The Story ID of the object Story.
subject_id Integer The Story ID of the subject Story.
verb Enum (blocks, duplicates, relates to) The verb describing the link’s relationship.

HistoryActionStoryLinkDelete

An action representing a Story Link being deleted.

Name Description
action Enum (delete) The action of the entity referenced.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
object_id Integer or null The Story ID of the object Story.
subject_id Integer or null The Story ID of the subject Story.
verb Enum (blocks, duplicates, relates to) The verb describing the link’s relationship.

HistoryActionStoryLinkUpdate

An action representing a Story Link being updated.

Name Description
action Enum (update) The action of the entity referenced.
changes HistoryChangesStoryLink The changes that have occurred as a result of the action.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
object_id Integer The Story ID of the object Story.
subject_id Integer The Story ID of the subject Story.
verb Enum (blocks, duplicates, relates to) The verb describing the link’s relationship.

HistoryActionStoryUpdate

An action representing a Story being updated.

Name Description
action Enum (update) The action of the entity referenced.
app_url String (2048) The application URL of the Story.
changes HistoryChangesStory The changes that have occurred as a result of the action.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
name String The name of the Story.
story_type Enum (bug, chore, feature) The type of Story; either feature, bug, or chore.

HistoryActionTaskCreate

An action representing a Task being created.

Name Description
action Enum (create) The action of the entity referenced.
complete Boolean Whether or not the Task is complete.
deadline String A timestamp that represent’s the Task’s deadline.
description String The description of the Task.
entity_type String The type of entity referenced.
group_mention_ids Array [UUID] An array of Groups IDs that represent which have been mentioned in the Task.
id Integer The ID of the entity referenced.
mention_ids Array [UUID] An array of Member IDs that represent who has been mentioned in the Task.
owner_ids Array [UUID] An array of Member IDs that represent the Task’s owners.

HistoryActionTaskDelete

An action representing a Task being deleted.

Name Description
action Enum (delete) The action of the entity referenced.
description String The description of the Task being deleted.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.

HistoryActionTaskUpdate

An action representing a Task being updated.

Name Description
action Enum (update) The action of the entity referenced.
changes HistoryChangesTask The changes that have occurred as a result of the action.
complete Boolean Whether or not the Task is complete.
description String The description of the Task.
entity_type String The type of entity referenced.
id Integer The ID of the entity referenced.
story_id Integer The Story ID that contains the Task.

HistoryActionWorkspace2BulkUpdate

An action representing a bulk operation within a workspace2.

Name Description
action Enum (bulk-update) The action of the entity referenced.
entity_type String The type of entity referenced.
id UUID The ID of the entity referenced.
name String The name of the workspace2 in which the BulkUpdate occurred.

HistoryChangesStory

The changes that have occurred as a result of the action.

Name Description
archived StoryHistoryChangeOldNewBool True if the Story has archived, otherwise false.
blocked StoryHistoryChangeOldNewBool True if the Story has archived, otherwise false.
blocker StoryHistoryChangeOldNewBool True if the Story has archived, otherwise false.
branch_ids StoryHistoryChangeAddsRemovesInt Task IDs that have been added or removed from the Story.
commit_ids StoryHistoryChangeAddsRemovesInt Task IDs that have been added or removed from the Story.
completed StoryHistoryChangeOldNewBool True if the Story has archived, otherwise false.
custom_field_value_ids StoryHistoryChangeAddsRemovesUuid Custom Field Enum Value IDs that have been added or removed from the Story.
deadline StoryHistoryChangeOldNewStr A timestamp that represents the Story’s deadline.
description StoryHistoryChangeOldNewStr A timestamp that represents the Story’s deadline.
epic_id StoryHistoryChangeOldNewInt The estimate value for the Story
estimate StoryHistoryChangeOldNewInt The estimate value for the Story
follower_ids StoryHistoryChangeAddsRemovesUuid Custom Field Enum Value IDs that have been added or removed from the Story.
group_id StoryHistoryChangeOldNewUuid The Team ID for the Story.
iteration_id StoryHistoryChangeOldNewInt The estimate value for the Story
label_ids StoryHistoryChangeAddsRemovesInt Task IDs that have been added or removed from the Story.
mention_ids StoryHistoryChangeAddsRemovesUuid Custom Field Enum Value IDs that have been added or removed from the Story.
name StoryHistoryChangeOldNewStr A timestamp that represents the Story’s deadline.
object_story_link_ids StoryHistoryChangeAddsRemovesInt Task IDs that have been added or removed from the Story.
owner_ids StoryHistoryChangeAddsRemovesUuid Custom Field Enum Value IDs that have been added or removed from the Story.
project_id StoryHistoryChangeOldNewInt The estimate value for the Story
requested_by_id StoryHistoryChangeOldNewUuid The Team ID for the Story.
started StoryHistoryChangeOldNewBool True if the Story has archived, otherwise false.
story_type StoryHistoryChangeOldNewStr A timestamp that represents the Story’s deadline.
subject_story_link_ids StoryHistoryChangeAddsRemovesInt Task IDs that have been added or removed from the Story.
task_ids StoryHistoryChangeAddsRemovesInt Task IDs that have been added or removed from the Story.
workflow_state_id StoryHistoryChangeOldNewInt The estimate value for the Story

The changes that have occurred as a result of the action.

Name Description
object_id StoryHistoryChangeOldNewInt The estimate value for the Story
subject_id StoryHistoryChangeOldNewInt The estimate value for the Story
verb StoryHistoryChangeOldNewStr A timestamp that represents the Story’s deadline.

HistoryChangesTask

The changes that have occurred as a result of the action.

Name Description
complete StoryHistoryChangeOldNewBool True if the Story has archived, otherwise false.
description StoryHistoryChangeOldNewStr A timestamp that represents the Story’s deadline.
mention_ids StoryHistoryChangeAddsRemovesUuid Custom Field Enum Value IDs that have been added or removed from the Story.
owner_ids StoryHistoryChangeAddsRemovesUuid Custom Field Enum Value IDs that have been added or removed from the Story.

HistoryReferenceBranch

A reference to a VCS Branch.

Name Description
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.
name String The name of the entity referenced.
url String (2048) The external URL for the Branch.

HistoryReferenceCommit

A reference to a VCS Commit.

Name Description
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.
message String The message from the Commit.
url String (2048) The external URL for the Branch.

HistoryReferenceCustomFieldEnumValue

A reference to a CustomField value asserted on a Story.

Name Description
entity_type String The type of entity referenced.
enum_value_enabled Boolean or null Whether or not the custom-field enum value is enabled.
field_enabled Boolean Whether or not the custom-field is enabled.
field_id UUID The public-id of the parent custom-field of this enum value.
field_name String The name as it is displayed to the user of the parent custom-field of this enum value.
field_type String The type variety of the parent custom-field of this enum value.
id undefined The ID of the entity referenced.
string_value String or null The custom-field enum value as a string.

HistoryReferenceEpic

A reference to an Epic.

Name Description
app_url String (2048) The application URL of the Epic.
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.
name String The name of the entity referenced.

HistoryReferenceGeneral

A default reference for entity types that don’t have extra fields.

Name Description
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.
name String The name of the entity referenced.

HistoryReferenceGroup

A reference to a Group.

Name Description
entity_type String The type of entity referenced.
id UUID The ID of the entity referenced.
name String The name of the entity referenced.

HistoryReferenceIteration

A reference to an Iteration.

Name Description
app_url String (2048) The application URL of the Iteration.
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.
name String The name of the entity referenced.

HistoryReferenceLabel

A reference to an Label.

Name Description
app_url String (2048) The application URL of the Label.
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.
name String The name of the entity referenced.

HistoryReferenceProject

A reference to an Project.

Name Description
app_url String (2048) The application URL of the Project.
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.
name String The name of the entity referenced.

HistoryReferenceStory

A reference to a Story.

Name Description
app_url String (2048) The application URL of the Story.
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.
name String The name of the entity referenced.
story_type Enum (bug, chore, feature) If the referenced entity is a Story, either “bug”, “chore”, or “feature”.

HistoryReferenceStoryTask

A reference to a Story Task.

Name Description
description String The description of the Story Task.
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.

HistoryReferenceWorkflowState

A references to a Story Workflow State.

Name Description
entity_type String The type of entity referenced.
id undefined The ID of the entity referenced.
name String The name of the entity referenced.
type Enum (backlog, done, started, unstarted) Either “backlog”, “unstarted”, “started”, or “done”.

Icon

Icons are used to attach images to Groups, Workspaces, Members, and Loading screens in the Shortcut web application.

Name Description
created_at Date The time/date that the Icon was created.
entity_type String A string description of this resource.
id UUID The unique ID of the Icon.
updated_at Date The time/date that the Icon was updated.
url String The URL of the Icon.

Identity

The Identity of the VCS user that authored the Commit.

Name Description
entity_type String A string description of this resource.
name String or null This is your login in VCS.
type Enum (bitbucket, github, gitlab, slack) or null The service this Identity is for.

Iteration

An Iteration is a defined, time-boxed period of development for a collection of Stories. See https://help.shortcut.com/hc/en-us/articles/360028953452-Iterations-Overview for more information.

Name Description
app_url String The Shortcut application url for the Iteration.
created_at Date The instant when this iteration was created.
description String The description of the iteration.
end_date Date The date this iteration ends.
entity_type String A string description of this resource
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
group_ids Array [UUID] An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
group_mention_ids Array [UUID] An array of Group IDs that have been mentioned in the Story description.
id Integer The ID of the iteration.
label_ids Array [Integer] An array of label ids attached to the iteration.
labels Array [Label] An array of labels attached to the iteration.
member_mention_ids Array [UUID] An array of Member IDs that have been mentioned in the Story description.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
name String The name of the iteration.
start_date Date The date this iteration begins.
stats IterationStats A group of calculated values for this Iteration.
status String The status of the iteration. Values are either “unstarted”, “started”, or “done”.
updated_at Date The instant when this iteration was last updated.

IterationAssociatedGroup

Name Description
associated_stories_count Integer The number of stories this Group owns in the Iteration.
group_id UUID The Group ID of the associated group.

IterationSearchResults

The results of the Iteration search query.

Name Description
data Array [IterationSlim] A list of search results.
next String or null The URL path and query string for the next page of search results.
total Integer The total number of matches for the search query. The first 1000 matches can be paged through via the API.

IterationSlim

IterationSlim represents the same resource as an Iteration, but is more light-weight. Use the Get Iteration endpoint to fetch the unabridged payload for an Iteration.

Name Description
app_url String The Shortcut application url for the Iteration.
created_at Date The instant when this iteration was created.
end_date Date The date this iteration ends.
entity_type String A string description of this resource
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
group_ids Array [UUID] An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
group_mention_ids Array [UUID] An array of Group IDs that have been mentioned in the Story description.
id Integer The ID of the iteration.
label_ids Array [Integer] An array of label ids attached to the iteration.
labels Array [Label] An array of labels attached to the iteration.
member_mention_ids Array [UUID] An array of Member IDs that have been mentioned in the Story description.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
name String The name of the iteration.
start_date Date The date this iteration begins.
stats IterationStats A group of calculated values for this Iteration.
status String The status of the iteration. Values are either “unstarted”, “started”, or “done”.
updated_at Date The instant when this iteration was last updated.

IterationStats

A group of calculated values for this Iteration.

Name Description
average_cycle_time Integer The average cycle time (in seconds) of completed stories in this Iteration.
average_lead_time Integer The average lead time (in seconds) of completed stories in this Iteration.
num_points Integer The total number of points in this Iteration.
num_points_backlog Integer The total number of backlog points in this Iteration.
num_points_done Integer The total number of completed points in this Iteration.
num_points_started Integer The total number of started points in this Iteration.
num_points_unstarted Integer The total number of unstarted points in this Iteration.
num_related_documents Integer The total number of documents related to an Iteration
num_stories_backlog Integer The total number of backlog Stories in this Iteration.
num_stories_done Integer The total number of done Stories in this Iteration.
num_stories_started Integer The total number of started Stories in this Iteration.
num_stories_unestimated Integer The total number of Stories with no point estimate.
num_stories_unstarted Integer The total number of unstarted Stories in this Iteration.

KeyResult

Name Description
current_observed_value KeyResultValue The starting value of the Key Result.
current_target_value KeyResultValue The starting value of the Key Result.
id UUID The ID of the Key Result.
initial_observed_value KeyResultValue The starting value of the Key Result.
name String The name of the Key Result.
objective_id Integer The Objective to which this Key Result belongs.
progress Integer The integer percentage of progress toward completion of the Key Result.
type Enum (boolean, numeric, percent) The type of the Key Result (numeric, percent, or boolean).

KeyResultValue

The starting value of the Key Result.

Name Description
boolean_value Boolean The boolean value.
numeric_value String The numeric value, as a decimal string. No more than two decimal places are allowed.

Label

A Label can be used to associate and filter Stories and Epics, and also create new Workspaces.

Name Description
app_url String The Shortcut application url for the Label.
archived Boolean A true/false boolean indicating if the Label has been archived.
color Color or null The hex color to be displayed with the Label (for example, “#ff0000”).
created_at Date or null The time/date that the Label was created.
description String or null The description of the Label.
entity_type String A string description of this resource.
external_id String or null This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here.
id Integer The unique ID of the Label.
name String The name of the Label.
stats LabelStats A group of calculated values for this Label. This is not included if the slim? flag is set to true for the List Labels endpoint.
updated_at Date or null The time/date that the Label was updated.

LabelSlim

A Label can be used to associate and filter Stories and Epics, and also create new Workspaces. A slim Label does not include aggregate stats. Fetch the Label using the labels endpoint to retrieve them.

Name Description
app_url String The Shortcut application url for the Label.
archived Boolean A true/false boolean indicating if the Label has been archived.
color Color or null The hex color to be displayed with the Label (for example, “#ff0000”).
created_at Date or null The time/date that the Label was created.
description String or null The description of the Label.
entity_type String A string description of this resource.
external_id String or null This field can be set to another unique ID. In the case that the Label has been imported from another tool, the ID in the other tool can be indicated here.
id Integer The unique ID of the Label.
name String The name of the Label.
updated_at Date or null The time/date that the Label was updated.

LabelStats

A group of calculated values for this Label. This is not included if the slim? flag is set to true for the List Labels endpoint.

Name Description
num_epics Integer The total number of Epics with this Label.
num_epics_completed Integer The number of completed Epics associated with this Label.
num_epics_in_progress Integer The number of in progress epics associated with this label.
num_epics_total Integer The total number of Epics associated with this Label.
num_epics_unstarted Integer The number of unstarted epics associated with this label.
num_points_backlog Integer The total number of backlog points with this Label.
num_points_completed Integer The total number of completed points with this Label.
num_points_in_progress Integer The total number of in-progress points with this Label.
num_points_total Integer The total number of points with this Label.
num_points_unstarted Integer The total number of unstarted points with this Label.
num_related_documents Integer The total number of Documents associated this Label.
num_stories_backlog Integer The total number of stories backlog Stories with this Label.
num_stories_completed Integer The total number of completed Stories with this Label.
num_stories_in_progress Integer The total number of in-progress Stories with this Label.
num_stories_total Integer The total number of Stories with this Label.
num_stories_unestimated Integer The total number of Stories with no point estimate with this Label.
num_stories_unstarted Integer The total number of stories unstarted Stories with this Label.

LinkedFile

Linked files are stored on a third-party website and linked to one or more Stories. Shortcut currently supports linking files from Google Drive, Dropbox, Box, and by URL.

Name Description
content_type String or null The content type of the image (e.g. txt/plain).
created_at Date The time/date the LinkedFile was created.
description String or null The description of the file.
entity_type String A string description of this resource.
group_mention_ids Array [UUID] The groups that are mentioned in the description of the file.
id Integer The unique identifier for the file.
member_mention_ids Array [UUID] The members that are mentioned in the description of the file.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
name String The name of the linked file.
size Integer or null The filesize, if the integration provided it.
story_ids Array [Integer] The IDs of the stories this file is attached to.
thumbnail_url String or null The URL of the file thumbnail, if the integration provided it.
type String The integration type (e.g. google, dropbox, box).
updated_at Date The time/date the LinkedFile was updated.
uploader_id UUID The UUID of the member that uploaded the file.
url String The URL of the file.

MaxSearchResultsExceededError

Error returned when total maximum supported results have been reached.

Name Description
error Enum (maximum-results-exceeded) The name for this type of error, maximum-results-exceeded
maximum-results Enum (1000) The maximum number of search results supported, 1000
message String An explanatory message: “A maximum of 1000 search results are supported.”

Member

Details about an individual user within the Workspace.

Name Description
created_at Date or null The time/date the Member was created.
disabled Boolean True/false boolean indicating whether the Member has been disabled within the Workspace.
entity_type String A string description of this resource.
group_ids Array [UUID] The Member’s group ids
id UUID The Member’s ID in Shortcut.
profile Profile A group of Member profile details.
role String The Member’s role in the Workspace.
state Enum (disabled, full, imported, partial) The user state, one of partial, full, disabled, or imported. A partial user is disabled, has no means to log in, and is not an import user. A full user is enabled and has a means to log in. A disabled user is disabled and has a means to log in. An import user is disabled, has no means to log in, and is marked as an import user.
updated_at Date or null The time/date the Member was last updated.

MemberInfo

Name Description
id UUID
mention_name String
name String
workspace2 BasicWorkspaceInfo

Milestone

(Deprecated) A Milestone is a collection of Epics that represent a release or some other large initiative that you are working on. Milestones have become Objectives, so you should use Objective-related API resources instead of Milestone ones.

Name Description
app_url String The Shortcut application url for the Milestone.
archived Boolean A boolean indicating whether the Milestone has been archived or not.
categories Array [Category] An array of Categories attached to the Milestone.
completed Boolean A true/false boolean indicating if the Milestone has been completed.
completed_at Date or null The time/date the Milestone was completed.
completed_at_override Date or null A manual override for the time/date the Milestone was completed.
created_at Date The time/date the Milestone was created.
description String The Milestone’s description.
entity_type String A string description of this resource.
id Integer The unique ID of the Milestone.
key_result_ids Array [UUID] The IDs of the Key Results associated with the Objective.
name String The name of the Milestone.
position Integer A number representing the position of the Milestone in relation to every other Milestone within the Workspace.
started Boolean A true/false boolean indicating if the Milestone has been started.
started_at Date or null The time/date the Milestone was started.
started_at_override Date or null A manual override for the time/date the Milestone was started.
state String The workflow state that the Milestone is in.
stats MilestoneStats A group of calculated values for this Milestone.
updated_at Date The time/date the Milestone was updated.

MilestoneStats

A group of calculated values for this Milestone.

Name Description
average_cycle_time Integer The average cycle time (in seconds) of completed stories in this Milestone.
average_lead_time Integer The average lead time (in seconds) of completed stories in this Milestone.
num_related_documents Integer The number of related documents to this Milestone.

Objective

An Objective is a collection of Epics that represent a release or some other large initiative that you are working on.

Name Description
app_url String The Shortcut application url for the Objective.
archived Boolean A boolean indicating whether the Objective has been archived or not.
categories Array [Category] An array of Categories attached to the Objective.
completed Boolean A true/false boolean indicating if the Objectivehas been completed.
completed_at Date or null The time/date the Objective was completed.
completed_at_override Date or null A manual override for the time/date the Objective was completed.
created_at Date The time/date the Objective was created.
description String The Objective’s description.
entity_type String A string description of this resource.
id Integer The unique ID of the Objective.
key_result_ids Array [UUID] The IDs of the Key Results associated with the Objective.
name String The name of the Objective.
position Integer A number representing the position of the Objective in relation to every other Objective within the Workspace.
started Boolean A true/false boolean indicating if the Objective has been started.
started_at Date or null The time/date the Objective was started.
started_at_override Date or null A manual override for the time/date the Objective was started.
state String The workflow state that the Objective is in.
stats ObjectiveStats A group of calculated values for this Objective.
updated_at Date The time/date the Objective was updated.

ObjectiveSearchResult

A Milestone in search results. This is typed differently from Milestone because the details=slim search argument will omit some fields.

Name Description
app_url String The Shortcut application url for the Milestone.
archived Boolean A boolean indicating whether the Milestone has been archived or not.
categories Array [Category] An array of Categories attached to the Milestone.
completed Boolean A true/false boolean indicating if the Milestone has been completed.
completed_at Date or null The time/date the Milestone was completed.
completed_at_override Date or null A manual override for the time/date the Milestone was completed.
created_at Date The time/date the Milestone was created.
description String The Milestone’s description.
entity_type String A string description of this resource.
id Integer The unique ID of the Milestone.
key_result_ids Array [UUID] The IDs of the Key Results associated with the Objective.
name String The name of the Milestone.
position Integer A number representing the position of the Milestone in relation to every other Milestone within the Workspace.
started Boolean A true/false boolean indicating if the Milestone has been started.
started_at Date or null The time/date the Milestone was started.
started_at_override Date or null A manual override for the time/date the Milestone was started.
state String The workflow state that the Milestone is in.
stats MilestoneStats A group of calculated values for this Milestone.
updated_at Date The time/date the Milestone was updated.

ObjectiveSearchResults

The results of the Objective search query.

Name Description
data Array [ObjectiveSearchResult] A list of search results.
next String or null The URL path and query string for the next page of search results.
total Integer The total number of matches for the search query. The first 1000 matches can be paged through via the API.

ObjectiveStats

A group of calculated values for this Objective.

Name Description
average_cycle_time Integer The average cycle time (in seconds) of completed stories in this Objective.
average_lead_time Integer The average lead time (in seconds) of completed stories in this Objective.
num_related_documents Integer The number of related documents to this Objective.

Profile

A group of Member profile details.

Name Description
deactivated Boolean A true/false boolean indicating whether the Member has been deactivated within Shortcut.
display_icon Icon or null Icons are used to attach images to Groups, Workspaces, Members, and Loading screens in the Shortcut web application.
email_address String or null The primary email address of the Member with the Organization.
entity_type String A string description of this resource.
gravatar_hash String or null This is the gravatar hash associated with email_address.
id UUID The unique identifier of the profile.
is_owner Boolean A boolean indicating whether this profile is an owner at their associated organization.
mention_name String The Member’s username within the Organization.
name String or null The Member’s name within the Organization.
two_factor_auth_activated Boolean If Two Factor Authentication is activated for this User.

Project

Projects typically map to teams (such as Frontend, Backend, Mobile, Devops, etc) but can represent any open-ended product, component, or initiative.

Name Description
abbreviation String or null The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.
app_url String The Shortcut application url for the Project.
archived Boolean True/false boolean indicating whether the Project is in an Archived state.
color Color or null The color associated with the Project in the Shortcut member interface.
created_at Date or null The time/date that the Project was created.
days_to_thermometer Integer The number of days before the thermometer appears in the Story summary.
description String or null The description of the Project.
entity_type String A string description of this resource.
external_id String or null This field can be set to another unique ID. In the case that the Project has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
id Integer The unique ID of the Project.
iteration_length Integer The number of weeks per iteration in this Project.
name String The name of the Project
show_thermometer Boolean Configuration to enable or disable thermometers in the Story summary.
start_time Date The date at which the Project was started.
stats ProjectStats A group of calculated values for this Project.
team_id Integer The ID of the team the project belongs to.
updated_at Date or null The time/date that the Project was last updated.
workflow_id Integer The ID of the workflow the project belongs to.

ProjectStats

A group of calculated values for this Project.

Name Description
num_points Integer The total number of points in this Project.
num_related_documents Integer The total number of documents related to this Project
num_stories Integer The total number of stories in this Project.

PullRequest

Corresponds to a VCS Pull Request attached to a Shortcut story.

Name Description
branch_id Integer The ID of the branch for the particular pull request.
branch_name String The name of the branch for the particular pull request.
build_status String The status of the Continuous Integration workflow for the pull request.
closed Boolean True/False boolean indicating whether the VCS pull request has been closed.
created_at Date The time/date the pull request was created.
draft Boolean True/False boolean indicating whether the VCS pull request is in the draft state.
entity_type String A string description of this resource.
has_overlapping_stories Boolean Boolean indicating that the Pull Request has Stories that have Pull Requests that change at least one of the same lines this Pull Request changes.
id Integer The unique ID associated with the pull request in Shortcut.
merged Boolean True/False boolean indicating whether the VCS pull request has been merged.
num_added Integer Number of lines added in the pull request, according to VCS.
num_commits Integer or null The number of commits on the pull request.
num_modified Integer or null Number of lines modified in the pull request, according to VCS.
num_removed Integer Number of lines removed in the pull request, according to VCS.
number Integer The pull request’s unique number ID in VCS.
overlapping_stories Array [Integer] An array of Story ids that have Pull Requests that change at least one of the same lines this Pull Request changes.
repository_id Integer The ID of the repository for the particular pull request.
review_status String The status of the review for the pull request.
target_branch_id Integer The ID of the target branch for the particular pull request.
target_branch_name String The name of the target branch for the particular pull request.
title String The title of the pull request.
updated_at Date The time/date the pull request was created.
url String The URL for the pull request.
vcs_labels Array [PullRequestLabel] or null An array of PullRequestLabels attached to the PullRequest.

PullRequestLabel

Corresponds to a VCS Label associated with a Pull Request.

Name Description
color Color The color of the VCS label.
description String or null The description of the VCS label.
entity_type String A string description of this resource.
id Integer The unique ID of the VCS Label.
name String The name of the VCS label.

RemoveCustomFieldParams

Name Description
field_id UUID The unique public ID for the CustomField.

RemoveLabelParams

Request parameters for removing a Label from a Shortcut Story.

Name Description
name String (128) The name of the new Label to remove.

Repository

Repository refers to a VCS repository.

Name Description
created_at Date or null The time/date the Repository was created.
entity_type String A string description of this resource.
external_id String or null The VCS unique identifier for the Repository.
full_name String or null The full name of the VCS repository.
id Integer or null The ID associated to the VCS repository in Shortcut.
name String or null The shorthand name of the VCS repository.
type Enum (bitbucket, github, gitlab) The VCS provider for the Repository.
updated_at Date or null The time/date the Repository was updated.
url String or null The URL of the Repository.

SearchResults

The results of the multi-entity search query.

Name Description
epics EpicSearchResults The results of the Epic search query.
iterations IterationSearchResults The results of the Iteration search query.
milestones ObjectiveSearchResults The results of the Objective search query.
stories StorySearchResults The results of the Story search query.

SearchStories

Name Description
archived Boolean A true/false boolean indicating whether the Story is in archived state.
completed_at_end Date Stories should have been completed on or before this date.
completed_at_start Date Stories should have been completed on or after this date.
created_at_end Date Stories should have been created on or before this date.
created_at_start Date Stories should have been created on or after this date.
deadline_end Date Stories should have a deadline on or before this date.
deadline_start Date Stories should have a deadline on or after this date.
epic_id Integer or null The Epic IDs that may be associated with the Stories.
epic_ids Array [Integer] The Epic IDs that may be associated with the Stories.
estimate Integer The number of estimate points associate with the Stories.
external_id String (1024) An ID or URL that references an external resource. Useful during imports.
group_id UUID or null The Group ID that is associated with the Stories
group_ids Array [UUID] The Group IDs that are associated with the Stories
includes_description Boolean Whether to include the story description in the response.
iteration_id Integer or null The Iteration ID that may be associated with the Stories.
iteration_ids Array [Integer] The Iteration IDs that may be associated with the Stories.
label_ids Array [Integer] The Label IDs that may be associated with the Stories.
label_name String The name of any associated Labels.
owner_id UUID or null An array of UUIDs for any Users who may be Owners of the Stories.
owner_ids Array [UUID] An array of UUIDs for any Users who may be Owners of the Stories.
project_id Integer or null The IDs for the Projects the Stories may be assigned to.
project_ids Array [Integer or null] The IDs for the Projects the Stories may be assigned to.
requested_by_id UUID The UUID of any Users who may have requested the Stories.
story_type Enum (bug, chore, feature) The type of Stories that you want returned.
updated_at_end Date Stories should have been updated on or before this date.
updated_at_start Date Stories should have been updated on or after this date.
workflow_state_id Integer The unique IDs of the specific Workflow States that the Stories should be in.
workflow_state_types Array [Enum (backlog, done, started, unstarted)] The type of Workflow State the Stories may be in.

Story

Stories are the standard unit of work in Shortcut and represent individual features, bugs, and chores.

Name Description
app_url String The Shortcut application url for the Story.
archived Boolean True if the story has been archived or not.
blocked Boolean A true/false boolean indicating if the Story is currently blocked.
blocker Boolean A true/false boolean indicating if the Story is currently a blocker of another story.
branches Array [Branch] An array of Git branches attached to the story.
comments Array [StoryComment] An array of comments attached to the story.
commits Array [Commit] An array of commits attached to the story.
completed Boolean A true/false boolean indicating if the Story has been completed.
completed_at Date or null The time/date the Story was completed.
completed_at_override Date or null A manual override for the time/date the Story was completed.
created_at Date The time/date the Story was created.
custom_fields Array [StoryCustomField] An array of CustomField value assertions for the story.
cycle_time Integer The cycle time (in seconds) of this story when complete.
deadline Date or null The due date of the story.
description String The description of the story.
entity_type String A string description of this resource.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_id String or null This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
external_links Array [String] An array of external links (strings) associated with a Story
files Array [UploadedFile] An array of files attached to the story.
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
group_id UUID or null The ID of the group associated with the story.
group_mention_ids Array [UUID] An array of Group IDs that have been mentioned in the Story description.
id Integer The unique ID of the Story.
iteration_id Integer or null The ID of the iteration the story belongs to.
label_ids Array [Integer] An array of label ids attached to the story.
labels Array [LabelSlim] An array of labels attached to the story.
lead_time Integer The lead time (in seconds) of this story when complete.
linked_files Array [LinkedFile] An array of linked files attached to the story.
member_mention_ids Array [UUID] An array of Member IDs that have been mentioned in the Story description.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
moved_at Date or null The time/date the Story was last changed workflow-state.
name String The name of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
position Integer A number representing the position of the story in relation to every other story in the current project.
previous_iteration_ids Array [Integer] The IDs of the iteration the story belongs to.
project_id Integer or null The ID of the project the story belongs to.
pull_requests Array [PullRequest] An array of Pull/Merge Requests attached to the story.
requested_by_id UUID The ID of the Member that requested the story.
started Boolean A true/false boolean indicating if the Story has been started.
started_at Date or null The time/date the Story was started.
started_at_override Date or null A manual override for the time/date the Story was started.
stats StoryStats The stats object for Stories
story_links Array [TypedStoryLink] An array of story links attached to the Story.
story_template_id UUID or null The ID of the story template used to create this story, or null if not created using a template.
story_type String The type of story (feature, bug, chore).
synced_item SyncedItem The synced item for the story.
tasks Array [Task] An array of tasks connected to the story.
unresolved_blocker_comments Array [Integer] The IDs of any unresolved blocker comments on the Story.
updated_at Date or null The time/date the Story was updated.
workflow_id Integer The ID of the workflow the story belongs to.
workflow_state_id Integer The ID of the workflow state the story is currently in.

StoryComment

A Comment is any note added within the Comment field of a Story.

Name Description
app_url String The Shortcut application url for the Comment.
author_id UUID or null The unique ID of the Member who is the Comment’s author.
blocker Boolean Marks the comment as a blocker that can be surfaced to permissions or teams mentioned in the comment. Can only be used on a top-level comment.
created_at Date The time/date when the Comment was created.
deleted Boolean True/false boolean indicating whether the Comment has been deleted.
entity_type String A string description of this resource.
external_id String or null This field can be set to another unique ID. In the case that the Comment has been imported from another tool, the ID in the other tool can be indicated here.
group_mention_ids Array [UUID] The unique IDs of the Group who are mentioned in the Comment.
id Integer The unique ID of the Comment.
linked_to_slack Boolean Whether the Comment is currently the root of a thread that is linked to Slack.
member_mention_ids Array [UUID] The unique IDs of the Member who are mentioned in the Comment.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
parent_id Integer or null The ID of the parent Comment this Comment is threaded under.
position Integer The Comments numerical position in the list from oldest to newest.
story_id Integer The ID of the Story on which the Comment appears.
text String or null The text of the Comment. In the case that the Comment has been deleted, this field can be set to nil.
unblocks_parent Boolean Marks the comment as an unblocker to its blocker parent. Can only be set on a threaded comment who has a parent with blocker set.
updated_at Date or null The time/date when the Comment was updated.

StoryContents

A container entity for the attributes this template should populate.

Name Description
custom_fields Array [CustomFieldValueParams] An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
deadline Date The due date of the story.
description String The description of the story.
entity_type String A string description of this resource.
epic_id Integer The ID of the epic the story belongs to.
estimate Integer The numeric point estimate of the story. Can also be null, which means unestimated.
external_links Array [String] An array of external links connected to the story.
files Array [UploadedFile] An array of files attached to the story.
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
group_id UUID The ID of the group to which the story is assigned.
iteration_id Integer The ID of the iteration the story belongs to.
label_ids Array [Integer] An array of label ids attached to the story.
labels Array [LabelSlim] An array of labels attached to the story.
linked_files Array [LinkedFile] An array of linked files attached to the story.
name String The name of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
project_id Integer The ID of the project the story belongs to.
story_type String The type of story (feature, bug, chore).
tasks Array [StoryContentsTask] An array of tasks connected to the story.
workflow_state_id Integer The ID of the workflow state the story is currently in.

StoryContentsTask

Name Description
complete Boolean True/false boolean indicating whether the Task has been completed.
description String Full text of the Task.
external_id String or null This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.
owner_ids Array [UUID] An array of UUIDs of the Owners of this Task.
position Integer The number corresponding to the Task’s position within a list of Tasks on a Story.

StoryCustomField

Name Description
field_id UUID The unique public ID for a CustomField.
value String A string representation of the value, if applicable.
value_id UUID The unique public ID for a CustomFieldEnumValue.

StoryHistoryChangeAddsRemovesInt

Task IDs that have been added or removed from the Story.

Name Description
adds Array [Integer] The values that have been added.
removes Array [Integer] The values that have been removed

StoryHistoryChangeAddsRemovesUuid

Custom Field Enum Value IDs that have been added or removed from the Story.

Name Description
adds Array [UUID] The values that have been added.
removes Array [UUID] The values that have been removed

StoryHistoryChangeOldNewBool

True if the Story has archived, otherwise false.

Name Description
new Boolean The new value.
old Boolean The old value.

StoryHistoryChangeOldNewInt

The estimate value for the Story

Name Description
new Integer The new value.
old Integer The old value.

StoryHistoryChangeOldNewStr

A timestamp that represents the Story’s deadline.

Name Description
new String The new value.
old String or null The old value.

StoryHistoryChangeOldNewUuid

The Team ID for the Story.

Name Description
new UUID The new value.
old UUID The old value.

Story links allow you create semantic relationships between two stories. Relationship types are relates to, blocks / blocked by, and duplicates / is duplicated by. The format is subject -> link -> object, or for example “story 5 blocks story 6”.

Name Description
created_at Date The time/date when the Story Link was created.
entity_type String A string description of this resource.
id Integer The unique identifier of the Story Link.
object_id Integer The ID of the object Story.
subject_id Integer The ID of the subject Story.
updated_at Date The time/date when the Story Link was last updated.
verb String How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”.

StoryReaction

Emoji reaction on a comment.

Name Description
emoji String Emoji text of the reaction.
permission_ids Array [UUID] Permissions who have reacted with this.

StorySearchResult

A Story in search results. This is typed differently from Story because the details=slim search argument will omit some fields.

Name Description
app_url String The Shortcut application url for the Story.
archived Boolean True if the story has been archived or not.
blocked Boolean A true/false boolean indicating if the Story is currently blocked.
blocker Boolean A true/false boolean indicating if the Story is currently a blocker of another story.
branches Array [Branch] An array of Git branches attached to the story.
comment_ids Array [Integer] An array of IDs of Comments attached to the story.
comments Array [StoryComment] An array of comments attached to the story.
commits Array [Commit] An array of commits attached to the story.
completed Boolean A true/false boolean indicating if the Story has been completed.
completed_at Date or null The time/date the Story was completed.
completed_at_override Date or null A manual override for the time/date the Story was completed.
created_at Date The time/date the Story was created.
custom_fields Array [StoryCustomField] An array of CustomField value assertions for the story.
cycle_time Integer The cycle time (in seconds) of this story when complete.
deadline Date or null The due date of the story.
description String The description of the story.
entity_type String A string description of this resource.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_id String or null This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
external_links Array [String] An array of external links (strings) associated with a Story
file_ids Array [Integer] An array of IDs of Files attached to the story.
files Array [UploadedFile] An array of files attached to the story.
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
group_id UUID or null The ID of the group associated with the story.
group_mention_ids Array [UUID] An array of Group IDs that have been mentioned in the Story description.
id Integer The unique ID of the Story.
iteration_id Integer or null The ID of the iteration the story belongs to.
label_ids Array [Integer] An array of label ids attached to the story.
labels Array [LabelSlim] An array of labels attached to the story.
lead_time Integer The lead time (in seconds) of this story when complete.
linked_file_ids Array [Integer] An array of IDs of LinkedFiles attached to the story.
linked_files Array [LinkedFile] An array of linked files attached to the story.
member_mention_ids Array [UUID] An array of Member IDs that have been mentioned in the Story description.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
moved_at Date or null The time/date the Story was last changed workflow-state.
name String The name of the story.
num_tasks_completed Integer The number of tasks on the story which are complete.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
position Integer A number representing the position of the story in relation to every other story in the current project.
previous_iteration_ids Array [Integer] The IDs of the iteration the story belongs to.
project_id Integer or null The ID of the project the story belongs to.
pull_requests Array [PullRequest] An array of Pull/Merge Requests attached to the story.
requested_by_id UUID The ID of the Member that requested the story.
started Boolean A true/false boolean indicating if the Story has been started.
started_at Date or null The time/date the Story was started.
started_at_override Date or null A manual override for the time/date the Story was started.
stats StoryStats The stats object for Stories
story_links Array [TypedStoryLink] An array of story links attached to the Story.
story_template_id UUID or null The ID of the story template used to create this story, or null if not created using a template.
story_type String The type of story (feature, bug, chore).
synced_item SyncedItem The synced item for the story.
task_ids Array [Integer] An array of IDs of Tasks attached to the story.
tasks Array [Task] An array of tasks connected to the story.
unresolved_blocker_comments Array [Integer] The IDs of any unresolved blocker comments on the Story.
updated_at Date or null The time/date the Story was updated.
workflow_id Integer The ID of the workflow the story belongs to.
workflow_state_id Integer The ID of the workflow state the story is currently in.

StorySearchResults

The results of the Story search query.

Name Description
data Array [StorySearchResult] A list of search results.
next String or null The URL path and query string for the next page of search results.
total Integer The total number of matches for the search query. The first 1000 matches can be paged through via the API.

StorySlim

StorySlim represents the same resource as a Story, but is more light-weight. For certain fields it provides ids rather than full resources (e.g., comment_ids and file_ids) and it also excludes certain aggregate values (e.g., cycle_time). The description field can be optionally included. Use the Get Story endpoint to fetch the unabridged payload for a Story.

Name Description
app_url String The Shortcut application url for the Story.
archived Boolean True if the story has been archived or not.
blocked Boolean A true/false boolean indicating if the Story is currently blocked.
blocker Boolean A true/false boolean indicating if the Story is currently a blocker of another story.
comment_ids Array [Integer] An array of IDs of Comments attached to the story.
completed Boolean A true/false boolean indicating if the Story has been completed.
completed_at Date or null The time/date the Story was completed.
completed_at_override Date or null A manual override for the time/date the Story was completed.
created_at Date The time/date the Story was created.
custom_fields Array [StoryCustomField] An array of CustomField value assertions for the story.
cycle_time Integer The cycle time (in seconds) of this story when complete.
deadline Date or null The due date of the story.
description String The description of the Story.
entity_type String A string description of this resource.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_id String or null This field can be set to another unique ID. In the case that the Story has been imported from another tool, the ID in the other tool can be indicated here.
external_links Array [String] An array of external links (strings) associated with a Story
file_ids Array [Integer] An array of IDs of Files attached to the story.
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
group_id UUID or null The ID of the group associated with the story.
group_mention_ids Array [UUID] An array of Group IDs that have been mentioned in the Story description.
id Integer The unique ID of the Story.
iteration_id Integer or null The ID of the iteration the story belongs to.
label_ids Array [Integer] An array of label ids attached to the story.
labels Array [LabelSlim] An array of labels attached to the story.
lead_time Integer The lead time (in seconds) of this story when complete.
linked_file_ids Array [Integer] An array of IDs of LinkedFiles attached to the story.
member_mention_ids Array [UUID] An array of Member IDs that have been mentioned in the Story description.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
moved_at Date or null The time/date the Story was last changed workflow-state.
name String The name of the story.
num_tasks_completed Integer The number of tasks on the story which are complete.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
position Integer A number representing the position of the story in relation to every other story in the current project.
previous_iteration_ids Array [Integer] The IDs of the iteration the story belongs to.
project_id Integer or null The ID of the project the story belongs to.
requested_by_id UUID The ID of the Member that requested the story.
started Boolean A true/false boolean indicating if the Story has been started.
started_at Date or null The time/date the Story was started.
started_at_override Date or null A manual override for the time/date the Story was started.
stats StoryStats The stats object for Stories
story_links Array [TypedStoryLink] An array of story links attached to the Story.
story_template_id UUID or null The ID of the story template used to create this story, or null if not created using a template.
story_type String The type of story (feature, bug, chore).
synced_item SyncedItem The synced item for the story.
task_ids Array [Integer] An array of IDs of Tasks attached to the story.
unresolved_blocker_comments Array [Integer] The IDs of any unresolved blocker comments on the Story.
updated_at Date or null The time/date the Story was updated.
workflow_id Integer The ID of the workflow the story belongs to.
workflow_state_id Integer The ID of the workflow state the story is currently in.

StoryStats

The stats object for Stories

Name Description
num_related_documents Integer The number of documents related to this Story.

SyncedItem

The synced item for the story.

Name Description
external_id String The id used to reference an external entity.
url String The url to the external entity.

Task

A Task on a Story.

Name Description
complete Boolean True/false boolean indicating whether the Task has been completed.
completed_at Date or null The time/date the Task was completed.
created_at Date The time/date the Task was created.
description String Full text of the Task.
entity_type String A string description of this resource.
external_id String or null This field can be set to another unique ID. In the case that the Task has been imported from another tool, the ID in the other tool can be indicated here.
group_mention_ids Array [UUID] An array of UUIDs of Groups mentioned in this Task.
id Integer The unique ID of the Task.
member_mention_ids Array [UUID] An array of UUIDs of Members mentioned in this Task.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
owner_ids Array [UUID] An array of UUIDs of the Owners of this Task.
position Integer The number corresponding to the Task’s position within a list of Tasks on a Story.
story_id Integer The unique identifier of the parent Story.
updated_at Date or null The time/date the Task was updated.

ThreadedComment

Comments associated with Epic Discussions.

Name Description
app_url String The Shortcut application url for the Comment.
author_id UUID The unique ID of the Member that authored the Comment.
comments Array [ThreadedComment] A nested array of threaded comments.
created_at Date The time/date the Comment was created.
deleted Boolean True/false boolean indicating whether the Comment is deleted.
entity_type String A string description of this resource.
external_id String or null This field can be set to another unique ID. In the case that the Comment has been imported from another tool, the ID in the other tool can be indicated here.
group_mention_ids Array [UUID] An array of Group IDs that have been mentioned in this Comment.
id Integer The unique ID of the Comment.
member_mention_ids Array [UUID] An array of Member IDs that have been mentioned in this Comment.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
text String The text of the Comment.
updated_at Date The time/date the Comment was updated.

The type of Story Link. The string can be subject or object.

Name Description
created_at Date The time/date when the Story Link was created.
entity_type String A string description of this resource.
id Integer The unique identifier of the Story Link.
object_id Integer The ID of the object Story.
subject_id Integer The ID of the subject Story.
type String This indicates whether the Story is the subject or object in the Story Link.
updated_at Date The time/date when the Story Link was last updated.
verb String How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”.

UnusableEntitlementError

Name Description
entitlement_tag String (63) Short tag describing the unusable entitlement action taken by the user.
message String (256) Message displayed to the user on why their action failed.
reason_tag Enum (entitlement-violation) The tag for violating an entitlement action.

UpdateCategory

Name Description
archived Boolean A true/false boolean indicating if the Category has been archived.
color Color or null The hex color to be displayed with the Category (for example, “#ff0000”).
name String The new name of the Category.

UpdateComment

Name Description
text String The updated comment text.

UpdateCustomField

Name Description
after_id UUID The ID of the CustomField we want to move this CustomField after.
before_id UUID The ID of the CustomField we want to move this CustomField before.
description String A description of the purpose of this field.
enabled Boolean Indicates whether the Field is enabled for the Workspace. Only enabled fields can be applied to Stories.
icon_set_identifier String (63) A frontend-controlled string that represents the icon for this custom field.
name String (63) A collection of objects representing reporting periods for years.
values Array [UpdateCustomFieldEnumValue] A collection of EnumValue objects representing the values in the domain of some Custom Field.

UpdateCustomFieldEnumValue

Name Description
color_key String or null A color key associated with this EnumValue within the CustomField’s domain.
enabled Boolean Whether this EnumValue is enabled for its CustomField or not. Leaving this key out of the request leaves the current enabled state untouched.
id UUID The unique ID of an existing EnumValue within the CustomField’s domain.
value String (63) A string value within the domain of this Custom Field.

UpdateEntityTemplate

Request parameters for changing either a template’s name or any of
the attributes it is designed to pre-populate.

Name Description
name String (128) The updated template name.
story_contents UpdateStoryContents Updated attributes for the template to populate.

UpdateEpic

Name Description
after_id Integer The ID of the Epic we want to move this Epic after.
archived Boolean A true/false boolean indicating whether the Epic is in archived state.
before_id Integer The ID of the Epic we want to move this Epic before.
completed_at_override Date or null A manual override for the time/date the Epic was completed.
deadline Date or null The Epic’s deadline.
description String (100000) The Epic’s description.
epic_state_id Integer The ID of the Epic State.
external_id String (128) This field can be set to another unique ID. In the case that the Epic has been imported from another tool, the ID in the other tool can be indicated here.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers on this Epic.
group_id UUID or null Deprecated The ID of the group to associate with the epic. Use group_ids.
group_ids Array [UUID] An array of UUIDS for Groups to which this Epic is related.
labels Array [CreateLabelParams] An array of Labels attached to the Epic.
milestone_id Integer or null Deprecated The ID of the Milestone this Epic is related to. Use objective_ids.
name String (256) The Epic’s name.
objective_ids Array [Integer] An array of IDs for Objectives to which this Epic is related.
owner_ids Array [UUID] An array of UUIDs for any members you want to add as Owners on this Epic.
planned_start_date Date or null The Epic’s planned start date.
requested_by_id UUID The ID of the member that requested the epic.
started_at_override Date or null A manual override for the time/date the Epic was started.
state Enum (done, in progress, to do) Deprecated The Epic’s state (to do, in progress, or done); will be ignored when epic_state_id is set.

UpdateFile

Name Description
created_at Date The time/date that the file was uploaded.
description String (4096) The description of the file.
external_id String (128) An additional ID that you may wish to assign to the file.
name String (1024) The name of the file.
updated_at Date The time/date that the file was last updated.
uploader_id UUID The unique ID assigned to the Member who uploaded the file to Shortcut.

UpdateGroup

Name Description
archived Boolean or null Whether or not this Group is archived.
color Color or null The color you wish to use for the Group in the system.
color_key Enum (black, blue, brass, fuchsia, gray, green, midnight-blue, orange, pink, purple, red, sky-blue, slate, turquoise, yellow, yellow-green) The color key you wish to use for the Group in the system.
description String (4096) The description of this Group.
display_icon_id UUID or null The Icon id for the avatar of this Group.
member_ids Array [UUID] The Member ids to add to this Group.
mention_name String (63) The mention name of this Group.
name String (63) The name of this Group.
workflow_ids Array [Integer] The Workflow ids to add to the Group.

UpdateIteration

Name Description
description String (100000) The description of the Iteration.
end_date String The date this Iteration ends, e.g. 2019-07-05.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers.
group_ids Array [UUID] An array of UUIDs for any Groups you want to add as Followers. Currently, only one Group association is presented in our web UI.
labels Array [CreateLabelParams] An array of Labels attached to the Iteration.
name String (256) The name of this Iteration
start_date String The date this Iteration begins, e.g. 2019-07-01

UpdateKeyResult

Name Description
initial_observed_value KeyResultValue The starting value of the Key Result.
name String (1024) The name of the Key Result.
observed_value KeyResultValue The starting value of the Key Result.
target_value KeyResultValue The starting value of the Key Result.

UpdateLabel

Name Description
archived Boolean A true/false boolean indicating if the Label has been archived.
color Color or null The hex color to be displayed with the Label (for example, “#ff0000”).
description String (1024) The new description of the label.
name String (128) The new name of the label.

UpdateLinkedFile

Name Description
description String (512) The description of the file.
name String The name of the file.
size Integer The filesize, if the integration provided it.
story_id Integer The ID of the linked story.
thumbnail_url String (2048) The URL of the thumbnail, if the integration provided it.
type Enum (box, dropbox, google, onedrive, url) The integration type of the file (e.g. google, dropbox, box).
uploader_id UUID The UUID of the member that uploaded the file.
url String (2048) The URL of linked file.

UpdateMilestone

Name Description
after_id Integer The ID of the Milestone we want to move this Milestone after.
archived Boolean A boolean indicating whether the Milestone is archived or not
before_id Integer The ID of the Milestone we want to move this Milestone before.
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Milestone.
completed_at_override Date or null A manual override for the time/date the Milestone was completed.
description String (100000) The Milestone’s description.
name String (256) The name of the Milestone.
started_at_override Date or null A manual override for the time/date the Milestone was started.
state Enum (done, in progress, to do) The workflow state that the Milestone is in.

UpdateObjective

Name Description
after_id Integer The ID of the Objective we want to move this Objective after.
archived Boolean A boolean indicating whether the Objective is archived or not
before_id Integer The ID of the Objective we want to move this Objective before.
categories Array [CreateCategoryParams] An array of IDs of Categories attached to the Objective.
completed_at_override Date or null A manual override for the time/date the Objective was completed.
description String (100000) The Objective’s description.
name String (256) The name of the Objective.
started_at_override Date or null A manual override for the time/date the Objective was started.
state Enum (done, in progress, to do) The workflow state that the Objective is in.

UpdateProject

Name Description
abbreviation String The Project abbreviation used in Story summaries. Should be kept to 3 characters at most.
archived Boolean A true/false boolean indicating whether the Story is in archived state.
color Color The color that represents the Project in the UI.
days_to_thermometer Integer The number of days before the thermometer appears in the Story summary.
description String (100000) The Project’s description.
follower_ids Array [UUID] An array of UUIDs for any Members you want to add as Followers.
name String (128) The Project’s name.
show_thermometer Boolean Configuration to enable or disable thermometers in the Story summary.
team_id Integer The ID of the team the project belongs to.

UpdateStories

Name Description
after_id Integer The ID of the story that the stories are to be moved below.
archived Boolean If the Stories should be archived or not.
before_id Integer The ID of the story that the stories are to be moved before.
custom_fields_add Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
custom_fields_remove Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
deadline Date or null The due date of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_links Array [String] An array of External Links associated with this story.
follower_ids_add Array [UUID] The UUIDs of the new followers to be added.
follower_ids_remove Array [UUID] The UUIDs of the followers to be removed.
group_id UUID or null The Id of the Group the Stories should belong to.
iteration_id Integer or null The ID of the iteration the story belongs to.
labels_add Array [CreateLabelParams] An array of labels to be added.
labels_remove Array [CreateLabelParams] An array of labels to be removed.
move_to Enum (first, last) One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state.
owner_ids_add Array [UUID] The UUIDs of the new owners to be added.
owner_ids_remove Array [UUID] The UUIDs of the owners to be removed.
project_id Integer or null The ID of the Project the Stories should belong to.
requested_by_id UUID The ID of the member that requested the story.
story_ids Array [Integer] The Ids of the Stories you wish to update.
story_type Enum (bug, chore, feature) The type of story (feature, bug, chore).
workflow_state_id Integer The ID of the workflow state to put the stories in.

UpdateStory

Name Description
after_id Integer The ID of the story we want to move this story after.
archived Boolean True if the story is archived, otherwise false.
before_id Integer The ID of the story we want to move this story before.
branch_ids Array [Integer] An array of IDs of Branches attached to the story.
commit_ids Array [Integer] An array of IDs of Commits attached to the story.
completed_at_override Date or null A manual override for the time/date the Story was completed.
custom_fields Array [CustomFieldValueParams] A map specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
deadline Date or null The due date of the story.
description String (100000) The description of the story.
epic_id Integer or null The ID of the epic the story belongs to.
estimate Integer or null The numeric point estimate of the story. Can also be null, which means unestimated.
external_links Array [String] An array of External Links associated with this story.
file_ids Array [Integer] An array of IDs of files attached to the story.
follower_ids Array [UUID] An array of UUIDs of the followers of this story.
group_id UUID or null The ID of the group to associate with this story
iteration_id Integer or null The ID of the iteration the story belongs to.
labels Array [CreateLabelParams] An array of labels attached to the story.
linked_file_ids Array [Integer] An array of IDs of linked files attached to the story.
move_to Enum (first, last) One of “first” or “last”. This can be used to move the given story to the first or last position in the workflow state.
name String (512) The title of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
project_id Integer or null The ID of the project the story belongs to.
pull_request_ids Array [Integer] An array of IDs of Pull/Merge Requests attached to the story.
requested_by_id UUID The ID of the member that requested the story.
started_at_override Date or null A manual override for the time/date the Story was started.
story_type Enum (bug, chore, feature) The type of story (feature, bug, chore).
workflow_state_id Integer The ID of the workflow state to put the story in.

UpdateStoryComment

Name Description
text String (100000) The updated comment text.

UpdateStoryContents

Updated attributes for the template to populate.

Name Description
custom_fields Array [CustomFieldValueParams] An array of maps specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a CustomField.
deadline Date or null The due date of the story.
description String The description of the story.
epic_id Integer or null The ID of the epic the to be populated.
estimate Integer or null The numeric point estimate to be populated.
external_links Array [String] An array of external links to be populated.
file_ids Array [Integer] An array of the attached file IDs to be populated.
follower_ids Array [UUID] An array of UUIDs for any Members listed as Followers.
group_id UUID or null The ID of the group to be populated.
iteration_id Integer or null The ID of the iteration the to be populated.
labels Array [CreateLabelParams] An array of labels to be populated by the template.
linked_file_ids Array [Integer] An array of the linked file IDs to be populated.
name String The name of the story.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.
project_id Integer or null The ID of the project the story belongs to.
story_type String The type of story (feature, bug, chore).
tasks Array [BaseTaskParams] An array of tasks to be populated by the template.
workflow_state_id Integer or null The ID of the workflow state to be populated.
Name Description
object_id Integer The ID of the object Story.
subject_id Integer The ID of the subject Story.
verb Enum (blocks, duplicates, relates to) The type of link.

UpdateTask

Name Description
after_id Integer Move task after this task ID.
before_id Integer Move task before this task ID.
complete Boolean A true/false boolean indicating whether the task is complete.
description String (2048) The Task’s description.
owner_ids Array [UUID] An array of UUIDs of the owners of this story.

UploadedFile

An UploadedFile is any document uploaded to your Shortcut Workspace. Files attached from a third-party service are different: see the Linked Files endpoint.

Name Description
content_type String Free form string corresponding to a text or image file.
created_at Date The time/date that the file was created.
description String or null The description of the file.
entity_type String A string description of this resource.
external_id String or null This field can be set to another unique ID. In the case that the File has been imported from another tool, the ID in the other tool can be indicated here.
filename String The name assigned to the file in Shortcut upon upload.
group_mention_ids Array [UUID] The unique IDs of the Groups who are mentioned in the file description.
id Integer The unique ID for the file.
member_mention_ids Array [UUID] The unique IDs of the Members who are mentioned in the file description.
mention_ids Array [UUID] Deprecated: use member_mention_ids.
name String The optional User-specified name of the file.
size Integer The size of the file.
story_ids Array [Integer] The unique IDs of the Stories associated with this file.
thumbnail_url String or null The url where the thumbnail of the file can be found in Shortcut.
updated_at Date or null The time/date that the file was updated.
uploader_id UUID The unique ID of the Member who uploaded the file.
url String or null The URL for the file.

Workflow

Workflow is the array of defined Workflow States. Workflow can be queried using the API but must be updated in the Shortcut UI.

Name Description
auto_assign_owner Boolean Indicates if an owner is automatically assigned when an unowned story is started.
created_at Date The date the Workflow was created.
default_state_id Integer The unique ID of the default state that new Stories are entered into.
description String A description of the workflow.
entity_type String A string description of this resource.
id Integer The unique ID of the Workflow.
name String The name of the workflow.
project_ids Array [Integer] An array of IDs of projects within the Workflow.
states Array [WorkflowState] A map of the states in this Workflow.
team_id Integer The ID of the team the workflow belongs to.
updated_at Date The date the Workflow was updated.

WorkflowState

Workflow State is any of the at least 3 columns. Workflow States correspond to one of 3 types: Unstarted, Started, or Done.

Name Description
color Color The hex color for this Workflow State.
created_at Date The time/date the Workflow State was created.
description String The description of what sort of Stories belong in that Workflow state.
entity_type String A string description of this resource.
id Integer The unique ID of the Workflow State.
name String The Workflow State’s name.
num_stories Integer The number of Stories currently in that Workflow State.
num_story_templates Integer The number of Story Templates associated with that Workflow State.
position Integer The position that the Workflow State is in, starting with 0 at the left.
type String The type of Workflow State (Unstarted, Started, or Finished)
updated_at Date When the Workflow State was last updated.
verb String or null The verb that triggers a move to that Workflow State when making VCS commits.