Last updated: Saturday, June 27, 2026

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 an alpha version of the Shortcut API. The API may change in backwards-incompatible ways during this period. We recommend pinning to a specific version and reviewing the changelog before upgrading.

Examples

See our API Cookbook for real-life examples of using the API.

Authentication

API URL

https://api.app.shortcut.com/

API Authentication Header

Authorization: Bearer <your-token-here>

URL https://api.app.shortcut.com/
Headers
- Authorization: Bearer <your-token-here>
- Content-Type: application/json

The Shortcut API uses token-based authentication. To generate an API token, go to https://app.shortcut.com/settings/account/api-tokens.

v4 tokens start with sct_ro_ (read-only) or sct_rw_ (read-write). Use these new tokens when making v4 API requests — v3 tokens will not work with v4 endpoints.

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.

Workspace Slug

Most v4 API endpoints require a workspace-slug path parameter, for example:

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics
Authorization: Bearer sct_rw_...

The workspace slug identifies which workspace you are operating on. You can find your workspace slug by calling the Whoami endpoint:

curl -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/whoami"

The response includes a workspace.slug field containing your workspace slug.

List endpoints in v4 return paginated results. Responses include a next_page_url field — if present, pass its cursor query parameter to retrieve the next page of results:

curl -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics?cursor=<cursor>"

When next_page_url is absent, you have reached the last page. The limit query parameter (1–100, default 10) controls how many results are returned per page.

Field Filtering

Most endpoints support a fields query parameter that lets you request only specific fields in the response. This can reduce response size and improve performance when you only need a subset of an entity’s data.

Pass a comma-separated list of field names:

curl -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics?fields=id,name,updated_at"

If fields is omitted, all fields are returned. Passing an invalid field name will return a 400 Bad Request response.

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.

OpenAPI file

We provide a machine-readable version of our API in OpenAPI 3.0. You can download a JSON version here:

OpenAPI 3.0

Migrating from v3 to v4

v4 introduces several changes from v3:

Workspace slug: Most endpoints now require a {workspace-slug} path segment (e.g. /api/v4/{workspace-slug}/stories instead of /api/v3/stories). Use the Whoami endpoint to retrieve your workspace slug.
Pagination: List endpoints now return paginated responses with a next_page_url cursor instead of returning all results at once.
Response envelope: Responses are wrapped in an envelope with entity (single resource) or entities (list) fields alongside a $schema field.

{schema-Name}

Get Schema

Gets the json-schema for a route.

Definition

GET https://api.app.shortcut.com/api/v4/schemas/{schema-name}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/schemas/{schema-name}"

URL Parameters

Name	Description
schema-name String	Required. The name of the JSON schema.

Responses

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

Whoami

Get Whoami

Returns details about the currently-authenticated member and token authorization.

Definition

GET https://api.app.shortcut.com/api/v4/whoami

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/whoami"

Example Response

{
  "authorization": {
    "scopes": []
  },
  "default_workflow": {
    "entity_type": "workflow:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "default_workflow_state": {
    "entity_type": "workflow-state:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo",
    "workflow_name": "foo"
  },
  "entity_type": "whoami",
  "member": {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  },
  "workspace": {
    "app_url": "foo",
    "entity_type": "workspace:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "slug": "foo"
  }
}

Responses

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

Admin

List Workspace Tokens

List Workspace Tokens returns a paginated list of all API Tokens in the Workspace. Requires admin role.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/admin/tokens

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/admin/tokens"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "token",
    "id": "12345678-9012-3456-7890-123456789012",
    "last_used_at": "2016-12-31T12:30:00Z",
    "member": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "scopes": [],
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Delete Workspace Token

Delete Workspace Token disables an API Token in the Workspace. Requires admin role.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/admin/tokens/{token-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/admin/tokens/{token-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
token-public-id UUID	Required. The unique ID of the Token.

Responses

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

Branches

List Branches

List Branches returns a paginated list of all Branches in the Workspace that have either been associated with a Story, or used in a Pull Request that was associated with a Story.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/branches

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/branches"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "branch",
    "external_url": "foo",
    "id": 123,
    "name": "foo",
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_deleted, include_deleted)	Filter options (default: :exclude_deleted).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Get Branch

Get Branch returns information about a chosen Branch.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/branches/{branch-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/branches/{branch-public-id}"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "branch",
  "external_url": "foo",
  "id": 123,
  "name": "foo",
  "pull_requests": {
    "current_items": 123,
    "entities": [{
      "entity_type": "pull-request:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "repository": {
    "entity_type": "repository:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
branch-public-id Integer	Required. The ID of the Branch.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Branch Pull Requests

List Branch Pull Requests returns a paginated list of all Pull Requests associated with a Branch in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/branches/{branch-public-id}/pull-requests

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/branches/{branch-public-id}/pull-requests"

Example Response

[
  {
    "branch": {
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "closed": true,
    "created_at": "2016-12-31T12:30:00Z",
    "draft": true,
    "entity_type": "pull-request",
    "external_id": "foo",
    "external_url": "foo",
    "id": 123,
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "target_branch": {
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "title": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
branch-public-id Integer	Required. The ID of the Branch.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_closed, include_closed)	Filter options (default: :include_closed).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Branch Stories

List Branch Stories returns a paginated list of all Stories associated with a Branch in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/branches/{branch-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/branches/{branch-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
branch-public-id Integer	Required. The ID of the Branch.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

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

Name	Description
categories Array [CreateCategoryParams]	Required. Payloads for each Category to create.

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

Name	Description
categories Array [BulkUpdateCategoriesParams1]	Required. Payloads for each Category to update.

Name	Description
category_ids Array [Integer]	Required. Ids of the archived Categories to delete.

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

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

Commits

List Commits

List Commits returns a paginated list of all Commits in the Workspace that have been associated with Stories.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/commits

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/commits"

Example Response

[
  {
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "commit",
    "external_url": "foo",
    "hash": "foo",
    "id": 123,
    "message": "foo",
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Get Commit

Get Commit returns information about a chosen Commit.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/commits/{commit-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/commits/{commit-public-id}"

Example Response

{
  "author": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "commit",
  "external_url": "foo",
  "hash": "foo",
  "id": 123,
  "message": "foo",
  "repository": {
    "entity_type": "repository:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "timestamp": "2016-12-31T12:30:00Z",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
commit-public-id Integer	Required. The ID of the Commit.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Commit Stories

List Commit Stories returns a paginated list of all Stories associated with a Commit in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/commits/{commit-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/commits/{commit-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
commit-public-id Integer	Required. The ID of the Commit.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Custom-Fields

List Custom Fields

List Custom Fields returns a paginated list of all Custom Fields in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields"

Example Response

[
  {
    "canonical_name": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "enabled": true,
    "entity_type": "custom-field",
    "field_type": "foo",
    "fixed_position": true,
    "icon_set_identifier": "foo",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "position": 123,
    "story_types": ["bug"],
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "values": [{
      "color_key": "black",
      "enabled": true,
      "entity_type": "custom-field-value",
      "field": {
        "entity_type": "custom-field:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "id": "12345678-9012-3456-7890-123456789012",
      "position": 123,
      "value": "foo"
    }]
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Bulk Update Custom Fields

Bulk Update Custom Fields updates multiple Custom Fields, and returns a paginated list of the updated Custom Fields.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "custom_fields": [{ "after_id": "12345678-9012-3456-7890-123456789012", "before_id": "12345678-9012-3456-7890-123456789012", "description": "foo", "enabled": true, "icon_set_identifier": "foo", "id": "12345678-9012-3456-7890-123456789012", "name": "foo", "values": [{
    "color_key": "black",
    "enabled": true,
    "id": "12345678-9012-3456-7890-123456789012",
    "value": "foo"
  }], "values_add": [{
    "color_key": "black",
    "enabled": true,
    "id": "12345678-9012-3456-7890-123456789012",
    "value": "foo"
  }], "values_remove": ["12345678-9012-3456-7890-123456789012"] }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/bulk"

Example Response

[
  {
    "canonical_name": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "enabled": true,
    "entity_type": "custom-field",
    "field_type": "foo",
    "fixed_position": true,
    "icon_set_identifier": "foo",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "position": 123,
    "story_types": ["bug"],
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "values": [{
      "color_key": "black",
      "enabled": true,
      "entity_type": "custom-field-value",
      "field": {
        "entity_type": "custom-field:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "id": "12345678-9012-3456-7890-123456789012",
      "position": 123,
      "value": "foo"
    }]
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
custom_fields Array [BulkUpdateCustomFieldsParams1]	Required. Payloads for each Custom Field to update.

Responses

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

Bulk Delete Custom Fields

Bulk Delete Custom Fields removes multiple Custom Fields from the Workspace.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "custom_field_ids": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

Body Parameters

Name	Description
custom_field_ids Array [UUID]	Required. The unique IDs of the Custom Fields to delete.

Responses

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

Get Custom Field

Get Custom Field returns information about a chosen Custom Field.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/{custom-field-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/{custom-field-public-id}"

Example Response

{
  "canonical_name": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "enabled": true,
  "entity_type": "custom-field",
  "field_type": "foo",
  "fixed_position": true,
  "icon_set_identifier": "foo",
  "id": "12345678-9012-3456-7890-123456789012",
  "name": "foo",
  "position": 123,
  "story_types": ["bug"],
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "values": [{
    "color_key": "black",
    "enabled": true,
    "entity_type": "custom-field-value",
    "field": {
      "entity_type": "custom-field:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "id": "12345678-9012-3456-7890-123456789012",
    "position": 123,
    "value": "foo"
  }]
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
custom-field-public-id UUID	Required. The unique ID of the Custom Field.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Custom Field

Update Custom Field allows you to modify a Custom Field definition in your Shortcut Workspace.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/{custom-field-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $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": "foo", "name": "foo", "values": [{ "color_key": "black", "enabled": true, "id": "12345678-9012-3456-7890-123456789012", "value": "foo" }], "values_add": [{ "color_key": "black", "enabled": true, "id": "12345678-9012-3456-7890-123456789012", "value": "foo" }], "values_remove": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/{custom-field-public-id}"

Example Response

{
  "canonical_name": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "enabled": true,
  "entity_type": "custom-field",
  "field_type": "foo",
  "fixed_position": true,
  "icon_set_identifier": "foo",
  "id": "12345678-9012-3456-7890-123456789012",
  "name": "foo",
  "position": 123,
  "story_types": ["bug"],
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "values": [{
    "color_key": "black",
    "enabled": true,
    "entity_type": "custom-field-value",
    "field": {
      "entity_type": "custom-field:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "id": "12345678-9012-3456-7890-123456789012",
    "position": 123,
    "value": "foo"
  }]
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
custom-field-public-id UUID	Required. The unique ID of the Custom Field.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
after_id UUID	Move this Custom Field to after the field with this ID.
before_id UUID	Move this Custom Field to before the field with this ID.
description String (1024)	A description of the Custom Field.
enabled Boolean	Whether the Custom Field is enabled.
icon_set_identifier String (63)	An identifier for the icon set for this Custom Field.
name String (63)	The name of the Custom Field.
values Array [UpdateCustomFieldEnumValueParams]	The ordered list of enum values. Existing values not included will be deleted.
values_add Array [UpdateCustomFieldEnumValueParams]	Enum values to add to the Custom Field. Existing values are unchanged.
values_remove Array [UUID]	IDs of enum values to remove from the Custom Field.

Responses

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

Delete Custom Field

Delete Custom Field removes a Custom Field from the Workspace.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/{custom-field-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/{custom-field-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
custom-field-public-id UUID	Required. The unique ID of the Custom Field.

Responses

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

List Custom Field Stories

Returns a paginated list of all Stories that have a value set for the specified Custom Field.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/{custom-field-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/custom-fields/{custom-field-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
custom-field-public-id UUID	Required. The unique ID of the Custom Field.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Documents

List Docs

List Docs returns a paginated list of all accessible Docs in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/documents

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/documents"

Example Response

[
  {
    "archived": true,
    "content_html": "foo",
    "content_markdown": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "creator": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "entity_type": "doc",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": "12345678-9012-3456-7890-123456789012",
    "title": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Doc

Create Doc allows you to create a new Doc in the Workspace.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/documents

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "content": "foo", "content_format": "html", "description": "foo", "title": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/documents"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
content String	Required. The content of the new Doc.
content_format Enum (html, markdown)	Format of the content being sent. Defaults to ‘html’. If ‘markdown’, content will be converted to HTML for storage.
description String (1024)	An optional description for the Doc.
title String (256)	Required. The title of the new Doc.

Responses

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

Bulk Create Docs

Bulk Create Docs creates multiple Docs, and returns a paginated list of the created Docs.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/documents/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "documents": [{ "content": "foo", "content_format": "html", "description": "foo", "title": "foo" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/documents/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
documents Array [CreateDocParams]	Required. Payloads for each Doc to create.

Responses

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

Get Doc

Get Doc returns information about a chosen Doc. Pass content_format=markdown (default) or content_format=html to include content in the response.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/documents/{doc-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/documents/{doc-public-id}"

Example Response

{
  "archived": true,
  "content_html": "foo",
  "content_markdown": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "creator": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "entity_type": "doc",
  "followers": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": "12345678-9012-3456-7890-123456789012",
  "title": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
doc-public-id UUID	Required. The ID of the Doc.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Doc Followers

List Doc Followers returns a paginated list of all Members following a Doc in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/documents/{doc-public-id}/followers

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/documents/{doc-public-id}/followers"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
doc-public-id UUID	Required. The ID of the Doc.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Entity-Templates

List Entity Templates

List Entity Templates returns a paginated list of all Entity Templates in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates"

Example Response

[
  {
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "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_id": "12345678-9012-3456-7890-123456789012"
      }],
      "deadline": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "epic": {
        "app_url": "foo",
        "entity_type": "epic:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "estimate": 123,
      "external_links": [],
      "files": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "followers": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "iteration": {
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "labels": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "linked_files": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "name": "foo",
      "owners": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "project": {
        "app_url": "foo",
        "entity_type": "project:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "story_type": "foo",
      "sub_tasks": [{
        "name": "foo",
        "owners": [{
          "entity_type": "member:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        }],
        "position": 123,
        "workflow_state": {
          "entity_type": "workflow-state:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo",
          "workflow_name": "foo"
        }
      }],
      "tasks": [{
        "complete": true,
        "description": "foo",
        "owners": [{
          "entity_type": "member:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        }],
        "position": 123
      }],
      "team": {
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "workflow_state": {
        "entity_type": "workflow-state:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo",
        "workflow_name": "foo"
      }
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Entity Template

Create Entity Template creates a new Entity Template in your Shortcut Workspace.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "author_id": "12345678-9012-3456-7890-123456789012", "name": "foo", "story_contents": { "custom_fields": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "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, "label_ids": [123], "linked_file_ids": [123], "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "story_type": "bug", "sub_tasks": [{
    "name": "foo",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "workflow_state_id": 123
  }], "tasks": [{
    "complete": true,
    "description": "foo",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"]
  }], "workflow_state_id": 123 } }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
author_id UUID	The ID of the member creating this template.
name String (128)	Required. The name of the new entity template.
story_contents CreateEntityTemplateStoryContentsParams	Required. A map of story attributes this template populates.

Responses

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

Bulk Create Entity Templates

Bulk Create Entity Templates creates multiple Entity Templates, and returns a paginated list of the created Entity Templates.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "entity_templates": [{ "author_id": "12345678-9012-3456-7890-123456789012", "name": "foo", "story_contents": {
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "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,
    "label_ids": [123],
    "linked_file_ids": [123],
    "name": "foo",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "story_type": "bug",
    "sub_tasks": [{
      "name": "foo",
      "owner_ids": ["12345678-9012-3456-7890-123456789012"],
      "workflow_state_id": 123
    }],
    "tasks": [{
      "complete": true,
      "description": "foo",
      "owner_ids": ["12345678-9012-3456-7890-123456789012"]
    }],
    "workflow_state_id": 123
  } }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
entity_templates Array [CreateEntityTemplateParams]	Required. Payloads for each Entity Template to create.

Responses

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

Bulk Update Entity Templates

Bulk Update Entity Templates updates multiple Entity Templates, and returns a paginated list of the updated Entity Templates.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "entity_templates": [{ "id": "12345678-9012-3456-7890-123456789012", "name": "foo", "story_contents": {
    "custom_fields": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "custom_fields_add": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "custom_fields_remove": [{
      "field_id": "12345678-9012-3456-7890-123456789012",
      "value_id": "12345678-9012-3456-7890-123456789012"
    }],
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "epic_id": 123,
    "estimate": 123,
    "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,
    "label_ids": [123],
    "label_ids_add": [123],
    "label_ids_remove": [123],
    "linked_file_ids": [123],
    "linked_file_ids_add": [123],
    "linked_file_ids_remove": [123],
    "name": "foo",
    "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,
    "story_type": "bug",
    "sub_tasks": [{
      "name": "foo",
      "owner_ids": ["12345678-9012-3456-7890-123456789012"],
      "workflow_state_id": 123
    }],
    "tasks": [{
      "complete": true,
      "description": "foo",
      "owner_ids": ["12345678-9012-3456-7890-123456789012"]
    }],
    "workflow_state_id": 123
  } }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/bulk"

Example Response

[
  {
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "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_id": "12345678-9012-3456-7890-123456789012"
      }],
      "deadline": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "foo",
      "epic": {
        "app_url": "foo",
        "entity_type": "epic:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "estimate": 123,
      "external_links": [],
      "files": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "followers": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "iteration": {
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "labels": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "linked_files": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "name": "foo",
      "owners": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "project": {
        "app_url": "foo",
        "entity_type": "project:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "story_type": "foo",
      "sub_tasks": [{
        "name": "foo",
        "owners": [{
          "entity_type": "member:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        }],
        "position": 123,
        "workflow_state": {
          "entity_type": "workflow-state:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo",
          "workflow_name": "foo"
        }
      }],
      "tasks": [{
        "complete": true,
        "description": "foo",
        "owners": [{
          "entity_type": "member:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        }],
        "position": 123
      }],
      "team": {
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "workflow_state": {
        "entity_type": "workflow-state:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo",
        "workflow_name": "foo"
      }
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
entity_templates Array [BulkUpdateEntityTemplatesParams1]	Required. Payloads for each Entity Template to update.

Responses

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

Bulk Delete Entity Templates

Bulk Delete Entity Templates removes multiple Entity Templates from the Workspace.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "entity_template_ids": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

Body Parameters

Name	Description
entity_template_ids Array [UUID]	Required. UUIDs of the Entity Templates to delete.

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/v4/{workspace-slug}/entity-templates/{entity-template-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/{entity-template-public-id}"

Example Response

{
  "author": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "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_id": "12345678-9012-3456-7890-123456789012"
    }],
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_links": [],
    "files": [{
      "entity_type": "file:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "followers": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "iteration": {
      "app_url": "foo",
      "entity_type": "iteration:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "labels": [{
      "app_url": "foo",
      "entity_type": "label:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "linked_files": [{
      "entity_type": "linked-file:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "name": "foo",
    "owners": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "foo",
    "sub_tasks": [{
      "name": "foo",
      "owners": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "position": 123,
      "workflow_state": {
        "entity_type": "workflow-state:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo",
        "workflow_name": "foo"
      }
    }],
    "tasks": [{
      "complete": true,
      "description": "foo",
      "owners": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "position": 123
    }],
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
entity-template-public-id UUID	Required. The unique ID of the entity template.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Entity Template

Update Entity Template updates an existing Entity Template in your Shortcut Workspace.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/{entity-template-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "name": "foo", "story_contents": { "custom_fields": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }], "custom_fields_add": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }], "custom_fields_remove": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }], "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_id": 123, "estimate": 123, "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, "label_ids": [123], "label_ids_add": [123], "label_ids_remove": [123], "linked_file_ids": [123], "linked_file_ids_add": [123], "linked_file_ids_remove": [123], "name": "foo", "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, "story_type": "bug", "sub_tasks": [{
    "name": "foo",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"],
    "workflow_state_id": 123
  }], "tasks": [{
    "complete": true,
    "description": "foo",
    "owner_ids": ["12345678-9012-3456-7890-123456789012"]
  }], "workflow_state_id": 123 } }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/{entity-template-public-id}"

Example Response

{
  "author": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "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_id": "12345678-9012-3456-7890-123456789012"
    }],
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "foo",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_links": [],
    "files": [{
      "entity_type": "file:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "followers": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "iteration": {
      "app_url": "foo",
      "entity_type": "iteration:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "labels": [{
      "app_url": "foo",
      "entity_type": "label:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "linked_files": [{
      "entity_type": "linked-file:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "name": "foo",
    "owners": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "foo",
    "sub_tasks": [{
      "name": "foo",
      "owners": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "position": 123,
      "workflow_state": {
        "entity_type": "workflow-state:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo",
        "workflow_name": "foo"
      }
    }],
    "tasks": [{
      "complete": true,
      "description": "foo",
      "owners": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "position": 123
    }],
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
entity-template-public-id UUID	Required. The unique ID of the entity template.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
name String (128)	The updated template name.
story_contents UpdateEntityTemplateStoryContentsParams	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

Delete Entity Template removes an Entity Template from the Workspace.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/{entity-template-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/entity-templates/{entity-template-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
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 configuration for the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epic-workflow

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epic-workflow"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "default_epic_state": {
    "entity_type": "epic-state:slim",
    "id": 123,
    "name": "foo",
    "type": "foo"
  },
  "entity_type": "epic-workflow",
  "epic_states": {
    "current_items": 123,
    "entities": [{
      "color": "foo",
      "created_at": "2016-12-31T12:30:00Z",
      "description": "foo",
      "entity_type": "epic-state",
      "id": 123,
      "name": "foo",
      "position": 123,
      "type": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Workflow States

Returns a paginated list of all Epic States in the Workspace’s Epic Workflow.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epic-workflow/states

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epic-workflow/states"

Example Response

[
  {
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "epic-state",
    "id": 123,
    "name": "foo",
    "position": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (position)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Epics

List Epics

List Epics returns a paginated list of all Epics in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "threaded-comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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",
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "epic",
    "epic_state": {
      "entity_type": "epic-state:slim",
      "id": 123,
      "name": "foo",
      "type": "foo"
    },
    "external_id": "foo",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "healths": {
      "current_items": 123,
      "entities": [{
        "created_at": "2016-12-31T12:30:00Z",
        "entity_type": "health:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "status": "foo",
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "objectives": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "objective:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "planned_start_date": "2016-12-31T12:30:00Z",
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Epic

Create Epic is used to create a new Epic in your Shortcut Workspace.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/epics

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "completed_at_override": "2016-12-31T12:30:00Z", "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_state_id": 123, "external_id": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "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", "team_ids": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
completed_at_override Date	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)	An external ID for the Epic.
follower_ids Array [UUID]	An array of UUIDs for Members to add as Followers.
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 Members to add as Owners.
planned_start_date Date or null	The Epic’s planned start date.
requested_by_id UUID	The UUID of the Member that requested the Epic.
started_at_override Date	A manual override for the time/date the Epic was started.
team_ids Array [UUID]	An array of UUIDs for Teams to associate with the Epic.

Responses

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

Bulk Create Epics

Bulk Create Epics creates multiple Epics, and returns a paginated list of the created Epics.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "epics": [{ "completed_at_override": "2016-12-31T12:30:00Z", "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_state_id": 123, "external_id": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "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", "team_ids": ["12345678-9012-3456-7890-123456789012"] }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
epics Array [CreateEpicParams]	Required. Payloads for each Epic to create.

Responses

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

Bulk Update Epics

Bulk Update Epics updates multiple Epics, and returns a paginated list of the updated Epics.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "epics": [{ "archived": true, "completed_at_override": "2016-12-31T12:30:00Z", "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_state_id": 123, "external_id": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "id": 123, "name": "foo", "objective_ids": [123], "objective_ids_add": [123], "objective_ids_remove": [123], "owner_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["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", "team_ids": ["12345678-9012-3456-7890-123456789012"], "team_ids_add": ["12345678-9012-3456-7890-123456789012"], "team_ids_remove": ["12345678-9012-3456-7890-123456789012"] }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/bulk"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "threaded-comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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",
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "epic",
    "epic_state": {
      "entity_type": "epic-state:slim",
      "id": 123,
      "name": "foo",
      "type": "foo"
    },
    "external_id": "foo",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "healths": {
      "current_items": 123,
      "entities": [{
        "created_at": "2016-12-31T12:30:00Z",
        "entity_type": "health:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "status": "foo",
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "objectives": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "objective:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "planned_start_date": "2016-12-31T12:30:00Z",
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
epics Array [BulkUpdateEpicsParams1]	Required. Payloads for each Epic to update.

Responses

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

Bulk Delete Epics

Bulk Delete Epics deletes multiple Epics. The Epics must be archived unless force is set.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "epic_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
force Boolean	Forces deletion of the Epics, overriding the check that they are archived.

Body Parameters

Name	Description
epic_ids Array [Integer]	Required. Ids of the Epics to delete.

Responses

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

Get Epic

Get Epic returns information about a chosen Epic.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "comments": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "deleted": true,
      "entity_type": "threaded-comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 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",
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "epic",
  "epic_state": {
    "entity_type": "epic-state:slim",
    "id": 123,
    "name": "foo",
    "type": "foo"
  },
  "external_id": "foo",
  "followers": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "healths": {
    "current_items": 123,
    "entities": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "health:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "status": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "labels": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "label:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "name": "foo",
  "objectives": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "objective:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "owners": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "planned_start_date": "2016-12-31T12:30:00Z",
  "requester": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Epic

Update Epic is used to modify an Epic in your Shortcut Workspace.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "completed_at_override": "2016-12-31T12:30:00Z", "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_state_id": 123, "external_id": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "objective_ids": [123], "objective_ids_add": [123], "objective_ids_remove": [123], "owner_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["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", "team_ids": ["12345678-9012-3456-7890-123456789012"], "team_ids_add": ["12345678-9012-3456-7890-123456789012"], "team_ids_remove": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "comments": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "deleted": true,
      "entity_type": "threaded-comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 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",
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "epic",
  "epic_state": {
    "entity_type": "epic-state:slim",
    "id": 123,
    "name": "foo",
    "type": "foo"
  },
  "external_id": "foo",
  "followers": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "healths": {
    "current_items": 123,
    "entities": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "health:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "status": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "labels": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "label:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "name": "foo",
  "objectives": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "objective:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "owners": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "planned_start_date": "2016-12-31T12:30:00Z",
  "requester": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
archived Boolean	Whether the Epic is archived.
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)	An external ID for the Epic.
follower_ids Array [UUID]	An array of UUIDs for Members to set as Followers. This will replace the current Followers on the Epic. Sending an empty array will delete all existing Followers.
follower_ids_add Array [UUID]	An array of UUIDs for Members to add as Followers. These will be added to the current Followers on the Epic.
follower_ids_remove Array [UUID]	An array of UUIDs for Members to remove as Followers. These will be removed from the current Followers on the Epic.
name String (256)	The Epic’s name.
objective_ids Array [Integer]	An array of IDs for Objectives to which this Epic is related. This will replace the current Objectives on the Epic. Sending an empty array will remove all existing Objectives.
objective_ids_add Array [Integer]	An array of IDs for Objectives to add to the Epic. These will be added to the current Objectives on the Epic.
objective_ids_remove Array [Integer]	An array of IDs for Objectives to remove from the Epic. These will be removed from the current Objectives on the Epic.
owner_ids Array [UUID]	An array of UUIDs for Members to set as Owners. This will replace the current Owners on the Epic. Sending an empty array will delete all existing Owners.
owner_ids_add Array [UUID]	An array of UUIDs for Members to add as Owners. These will be added to the current Owners on the Epic.
owner_ids_remove Array [UUID]	An array of UUIDs for Members to remove as Owners. These will be removed from the current Owners on the Epic.
planned_start_date Date or null	The Epic’s planned start date.
requested_by_id UUID	The UUID of the Member that requested the Epic.
started_at_override Date or null	A manual override for the time/date the Epic was started.
team_ids Array [UUID]	An array of UUIDs for Teams to associate with the Epic. This will replace the current Teams on the Epic. Sending an empty array will remove all existing Teams.
team_ids_add Array [UUID]	An array of UUIDs for Teams to add to the Epic. These will be added to the current Teams on the Epic.
team_ids_remove Array [UUID]	An array of UUIDs for Teams to remove from the Epic. These will be removed from the current Teams on the Epic.

Responses

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

Delete Epic

Delete Epic removes an Epic from the Workspace. The Epic must be archived unless force is set.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
force Boolean	Forces deletion of the Epic, overriding the check that it is archived.

Responses

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

List Epic Comments

List Epic Comments returns a paginated list of all Comments for an Epic in the Workspace. Note that deleted comments will also be returned, but will have minimal information. The deleted comments are included as they may be parents to other comments.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments"

Example Response

[
  {
    "app_url": "foo",
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "threaded-comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "threaded-comment",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_comment": {
      "app_url": "foo",
      "deleted": true,
      "entity_type": "threaded-comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    },
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
ids String	A comma-separated list of ids. If included, only those entities will be considered for listing.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

Create Epic Comment

Create Epic Comment is used to add a new Comment to an Epic. To reply to an existing Comment, provide a parent_comment_id.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "author_id": "12345678-9012-3456-7890-123456789012", "external_id": "foo", "parent_comment_id": 123, "text": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
author_id UUID	The Member ID of the Comment’s author. Defaults to the user identified by the API token. Requires the admin role to set.
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.
parent_comment_id Integer	The ID of the Comment to reply to. When provided, creates a threaded reply rather than a top-level Comment.
text String (100000)	Required. The comment text.

Responses

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

Bulk Create Epic Comments

Bulk Create Epic Comments creates multiple Comments on an Epic, and returns a paginated list of the created Comments.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "comments": [{ "author_id": "12345678-9012-3456-7890-123456789012", "external_id": "foo", "parent_comment_id": 123, "text": "foo" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Body Parameters

Name	Description
comments Array [CreateEpicCommentParams]	Required. Payloads for each Comment to create.

Responses

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

Bulk Update Epic Comments

Bulk Update Epic Comments updates multiple Comments on an Epic, and returns a paginated list of the updated Comments.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "comments": [{ "id": 123, "text": "foo" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/bulk"

Example Response

[
  {
    "app_url": "foo",
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "threaded-comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "threaded-comment",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_comment": {
      "app_url": "foo",
      "deleted": true,
      "entity_type": "threaded-comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    },
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Body Parameters

Name	Description
comments Array [BulkUpdateEpicCommentsParams1]	Required. Payloads for each Comment to update.

Responses

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

Bulk Delete Epic Comments

Bulk Delete Epic Comments deletes multiple Comments from an Epic.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "comment_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

Body Parameters

Name	Description
comment_ids Array [Integer]	Required. Ids of the Comments to delete.

Responses

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

Get Epic Comment

Get Epic Comment returns information about a chosen Epic Comment.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}"

Example Response

{
  "app_url": "foo",
  "author": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "comments": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "deleted": true,
      "entity_type": "threaded-comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "threaded-comment",
  "epic": {
    "app_url": "foo",
    "entity_type": "epic:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "external_id": "foo",
  "id": 123,
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "parent_comment": {
    "app_url": "foo",
    "deleted": true,
    "entity_type": "threaded-comment:slim",
    "id": 123,
    "text": "foo",
    "uri": "foo"
  },
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Epic Comment

Update Epic Comment is used to modify an existing Epic Comment.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "text": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}"

Example Response

{
  "app_url": "foo",
  "author": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "comments": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "deleted": true,
      "entity_type": "threaded-comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "threaded-comment",
  "epic": {
    "app_url": "foo",
    "entity_type": "epic:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "external_id": "foo",
  "id": 123,
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "parent_comment": {
    "app_url": "foo",
    "deleted": true,
    "entity_type": "threaded-comment:slim",
    "id": 123,
    "text": "foo",
    "uri": "foo"
  },
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
text String (100000)	The comment text.

Responses

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

Delete Epic Comment

Delete a Comment from an Epic.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Comment Comments

List Epic Comment Comments returns a paginated list of all threaded reply Comments for an Epic Comment in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}/comments

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}/comments"

Example Response

[
  {
    "app_url": "foo",
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "threaded-comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "threaded-comment",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_comment": {
      "app_url": "foo",
      "deleted": true,
      "entity_type": "threaded-comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    },
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

List Epic Comment Mentioned Members

List Epic Comment Mentioned Members returns a paginated list of all Members mentioned in an Epic Comment in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}/mentioned-members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}/mentioned-members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (name)	Order the results by this property and direction.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

List Epic Comment Mentioned Teams

List Epic Comment Mentioned Teams returns a paginated list of all Teams mentioned in an Epic Comment in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}/mentioned-teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/comments/{comment-public-id}/mentioned-teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (name, updated_at)	Order the results by this property and direction.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

List Epic Healths

Returns a paginated list of Health updates for the specified Epic.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/epic-healths

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/epic-healths"

Example Response

[
  {
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "health",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "id": "12345678-9012-3456-7890-123456789012",
    "objective": {
      "app_url": "foo",
      "entity_type": "objective:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "status": "At Risk",
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Epic Health

Creates a new Health update for the specified Epic.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/epic-healths

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "status": "At Risk", "text": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/epic-healths"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
status Enum (At Risk, No Health, Off Track, On Track)	Required. The health status.
text String	The text body of the Health update.

Responses

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

Get Epic Health

Returns a Health for the specified Epic.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/epic-healths/{epic-health-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/epic-healths/{epic-health-public-id}"

Example Response

{
  "author": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "health",
  "epic": {
    "app_url": "foo",
    "entity_type": "epic:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "id": "12345678-9012-3456-7890-123456789012",
  "objective": {
    "app_url": "foo",
    "entity_type": "objective:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "status": "At Risk",
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.
epic-health-public-id UUID	Required. The unique ID of the Health.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Followers

List Epic Followers returns a paginated list of all Members who are following an Epic in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/followers

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/followers"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Labels

List Epic Labels returns a paginated list of all Labels for an Epic in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/labels

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/labels"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "label",
    "epics": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "epic:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Mentioned Members

List Epic Mentioned Members returns a paginated list of all Members mentioned in an Epic in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/mentioned-members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/mentioned-members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Mentioned Teams

List Epic Mentioned Teams returns a paginated list of all Teams mentioned in an Epic in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/mentioned-teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/mentioned-teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Objectives

List Epic Objectives returns a paginated list of all Objectives associated with an Epic in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/objectives

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/objectives"

Example Response

[
  {
    "app_url": "foo",
    "entity_type": "objective:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Owners

List Epic Owners returns a paginated list of all Members who own an Epic in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/owners

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/owners"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Stories

List Epic Stories returns a paginated list of all Stories associated with an Epic in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Epic Teams

List Epic Teams returns a paginated list of all Teams associated with an Epic in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/{epic-public-id}/teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
epic-public-id Integer	Required. The ID of the Epic.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Files

List Files

List Files returns a paginated list of all Files in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/files

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/files"

Example Response

[
  {
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "file",
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "size": 123,
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "uri": "foo",
    "url": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Upload Files

Upload Files uploads one or more 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.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/files

Example Request

curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -F 'story_id=123' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/files"

Form Parameters

Name	Description
story_id Integer	The ID of the Story to attach the files to.

Responses

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

Bulk Delete Files

Bulk Delete Files deletes multiple Files from the Workspace.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/files/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "file_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/files/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

Body Parameters

Name	Description
file_ids Array [Integer]	Required. Ids of the Files to delete.

Responses

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

Get File

Get File returns information about the chosen File.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/files/{file-public-id}"

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "file",
  "external_id": "foo",
  "id": 123,
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "name": "foo",
  "size": 123,
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "thumbnail_url": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "uri": "foo",
  "url": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
file-public-id Integer	Required. The ID of the File.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Delete File

Delete File removes a previously uploaded File from the Workspace.

Definition

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

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/files/{file-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
file-public-id Integer	Required. The ID of the File.

Responses

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

List File Mentioned Members

List File Mentioned Members returns a paginated list of all Members mentioned in a File in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/files/{file-public-id}/mentioned-members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/files/{file-public-id}/mentioned-members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
file-public-id Integer	Required. The ID of the File.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List File Mentioned Teams

List File Mentioned Teams returns a paginated list of all Teams mentioned in a File in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/files/{file-public-id}/mentioned-teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/files/{file-public-id}/mentioned-teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
file-public-id Integer	Required. The ID of the File.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List File Stories

List File Stories returns a paginated list of all Stories associated with a File in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/files/{file-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/files/{file-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
file-public-id Integer	Required. The ID of the File.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Iterations

List Iterations

List Iterations returns a paginated list of all Iterations in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations"

Example Response

[
  {
    "app_url": "foo",
    "associated_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "end_date": "foo",
    "entity_type": "iteration",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "start_date": "foo",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (start_date, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Iteration

Create Iteration is used to create a new Iteration in your Shortcut Workspace.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "description": "foo", "end_date": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "start_date": "foo", "team_ids": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
description String (100000)	The description of the Iteration.
end_date String	Required. The date this Iteration ends (ISO 8601 date format, e.g. ‘2024-01-15’).
follower_ids Array [UUID]	An array of UUIDs for any Members you want to add as Followers.
name String (256)	Required. The name of this Iteration.
start_date String	Required. The date this Iteration begins (ISO 8601 date format, e.g. ‘2024-01-01’).
team_ids Array [UUID]	An array of UUIDs for any Teams you want to associate with the Iteration.

Responses

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

Bulk Create Iterations

Bulk Create Iterations creates multiple Iterations, and returns a paginated list of the created Iterations.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "iterations": [{ "description": "foo", "end_date": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "start_date": "foo", "team_ids": ["12345678-9012-3456-7890-123456789012"] }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (start_date, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
iterations Array [CreateIterationParams]	Required. Payloads for each Iteration to create.

Responses

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

Bulk Update Iterations

Bulk Update Iterations updates multiple Iterations, and returns a paginated list of the updated Iterations.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "iterations": [{ "description": "foo", "end_date": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "id": 123, "name": "foo", "start_date": "foo", "team_ids": ["12345678-9012-3456-7890-123456789012"], "team_ids_add": ["12345678-9012-3456-7890-123456789012"], "team_ids_remove": ["12345678-9012-3456-7890-123456789012"] }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/bulk"

Example Response

[
  {
    "app_url": "foo",
    "associated_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "end_date": "foo",
    "entity_type": "iteration",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "start_date": "foo",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (start_date, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
iterations Array [BulkUpdateIterationsParams1]	Required. Payloads for each Iteration to update.

Responses

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

Bulk Delete Iterations

Bulk Delete Iterations deletes multiple Iterations.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "iteration_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

Body Parameters

Name	Description
iteration_ids Array [Integer]	Required. Ids of the Iterations to delete.

Responses

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

Get Current Iterations

Returns all currently started iterations for the authenticated user based on their team memberships. The ‘current’ iterations are determined by finding started iterations associated with teams the user belongs to. If multiple iterations match, all are returned sorted by start date (ascending), then end date (ascending), then ID (ascending).

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/current

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/current"

Example Response

[
  {
    "app_url": "foo",
    "associated_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "end_date": "foo",
    "entity_type": "iteration",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "start_date": "foo",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (start_date, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Get Iteration

Get Iteration returns information about a chosen Iteration.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}"

Example Response

{
  "app_url": "foo",
  "associated_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "end_date": "foo",
  "entity_type": "iteration",
  "followers": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "labels": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "label:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "name": "foo",
  "start_date": "foo",
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
iteration-public-id Integer	Required. The unique ID of the Iteration.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Iteration

Update Iteration is used to modify an Iteration in your Shortcut Workspace.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "description": "foo", "end_date": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "start_date": "foo", "team_ids": ["12345678-9012-3456-7890-123456789012"], "team_ids_add": ["12345678-9012-3456-7890-123456789012"], "team_ids_remove": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}"

Example Response

{
  "app_url": "foo",
  "associated_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "end_date": "foo",
  "entity_type": "iteration",
  "followers": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "labels": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "label:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "name": "foo",
  "start_date": "foo",
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
iteration-public-id Integer	Required. The unique ID of the Iteration.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
description String (100000)	The description of the Iteration.
end_date String	The date this Iteration ends (ISO 8601 date format, e.g. ‘2024-01-15’).
follower_ids Array [UUID]	An array of UUIDs for any Members you want to set as Followers, replacing existing Followers.
follower_ids_add Array [UUID]	An array of UUIDs for any Members you want to add as Followers.
follower_ids_remove Array [UUID]	An array of UUIDs for any Members you want to remove as Followers.
name String (256)	The name of this Iteration.
start_date String	The date this Iteration begins (ISO 8601 date format, e.g. ‘2024-01-01’).
team_ids Array [UUID]	An array of UUIDs for any Teams you want to set on the Iteration, replacing existing Teams.
team_ids_add Array [UUID]	An array of UUIDs for any Teams you want to add to the Iteration.
team_ids_remove Array [UUID]	An array of UUIDs for any Teams you want to remove from the Iteration.

Responses

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

Delete Iteration

Delete Iteration removes an Iteration from the Workspace.

Definition

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

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
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 Associated Teams

List Iteration Associated Teams returns a paginated list of all Teams that own Stories in an Iteration but are not directly associated with the Iteration.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/associated-teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/associated-teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
iteration-public-id Integer	Required. The unique ID of the Iteration.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Iteration Followers

List Iteration Followers returns a paginated list of all Members who are following an Iteration in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/followers

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/followers"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
iteration-public-id Integer	Required. The unique ID of the Iteration.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Iteration Labels

List Iteration Labels returns a paginated list of all Labels for an Iteration in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/labels

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/labels"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "label",
    "epics": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "epic:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
iteration-public-id Integer	Required. The unique ID of the Iteration.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Iteration Mentioned Members

List Iteration Mentioned Members returns a paginated list of all Members mentioned in an Iteration in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/mentioned-members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/mentioned-members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
iteration-public-id Integer	Required. The unique ID of the Iteration.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Iteration Mentioned Teams

List Iteration Mentioned Teams returns a paginated list of all Teams mentioned in an Iteration in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/mentioned-teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/mentioned-teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
iteration-public-id Integer	Required. The unique ID of the Iteration.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Iteration Stories

List Iteration Stories returns a paginated list of all Stories in an Iteration in the Workspace.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
iteration-public-id Integer	Required. The unique ID of the Iteration.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Iteration Teams

List Iteration Teams returns a paginated list of all Teams directly associated with an Iteration in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/{iteration-public-id}/teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
iteration-public-id Integer	Required. The unique ID of the Iteration.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Key-Results

List Key Results

Returns a paginated list of all Key Results in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/key-results

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/key-results"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "current_observed_value": {
      "boolean_value": true,
      "created_at": "2016-12-31T12:30:00Z",
      "creator": {
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "numeric_value": "foo"
    },
    "current_target_value": {
      "boolean_value": true,
      "created_at": "2016-12-31T12:30:00Z",
      "creator": {
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "numeric_value": "foo"
    },
    "entity_type": "key-result",
    "id": "12345678-9012-3456-7890-123456789012",
    "initial_observed_value": {
      "boolean_value": true,
      "created_at": "2016-12-31T12:30:00Z",
      "creator": {
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "numeric_value": "foo"
    },
    "name": "foo",
    "objective": {
      "app_url": "foo",
      "entity_type": "objective:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "progress": 123,
    "type": "boolean",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Get Key Result

Returns the specified Key Result.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/key-results/{key-result-public-id}"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "current_observed_value": {
    "boolean_value": true,
    "created_at": "2016-12-31T12:30:00Z",
    "creator": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "numeric_value": "foo"
  },
  "current_target_value": {
    "boolean_value": true,
    "created_at": "2016-12-31T12:30:00Z",
    "creator": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "numeric_value": "foo"
  },
  "entity_type": "key-result",
  "id": "12345678-9012-3456-7890-123456789012",
  "initial_observed_value": {
    "boolean_value": true,
    "created_at": "2016-12-31T12:30:00Z",
    "creator": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "numeric_value": "foo"
  },
  "name": "foo",
  "objective": {
    "app_url": "foo",
    "entity_type": "objective:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "progress": 123,
  "type": "boolean",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
key-result-public-id UUID	Required. The unique ID of the Key Result.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Key Result

Updates the specified Key Result.

Definition

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

Example Request

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

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "current_observed_value": {
    "boolean_value": true,
    "created_at": "2016-12-31T12:30:00Z",
    "creator": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "numeric_value": "foo"
  },
  "current_target_value": {
    "boolean_value": true,
    "created_at": "2016-12-31T12:30:00Z",
    "creator": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "numeric_value": "foo"
  },
  "entity_type": "key-result",
  "id": "12345678-9012-3456-7890-123456789012",
  "initial_observed_value": {
    "boolean_value": true,
    "created_at": "2016-12-31T12:30:00Z",
    "creator": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "numeric_value": "foo"
  },
  "name": "foo",
  "objective": {
    "app_url": "foo",
    "entity_type": "objective:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "progress": 123,
  "type": "boolean",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
key-result-public-id UUID	Required. The unique ID of the Key Result.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
initial_observed_value UpdateKeyResultValueParams	The starting value of the Key Result.
name String (1024)	The new name of the Key Result.
observed_value UpdateKeyResultValueParams	The starting value of the Key Result.
target_value UpdateKeyResultValueParams	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 paginated list of all Labels in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/labels

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "label",
    "epics": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "epic:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will 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/v4/{workspace-slug}/labels

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "color": "#6515dd", "description": "foo", "external_id": "foo", "name": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

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

Bulk Create Labels

Bulk Create Labels creates multiple Labels, and returns a paginated list of the created Labels.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "labels": [{ "color": "#6515dd", "description": "foo", "external_id": "foo", "name": "foo" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
labels Array [CreateLabelParams]	Required. Payloads for each Label to create.

Responses

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

Bulk Update Labels

Bulk Update Labels updates multiple Labels, and returns a paginated list of the updated Labels.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "labels": [{ "archived": true, "color": "#6515dd", "description": "foo", "id": 123, "name": "foo" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/bulk"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "label",
    "epics": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "epic:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
labels Array [BulkUpdateLabelsParams1]	Required. Payloads for each Label to update.

Responses

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

Bulk Delete Labels

Bulk Delete Labels deletes multiple Labels.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "label_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

Body Parameters

Name	Description
label_ids Array [Integer]	Required. Ids of the Labels to delete.

Responses

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

Get Label

Get Label returns information about a chosen Label.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/{label-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "label",
  "epics": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
label-public-id Integer	Required. The ID of the Label.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Label

Update Label allows you to modify a Label in your Shortcut Workspace.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/{label-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "color": "#6515dd", "description": "foo", "name": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/{label-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "label",
  "epics": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "external_id": "foo",
  "id": 123,
  "name": "foo",
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
label-public-id Integer	Required. The ID of the Label.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

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 description of the Label.
name String (128)	The name of the Label.

Responses

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

Delete Label

Delete Label removes a Label from the Workspace.

Definition

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

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/{label-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
label-public-id Integer	Required. The ID of the Label.

Responses

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

List Label Epics

List Label Epics returns a paginated list of all Epics that have a given Label.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/{label-public-id}/epics"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "threaded-comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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",
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "epic",
    "epic_state": {
      "entity_type": "epic-state:slim",
      "id": 123,
      "name": "foo",
      "type": "foo"
    },
    "external_id": "foo",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "healths": {
      "current_items": 123,
      "entities": [{
        "created_at": "2016-12-31T12:30:00Z",
        "entity_type": "health:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "status": "foo",
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "objectives": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "objective:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "planned_start_date": "2016-12-31T12:30:00Z",
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
label-public-id Integer	Required. The ID of the Label.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Label Stories

List Label Stories returns a paginated list of all Stories that have a given Label.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/labels/{label-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
label-public-id Integer	Required. The ID of the Label.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Linked-Files

List Linked Files

List Linked Files returns a paginated list of all Linked Files in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files"

Example Response

[
  {
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "linked-file",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "size": 123,
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "uri": "foo",
    "url": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Linked File

Create Linked File is used to add a new Linked File to your Shortcut Workspace.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "content_type": "foo", "description": "foo", "name": "foo", "size": 123, "thumbnail_url": "foo", "type": "foo", "url": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
content_type String (128)	The content type of the Linked File.
description String (512)	The description of the Linked File.
name String (256)	Required. The name of the Linked File.
size Integer	The size of the Linked File.
thumbnail_url String (2048)	The URL of the thumbnail.
type String (63)	Required. The integration type (e.g. google, dropbox, box, onedrive, url).
url String (2048)	Required. The URL of the Linked File.

Responses

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

Bulk Create Linked Files

Bulk Create Linked Files creates multiple Linked Files, and returns a paginated list of the created Linked Files.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "linked_files": [{ "content_type": "foo", "description": "foo", "name": "foo", "size": 123, "thumbnail_url": "foo", "type": "foo", "url": "foo" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
linked_files Array [CreateLinkedFileParams]	Required. Payloads for each Linked File to create.

Responses

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

Bulk Update Linked Files

Bulk Update Linked Files updates multiple Linked Files, and returns a paginated list of the updated Linked Files.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "linked_files": [{ "description": "foo", "id": 123, "name": "foo", "thumbnail_url": "foo", "type": "foo", "url": "foo" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/bulk"

Example Response

[
  {
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "linked-file",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "size": 123,
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "uri": "foo",
    "url": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
linked_files Array [BulkUpdateLinkedFilesParams1]	Required. Payloads for each Linked File to update.

Responses

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

Bulk Delete Linked Files

Bulk Delete Linked Files deletes multiple Linked Files.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "linked_file_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

Body Parameters

Name	Description
linked_file_ids Array [Integer]	Required. Ids of the Linked Files to delete.

Responses

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

Get Linked File

Get Linked File returns information about the chosen Linked File.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}"

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "linked-file",
  "id": 123,
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "name": "foo",
  "size": 123,
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "thumbnail_url": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "uri": "foo",
  "url": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
linked-file-public-id Integer	Required. The ID of the Linked File.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Linked File

Update Linked File is used to update an existing Linked File in your Shortcut Workspace.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "description": "foo", "name": "foo", "thumbnail_url": "foo", "type": "foo", "url": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}"

Example Response

{
  "content_type": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "linked-file",
  "id": 123,
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "name": "foo",
  "size": 123,
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "thumbnail_url": "foo",
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uploader": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "uri": "foo",
  "url": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
linked-file-public-id Integer	Required. The ID of the Linked File.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
description String (512)	The description of the Linked File.
name String (256)	The name of the Linked File.
thumbnail_url String (2048)	The URL of the thumbnail.
type String (63)	The integration type (e.g. google, dropbox, box, onedrive, url).
url String (2048)	The URL of the Linked File.

Responses

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

Delete Linked File

Delete Linked File removes a Linked File from the Workspace.

Definition

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

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
linked-file-public-id Integer	Required. The ID of the Linked File.

Responses

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

List Linked File Mentioned Members

List Linked File Mentioned Members returns a paginated list of all Members mentioned in a Linked File in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}/mentioned-members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}/mentioned-members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
linked-file-public-id Integer	Required. The ID of the Linked File.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Linked File Mentioned Teams

List Linked File Mentioned Teams returns a paginated list of all Teams mentioned in a Linked File in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}/mentioned-teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}/mentioned-teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
linked-file-public-id Integer	Required. The ID of the Linked File.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Linked File Stories

List Linked File Stories returns a paginated list of all Stories associated with a Linked File in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/linked-files/{linked-file-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
linked-file-public-id Integer	Required. The ID of the Linked File.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Members

List Members

List Members returns a paginated list of all Members in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Bulk Update Members

Bulk Update Members updates multiple Members and returns a paginated list of the updated Members.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/members/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "members": [{ "disabled": true, "id": "12345678-9012-3456-7890-123456789012", "role": "admin" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/members/bulk"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
members Array [BulkUpdateMembersParams1]	Required. Payloads for each Member to update.

Responses

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

Get Member

Get Member returns information about a Member of the Workspace.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/members/{member-public-id}"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "disabled": true,
  "email_address": "foo",
  "entity_type": "member",
  "id": "12345678-9012-3456-7890-123456789012",
  "mention_name": "foo",
  "name": "foo",
  "role": "foo",
  "teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
member-public-id UUID	Required. The unique ID of the Member.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Member

Update Member modifies a Member’s role or disabled status in the Workspace.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/members/{member-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "disabled": true, "role": "admin" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/members/{member-public-id}"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "disabled": true,
  "email_address": "foo",
  "entity_type": "member",
  "id": "12345678-9012-3456-7890-123456789012",
  "mention_name": "foo",
  "name": "foo",
  "role": "foo",
  "teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
member-public-id UUID	Required. The unique ID of the Member.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
disabled Boolean	Set to true to disable the Member, false to re-enable them.
role Enum (admin, member, observer)	The new role to assign to the Member. One of “admin”, “member”, or “observer”.

Responses

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

List Member Stories

Returns a paginated list of all Stories owned by the specified Member.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/members/{member-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/members/{member-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
member-public-id UUID	Required. The unique ID of the Member.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Member Teams

Returns a paginated list of all Teams the Member belongs to.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/members/{member-public-id}/teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/members/{member-public-id}/teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
member-public-id UUID	Required. The unique ID of the Member.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Objectives

List Objectives

List Objectives returns a paginated list of all Objectives in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "categories": [{
      "entity_type": "category:slim",
      "id": 123,
      "name": "foo",
      "uri": "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",
    "description": "foo",
    "entity_type": "objective",
    "epics": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "epic:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "healths": {
      "current_items": 123,
      "entities": [{
        "created_at": "2016-12-31T12:30:00Z",
        "entity_type": "health:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "status": "foo",
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "key_results": {
      "current_items": 123,
      "entities": [{
        "entity_type": "key-result:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "done",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Objective

Create Objective is used to create a new Objective in your Shortcut Workspace.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "category_ids": [123], "completed_at_override": "2016-12-31T12:30:00Z", "description": "foo", "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "started_at_override": "2016-12-31T12:30:00Z", "state": "done", "team_ids": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
category_ids Array [Integer]	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.
owner_ids Array [UUID]	An array of UUIDs for Members to add as Owners.
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 of the Objective.
team_ids Array [UUID]	An array of UUIDs for Teams to associate with the Objective.

Responses

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

Bulk Create Objectives

Bulk Create Objectives creates multiple Objectives, and returns a paginated list of the created Objectives.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "objectives": [{ "category_ids": [123], "completed_at_override": "2016-12-31T12:30:00Z", "description": "foo", "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "started_at_override": "2016-12-31T12:30:00Z", "state": "done", "team_ids": ["12345678-9012-3456-7890-123456789012"] }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
objectives Array [CreateObjectiveParams]	Required. Payloads for each Objective to create.

Responses

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

Bulk Update Objectives

Bulk Update Objectives updates multiple Objectives, and returns a paginated list of the updated Objectives.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "objectives": [{ "archived": true, "category_ids": [123], "category_ids_add": [123], "category_ids_remove": [123], "completed_at_override": "2016-12-31T12:30:00Z", "description": "foo", "id": 123, "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["12345678-9012-3456-7890-123456789012"], "started_at_override": "2016-12-31T12:30:00Z", "state": "done", "team_ids": ["12345678-9012-3456-7890-123456789012"], "team_ids_add": ["12345678-9012-3456-7890-123456789012"], "team_ids_remove": ["12345678-9012-3456-7890-123456789012"] }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/bulk"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "categories": [{
      "entity_type": "category:slim",
      "id": 123,
      "name": "foo",
      "uri": "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",
    "description": "foo",
    "entity_type": "objective",
    "epics": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "epic:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "healths": {
      "current_items": 123,
      "entities": [{
        "created_at": "2016-12-31T12:30:00Z",
        "entity_type": "health:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "status": "foo",
        "updated_at": "2016-12-31T12:30:00Z"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "key_results": {
      "current_items": 123,
      "entities": [{
        "entity_type": "key-result:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "state": "done",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
objectives Array [BulkUpdateObjectivesParams1]	Required. Payloads for each Objective to update.

Responses

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

Bulk Delete Objectives

Bulk Delete Objectives deletes multiple Objectives.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "objective_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

Body Parameters

Name	Description
objective_ids Array [Integer]	Required. Ids of the Objectives to delete.

Responses

Code	Description
204	No Content
400	Schema mismatch
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/v4/{workspace-slug}/objectives/{objective-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "categories": [{
    "entity_type": "category:slim",
    "id": 123,
    "name": "foo",
    "uri": "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",
  "description": "foo",
  "entity_type": "objective",
  "epics": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "healths": {
    "current_items": 123,
    "entities": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "health:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "status": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "key_results": {
    "current_items": 123,
    "entities": [{
      "entity_type": "key-result:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "name": "foo",
  "owners": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "done",
  "teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Objective

Update Objective is used to modify an Objective in your Shortcut Workspace.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "category_ids": [123], "category_ids_add": [123], "category_ids_remove": [123], "completed_at_override": "2016-12-31T12:30:00Z", "description": "foo", "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["12345678-9012-3456-7890-123456789012"], "started_at_override": "2016-12-31T12:30:00Z", "state": "done", "team_ids": ["12345678-9012-3456-7890-123456789012"], "team_ids_add": ["12345678-9012-3456-7890-123456789012"], "team_ids_remove": ["12345678-9012-3456-7890-123456789012"] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "categories": [{
    "entity_type": "category:slim",
    "id": 123,
    "name": "foo",
    "uri": "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",
  "description": "foo",
  "entity_type": "objective",
  "epics": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "healths": {
    "current_items": 123,
    "entities": [{
      "created_at": "2016-12-31T12:30:00Z",
      "entity_type": "health:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "status": "foo",
      "updated_at": "2016-12-31T12:30:00Z"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "key_results": {
    "current_items": 123,
    "entities": [{
      "entity_type": "key-result:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "name": "foo",
  "owners": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "state": "done",
  "teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
archived Boolean	Whether the Objective is archived.
category_ids Array [Integer]	An array of IDs of Categories to set on the Objective. Replaces current Categories.
category_ids_add Array [Integer]	An array of IDs of Categories to add to the Objective.
category_ids_remove Array [Integer]	An array of IDs of Categories to remove from 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.
owner_ids Array [UUID]	An array of UUIDs for Members to set as Owners. This will replace the current Owners on the Objective. Sending an empty array will delete all existing Owners.
owner_ids_add Array [UUID]	An array of UUIDs for Members to add as Owners. These will be added to the current Owners on the Objective.
owner_ids_remove Array [UUID]	An array of UUIDs for Members to remove as Owners. These will be removed from the current Owners on 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 of the Objective.
team_ids Array [UUID]	An array of UUIDs for Teams to associate with the Objective. This will replace the current Teams on the Objective. Sending an empty array will remove all existing Teams.
team_ids_add Array [UUID]	An array of UUIDs for Teams to add to the Objective. These will be added to the current Teams on the Objective.
team_ids_remove Array [UUID]	An array of UUIDs for Teams to remove from the Objective. These will be removed from the current Teams on the Objective.

Responses

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

Delete Objective

Delete Objective removes an Objective from the Workspace.

Definition

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

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
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 Categories

List Objective Categories returns a paginated list of all Categories associated with an Objective in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/categories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/categories"

Example Response

[
  {
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "category",
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Objective Epics

List Objective Epics returns a paginated list of all Epics associated with an Objective in the Workspace.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/epics"

Example Response

[
  {
    "app_url": "foo",
    "entity_type": "epic:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Objective Key Results

List Objective Key Results returns a paginated list of all Key Results associated with an Objective in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/key-results

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/key-results"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "current_observed_value": {
      "boolean_value": true,
      "created_at": "2016-12-31T12:30:00Z",
      "creator": {
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "numeric_value": "foo"
    },
    "current_target_value": {
      "boolean_value": true,
      "created_at": "2016-12-31T12:30:00Z",
      "creator": {
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "numeric_value": "foo"
    },
    "entity_type": "key-result",
    "id": "12345678-9012-3456-7890-123456789012",
    "initial_observed_value": {
      "boolean_value": true,
      "created_at": "2016-12-31T12:30:00Z",
      "creator": {
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "numeric_value": "foo"
    },
    "name": "foo",
    "objective": {
      "app_url": "foo",
      "entity_type": "objective:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "progress": 123,
    "type": "boolean",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Objective Healths

Returns a paginated list of Health updates for the specified Objective.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/objective-healths

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/objective-healths"

Example Response

[
  {
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "health",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "id": "12345678-9012-3456-7890-123456789012",
    "objective": {
      "app_url": "foo",
      "entity_type": "objective:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "status": "At Risk",
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Objective Health

Creates a new Health update for the specified Objective.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/objective-healths

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "status": "At Risk", "text": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/objective-healths"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
status Enum (At Risk, No Health, Off Track, On Track)	Required. The health status.
text String	The text body of the Health update.

Responses

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

Get Objective Health

Returns a Health for the specified Objective.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/objective-healths/{objective-health-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/objective-healths/{objective-health-public-id}"

Example Response

{
  "author": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "health",
  "epic": {
    "app_url": "foo",
    "entity_type": "epic:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "id": "12345678-9012-3456-7890-123456789012",
  "objective": {
    "app_url": "foo",
    "entity_type": "objective:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "status": "At Risk",
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.
objective-health-public-id UUID	Required. The unique ID of the Health.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Objective Owners

List Objective Owners returns a paginated list of all Members who own an Objective in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/owners

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/owners"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Objective Teams

List Objective Teams returns a paginated list of all Teams associated with an Objective in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/{objective-public-id}/teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
objective-public-id Integer	Required. The ID of the Objective.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Projects

List Projects

List Projects returns a paginated list of all Projects in the Workspace. Projects are a deprecated feature.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/projects

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/projects"

Example Response

[
  {
    "abbreviation": "foo",
    "app_url": "foo",
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "days_to_thermometer": 123,
    "description": "foo",
    "entity_type": "project",
    "external_id": "foo",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iteration_length": 123,
    "name": "foo",
    "show_thermometer": true,
    "start_time": "2016-12-31T12:30:00Z",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Project

Create Project allows you to create a new Project in Shortcut. Projects are a deprecated feature.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/projects

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "abbreviation": "foo", "color": "#6515dd", "description": "foo", "external_id": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "iteration_length": 123, "name": "foo", "start_time": "2016-12-31T12:30:00Z", "workflow_id": 123 }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/projects"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
abbreviation String (63)	The abbreviation for the Project. Should be kept to 3 characters at most.
color Color	The hex color for the Project (e.g., “#ff0000”).
description String (100000)	The description of the Project.
external_id String (128)	An external ID for the Project, for use when importing from another tool.
follower_ids Array [UUID]	UUIDs of Members to add as Followers of the Project.
iteration_length Integer	The number of weeks per iteration in this Project.
name String (2048)	Required. The name of the Project.
start_time Date	The date at which the Project was started.
workflow_id Integer	The ID of the Workflow for the Project. Defaults to the workspace default.

Responses

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

Get Project

Get Project returns information about the chosen Project. Projects are a deprecated feature.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/projects/{project-public-id}"

Example Response

{
  "abbreviation": "foo",
  "app_url": "foo",
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "days_to_thermometer": 123,
  "description": "foo",
  "entity_type": "project",
  "external_id": "foo",
  "followers": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "iteration_length": 123,
  "name": "foo",
  "show_thermometer": true,
  "start_time": "2016-12-31T12:30:00Z",
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "workflow": {
    "entity_type": "workflow:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  }
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
project-public-id Integer	Required. The unique ID of the Project.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Project

Update Project can be used to update Project properties. Projects are a deprecated feature.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/projects/{project-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "abbreviation": "foo", "archived": true, "color": "#6515dd", "days_to_thermometer": 123, "description": "foo", "follower_ids": ["12345678-9012-3456-7890-123456789012"], "follower_ids_add": ["12345678-9012-3456-7890-123456789012"], "follower_ids_remove": ["12345678-9012-3456-7890-123456789012"], "name": "foo", "show_thermometer": true }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/projects/{project-public-id}"

Example Response

{
  "abbreviation": "foo",
  "app_url": "foo",
  "archived": true,
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "days_to_thermometer": 123,
  "description": "foo",
  "entity_type": "project",
  "external_id": "foo",
  "followers": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "iteration_length": 123,
  "name": "foo",
  "show_thermometer": true,
  "start_time": "2016-12-31T12:30:00Z",
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "workflow": {
    "entity_type": "workflow:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  }
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
project-public-id Integer	Required. The unique ID of the Project.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
abbreviation String (63) or null	The abbreviation for the Project. Set to null to clear.
archived Boolean	Whether the Project is archived.
color Color or null	The hex color for the Project. Set to null to clear.
days_to_thermometer Integer	The number of days before the thermometer is shown.
description String (100000) or null	The description of the Project.
follower_ids Array [UUID]	UUIDs of Members to set as Followers. Replaces current followers.
follower_ids_add Array [UUID]	UUIDs of Members to add as Followers.
follower_ids_remove Array [UUID]	UUIDs of Members to remove as Followers.
name String (2048)	The name of the Project.
show_thermometer Boolean	Whether the thermometer is shown.

Responses

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

Delete Project

Delete Project can be used to delete any Project. Projects are a deprecated feature.

Definition

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

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/projects/{project-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
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 Project Followers

List Project Followers returns a paginated list of all Members following a Project. Projects are a deprecated feature.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/projects/{project-public-id}/followers

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/projects/{project-public-id}/followers"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
project-public-id Integer	Required. The unique ID of the Project.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Project Stories

List Project Stories returns a paginated list of all Stories associated with a Project. Projects are a deprecated feature.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/projects/{project-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
project-public-id Integer	Required. The unique ID of the Project.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Pull-Requests

List Pull Requests

List Pull Requests returns a paginated list of all Pull Requests in the Workspace that have been associated with a Story.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/pull-requests

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/pull-requests"

Example Response

[
  {
    "branch": {
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "closed": true,
    "created_at": "2016-12-31T12:30:00Z",
    "draft": true,
    "entity_type": "pull-request",
    "external_id": "foo",
    "external_url": "foo",
    "id": 123,
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "target_branch": {
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "title": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_closed, include_closed)	Filter options (default: :include_closed).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Get Pull Request

Get Pull Request returns information about a chosen Pull Request.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/pull-requests/{pull-request-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/pull-requests/{pull-request-public-id}"

Example Response

{
  "branch": {
    "entity_type": "branch:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "closed": true,
  "created_at": "2016-12-31T12:30:00Z",
  "draft": true,
  "entity_type": "pull-request",
  "external_id": "foo",
  "external_url": "foo",
  "id": 123,
  "repository": {
    "entity_type": "repository:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "target_branch": {
    "entity_type": "branch:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "title": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
pull-request-public-id Integer	Required. The ID of the Pull Request.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Pull Request Stories

List Pull Request Stories returns a paginated list of all Stories associated with a Pull Request in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/pull-requests/{pull-request-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/pull-requests/{pull-request-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
pull-request-public-id Integer	Required. The ID of the Pull Request.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Repositories

List Repositories

List Repositories returns a paginated list of all connected Repositories in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories"

Example Response

[
  {
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "repository",
    "external_url": "foo",
    "full_name": "foo",
    "id": 123,
    "name": "foo",
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Get Repository

Get Repository returns information about a connected Repository.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories/{repository-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories/{repository-public-id}"

Example Response

{
  "branches": {
    "current_items": 123,
    "entities": [{
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "commits": {
    "current_items": 123,
    "entities": [{
      "entity_type": "commit:slim",
      "id": 123,
      "message": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "repository",
  "external_url": "foo",
  "full_name": "foo",
  "id": 123,
  "name": "foo",
  "pull_requests": {
    "current_items": 123,
    "entities": [{
      "entity_type": "pull-request:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
repository-public-id Integer	Required. The ID of the Repository.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Repository Branches

List Repository Branches returns a paginated list of all Branches associated with a Repository in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories/{repository-public-id}/branches

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories/{repository-public-id}/branches"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "branch",
    "external_url": "foo",
    "id": 123,
    "name": "foo",
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
repository-public-id Integer	Required. The ID of the Repository.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_deleted, include_deleted)	Filter options (default: :exclude_deleted).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Repository Commits

List Repository Commits returns a paginated list of all Commits associated with a Repository in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories/{repository-public-id}/commits

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories/{repository-public-id}/commits"

Example Response

[
  {
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "commit",
    "external_url": "foo",
    "hash": "foo",
    "id": 123,
    "message": "foo",
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
repository-public-id Integer	Required. The ID of the Repository.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Repository Pull Requests

List Repository Pull Requests returns a paginated list of all Pull Requests associated with a Repository in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories/{repository-public-id}/pull-requests

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/repositories/{repository-public-id}/pull-requests"

Example Response

[
  {
    "branch": {
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "closed": true,
    "created_at": "2016-12-31T12:30:00Z",
    "draft": true,
    "entity_type": "pull-request",
    "external_id": "foo",
    "external_url": "foo",
    "id": 123,
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "target_branch": {
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "title": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
repository-public-id Integer	Required. The ID of the Repository.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_closed, include_closed)	Filter options (default: :include_closed).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Stories

List Stories

List Stories returns a paginated list of all Stories in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
ids String	A comma-separated list of ids. If included, only those entities will be considered for listing.
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Story

Create Story is used to add a new Story to your Shortcut Workspace.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/stories

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "checklist_items": [{ "completed": true, "description": "foo", "external_id": "foo", "set_position": {
    "anchor_checklist_item_id": 123,
    "position": "after"
  } }], "custom_field_values": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_id": 123, "estimate": 123, "external_id": "foo", "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "iteration_id": 123, "label_ids": [123], "linked_file_ids": [123], "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "parent_story_id": 123, "project_id": 123, "requester_id": "12345678-9012-3456-7890-123456789012", "set_position": { "anchor_story_id": 123, "position": "after" }, "story_links": [{ "object_story_id": 123, "subject_story_id": 123, "verb": "blocks" }], "story_type": "bug", "team_id": "12345678-9012-3456-7890-123456789012", "workflow_state_id": 123 }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
archived Boolean	Controls the Story’s archived state.
checklist_items Array [CreateStoryChecklistItemParams]	An array of Checklist Items connected to the Story.
custom_field_values Array [CreateCustomFieldValueParams]	An array of objects specifying a Custom Field value ID and CustomFieldEnumValue ID that represents an assertion of some value for a Custom Field value.
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 (128)	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 the 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 Members that follow this Story.
iteration_id Integer or null	The ID of the Iteration the Story belongs to.
label_ids Array [Integer]	Labels to attach to the Story.
linked_file_ids Array [Integer]	An array of IDs of Linked Files attached to the Story.
name String (512)	Required. The name of the Story.
owner_ids Array [UUID]	An array of UUIDs of the Members that own this Story.
parent_story_id Integer or null	The ID of the parent Story to associate with this Story (making the Story a sub-task). Field only applicable when Sub-task feature is enabled.
project_id Integer or null	The ID of the Project the Story belongs to.
requester_id UUID	The ID of the Member that requested the Story. Will default to the Member making the API call if not provided.
set_position Body5196896SetPosition	One of “first”, “last”, “before”, or “after”. This can be used to move the given story to the first or last position in the Workflow State, or before or after a given Story.
story_links Array [CreateNestedStoryLinkParams]	An array of Story links attached to the Story.
story_type Enum (bug, chore, feature)	The type of Story (feature, bug, chore).
team_id UUID or null	The id of the Team to associate with this Story.
workflow_state_id Integer	Required. 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

Bulk Create Stories

Bulk Create Stories creates multiple Stories, and returns a paginated list of the created Stories.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "stories": [{ "archived": true, "checklist_items": [{
    "completed": true,
    "description": "foo",
    "external_id": "foo",
    "set_position": {
      "anchor_checklist_item_id": 123,
      "position": "after"
    }
  }], "custom_field_values": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }], "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_id": 123, "estimate": 123, "external_id": "foo", "external_links": [], "file_ids": [123], "follower_ids": ["12345678-9012-3456-7890-123456789012"], "iteration_id": 123, "label_ids": [123], "linked_file_ids": [123], "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "parent_story_id": 123, "project_id": 123, "requester_id": "12345678-9012-3456-7890-123456789012", "set_position": {
    "anchor_story_id": 123,
    "position": "after"
  }, "story_links": [{
    "object_story_id": 123,
    "subject_story_id": 123,
    "verb": "blocks"
  }], "story_type": "bug", "team_id": "12345678-9012-3456-7890-123456789012", "workflow_state_id": 123 }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
stories Array [CreateStoryParams]	Required. Payloads for each Story to create.

Responses

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

Bulk Update Stories

Bulk Update Stories updates multiple Stories, and returns a paginated list of the updated Stories.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "stories": [{ "archived": true, "custom_field_values": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }], "custom_field_values_add": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }], "custom_field_values_remove": [{
    "field_id": "12345678-9012-3456-7890-123456789012",
    "value_id": "12345678-9012-3456-7890-123456789012"
  }], "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_id": 123, "estimate": 123, "external_id": "foo", "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"], "id": 123, "iteration_id": 123, "label_ids": [123], "label_ids_add": [123], "label_ids_remove": [123], "linked_file_ids": [123], "linked_file_ids_add": [123], "linked_file_ids_remove": [123], "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["12345678-9012-3456-7890-123456789012"], "parent_story_id": 123, "project_id": 123, "requester_id": "12345678-9012-3456-7890-123456789012", "set_position": {
    "anchor_story_id": 123,
    "position": "after"
  }, "story_type": "bug", "team_id": "12345678-9012-3456-7890-123456789012", "workflow_state_id": 123 }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/bulk"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
stories Array [BulkUpdateStoriesParams1]	Required. Payloads for each Story to update.

Responses

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

Bulk Delete Stories

Bulk Delete Stories deletes multiple Stories. The Stories must be archived unless force is set.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/bulk

Example Request

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

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
force Boolean	Forces deletion of the Stories, overriding the check that they are archived.

Body Parameters

Name	Description
story_ids Array [Integer]	Required. Ids of the archived Stories to delete.

Responses

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

Search Stories

Search Stories lets you search Stories based on a query.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/search

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/search"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
query String	The search query. Required if `cursor` is not sent. See our help center article on search operators.
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

Code	Description
200	[ Story, … ]
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/v4/{workspace-slug}/stories/{story-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "blocked": true,
  "blocker": true,
  "branches": {
    "current_items": 123,
    "entities": [{
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "checklist_items": {
    "current_items": 123,
    "entities": [{
      "description": "foo",
      "entity_type": "checklist-item:slim",
      "id": 123,
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "comments": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "deleted": true,
      "entity_type": "comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "commits": {
    "current_items": 123,
    "entities": [{
      "entity_type": "commit:slim",
      "id": 123,
      "message": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 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_field_values": {
    "current_items": 123,
    "entities": [{
      "entity_type": "custom-field-value:slim",
      "field": {
        "entity_type": "custom-field:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "id": "12345678-9012-3456-7890-123456789012",
      "value": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "story",
  "epic": {
    "app_url": "foo",
    "entity_type": "epic:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "estimate": 123,
  "external_id": "foo",
  "external_links": {
    "current_items": 123,
    "entities": [{
      "entity_type": "external-link",
      "value": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "files": {
    "current_items": 123,
    "entities": [{
      "entity_type": "file:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "followers": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "iterations": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "iteration:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "labels": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "label:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "linked_files": {
    "current_items": 123,
    "entities": [{
      "entity_type": "linked-file:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "moved_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "owners": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "parent_story": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "position": 123,
  "project": {
    "app_url": "foo",
    "entity_type": "project:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "pull_requests": {
    "current_items": 123,
    "entities": [{
      "entity_type": "pull-request:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "requester": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "story_links": {
    "current_items": 123,
    "entities": [{
      "entity_type": "story-link:slim",
      "id": 123,
      "object": {
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "subject": {
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "uri": "foo",
      "verb": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "story_template": {
    "entity_type": "story-template:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "story_type": "bug",
  "sub_task_stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "team": {
    "app_url": "foo",
    "entity_type": "team:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "workflow": {
    "entity_type": "workflow:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "workflow_state": {
    "entity_type": "workflow-state:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo",
    "workflow_name": "foo"
  }
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Story

Update Story is used to modify a Story in your Shortcut Workspace.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "custom_field_values": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value_id": "12345678-9012-3456-7890-123456789012" }], "custom_field_values_add": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value_id": "12345678-9012-3456-7890-123456789012" }], "custom_field_values_remove": [{ "field_id": "12345678-9012-3456-7890-123456789012", "value_id": "12345678-9012-3456-7890-123456789012" }], "deadline": "2016-12-31T12:30:00Z", "description": "foo", "epic_id": 123, "estimate": 123, "external_id": "foo", "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"], "iteration_id": 123, "label_ids": [123], "label_ids_add": [123], "label_ids_remove": [123], "linked_file_ids": [123], "linked_file_ids_add": [123], "linked_file_ids_remove": [123], "name": "foo", "owner_ids": ["12345678-9012-3456-7890-123456789012"], "owner_ids_add": ["12345678-9012-3456-7890-123456789012"], "owner_ids_remove": ["12345678-9012-3456-7890-123456789012"], "parent_story_id": 123, "project_id": 123, "requester_id": "12345678-9012-3456-7890-123456789012", "set_position": { "anchor_story_id": 123, "position": "after" }, "story_type": "bug", "team_id": "12345678-9012-3456-7890-123456789012", "workflow_state_id": 123 }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "blocked": true,
  "blocker": true,
  "branches": {
    "current_items": 123,
    "entities": [{
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "checklist_items": {
    "current_items": 123,
    "entities": [{
      "description": "foo",
      "entity_type": "checklist-item:slim",
      "id": 123,
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "comments": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "deleted": true,
      "entity_type": "comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "commits": {
    "current_items": 123,
    "entities": [{
      "entity_type": "commit:slim",
      "id": 123,
      "message": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 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_field_values": {
    "current_items": 123,
    "entities": [{
      "entity_type": "custom-field-value:slim",
      "field": {
        "entity_type": "custom-field:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      },
      "id": "12345678-9012-3456-7890-123456789012",
      "value": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "deadline": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "story",
  "epic": {
    "app_url": "foo",
    "entity_type": "epic:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "estimate": 123,
  "external_id": "foo",
  "external_links": {
    "current_items": 123,
    "entities": [{
      "entity_type": "external-link",
      "value": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "files": {
    "current_items": 123,
    "entities": [{
      "entity_type": "file:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "followers": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "id": 123,
  "iterations": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "iteration:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "labels": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "label:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "linked_files": {
    "current_items": 123,
    "entities": [{
      "entity_type": "linked-file:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "moved_at": "2016-12-31T12:30:00Z",
  "name": "foo",
  "owners": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "parent_story": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "position": 123,
  "project": {
    "app_url": "foo",
    "entity_type": "project:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "pull_requests": {
    "current_items": 123,
    "entities": [{
      "entity_type": "pull-request:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "requester": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "started": true,
  "started_at": "2016-12-31T12:30:00Z",
  "started_at_override": "2016-12-31T12:30:00Z",
  "story_links": {
    "current_items": 123,
    "entities": [{
      "entity_type": "story-link:slim",
      "id": 123,
      "object": {
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "subject": {
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      },
      "uri": "foo",
      "verb": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "story_template": {
    "entity_type": "story-template:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "story_type": "bug",
  "sub_task_stories": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "team": {
    "app_url": "foo",
    "entity_type": "team:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "workflow": {
    "entity_type": "workflow:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "workflow_state": {
    "entity_type": "workflow-state:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo",
    "workflow_name": "foo"
  }
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
archived Boolean	Controls the Story’s archived state.
custom_field_values Array [CreateCustomFieldValueParams]	An array of objects specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a Custom Field. This will replace the current Custom Field values on the Story. Sending an empty array will delete all existing Custom Field values.
custom_field_values_add Array [CreateCustomFieldValueParams]	An array of objects specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a Custom Field. These will be added to the current Custom Field values on the Story.
custom_field_values_remove Array [CreateCustomFieldValueParams]	An array of objects specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a Custom Field. These will be removed from the current Custom Field values on the Story.
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 (128)	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 the Story. This will replace the current External Links on the Story. Sending an empty array will delete all existing External Links.
external_links_add Array [String]	An array of External Links associated with the Story. These will be added to the current External Links on the Story.
external_links_remove Array [String]	An array of External Links associated with the Story. These will be removed from the current External Links on the Story.
file_ids Array [Integer]	An array of IDs of Files attached to the Story. This will replace the current Files on the Story. Sending an empty array will delete all existing Files.
file_ids_add Array [Integer]	An array of IDs of Files attached to the Story. These will be added to the current files on the Story.
file_ids_remove Array [Integer]	An array of IDs of Files attached to the Story. These will be added to the current files on the Story.
follower_ids Array [UUID]	An array of UUIDs of the Members that follow this Story. This will replace the current Followers on the Story. Sending an empty array will delete all existing Followers.
follower_ids_add Array [UUID]	An array of UUIDs of the Members that follow this Story. These will be added to the current followers on the Story.
follower_ids_remove Array [UUID]	An array of UUIDs of the Members that follow this Story. These will be removed from the current followers on the Story.
iteration_id Integer or null	The ID of the Iteration the Story belongs to.
label_ids Array [Integer]	Labels to attach to the Story. This will replace the current Labels on the Story. Sending an empty array will delete all existing Labels.
label_ids_add Array [Integer]	Labels to attach to the Story. These will be added to the current Labels on the Story.
label_ids_remove Array [Integer]	Labels to detach from the Story. These will be removed to the current Labels on the Story.
linked_file_ids Array [Integer]	An array of IDs of Linked Files attached to the Story. This will replace the current Linked Files on the Story. Sending an empty array will delete all existing Linked Files.
linked_file_ids_add Array [Integer]	An array of IDs of Linked Files attached to the Story. These will be added to the current files on the Story.
linked_file_ids_remove Array [Integer]	An array of IDs of Linked Files attached to the Story. These will be added to the current files on the Story.
name String (512)	The name of the Story.
owner_ids Array [UUID]	An array of UUIDs of the Members that own this Story. This will replace the current Owners on the Story. Sending an empty array will delete all existing Owners.
owner_ids_add Array [UUID]	An array of UUIDs of the Members that own this Story. These will be added to the current owners on the Story.
owner_ids_remove Array [UUID]	An array of UUIDs of the Members that own this Story. These will be removed from the current owners on the Story.
parent_story_id Integer or null	The ID of the parent Story to associate with this Story (making the Story a sub-task). Field only applicable when Sub-task feature is enabled.
project_id Integer or null	The ID of the Project the Story belongs to.
requester_id UUID	The ID of the Member that requested the Story. Will default to the Member making the API call if not provided.
set_position Body5196837SetPosition	One of “first”, “last”, “before”, or “after”. This can be used to move the given story to the first or last position in the Workflow State, or before or after a given Story.
story_type Enum (bug, chore, feature)	The type of Story (feature, bug, chore).
team_id UUID or null	The id of the Team to associate with this Story.
workflow_state_id Integer	The ID of the Workflow State to move the Story to.

Responses

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

Delete Story

Delete Story can be used to delete a Story. The Story must be archived unless force is set.

Definition

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

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
force Boolean	Forces deletion of the Story, overriding the check that it is archived.

Responses

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

List Story Branches

List Story Branches returns a paginated list of all Branches for a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/branches

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/branches"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "branch",
    "external_url": "foo",
    "id": 123,
    "name": "foo",
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_deleted, include_deleted)	Filter options (default: :exclude_deleted).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Checklist Items

List Story Checklist Items returns a paginated list of all Checklist Items for a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items"

Example Response

[
  {
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "checklist-item",
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "position": 123,
    "story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
ids String	A comma-separated list of ids. If included, only those entities will be considered for listing.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (position)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

Create Story Checklist Item

Create Story Checklist Item is used to add a new Checklist Item to a Story.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "completed": true, "description": "foo", "external_id": "foo", "set_position": { "anchor_checklist_item_id": 123, "position": "after" } }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
completed Boolean	True/false boolean indicating whether the Checklist Item is completed. Defaults to false.
description String (2048)	Required. The Checklist Item description.
external_id String (128)	This field can be set to another unique ID. In the case that the Checklist Item has been imported from another tool, the ID in the other tool can be indicated here.
set_position Body5196877SetPosition	One of “first”, “last”, “before”, or “after”. This can be used to move the Checklist Item to the first or last position in the Story’s checklist, or before or after a given Checklist Item.

Responses

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

Bulk Create Story Checklist Items

Bulk Create Story Checklist Items creates multiple Checklist Items on a Story, and returns a paginated list of the created Checklist Items.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "checklist_items": [{ "completed": true, "description": "foo", "external_id": "foo", "set_position": {
    "anchor_checklist_item_id": 123,
    "position": "after"
  } }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (position)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Body Parameters

Name	Description
checklist_items Array [CreateStoryChecklistItemParams]	Required. Payloads for each Checklist Item to create.

Responses

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

Bulk Update Story Checklist Items

Bulk Update Story Checklist Items updates multiple Checklist Items on a Story, and returns a paginated list of the updated Checklist Items.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "checklist_items": [{ "completed": true, "description": "foo", "id": 123, "set_position": {
    "anchor_checklist_item_id": 123,
    "position": "after"
  } }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/bulk"

Example Response

[
  {
    "completed": true,
    "completed_at": "2016-12-31T12:30:00Z",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "checklist-item",
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "position": 123,
    "story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (position)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Body Parameters

Name	Description
checklist_items Array [BulkUpdateStoryChecklistItemsParams1]	Required. Payloads for each Checklist Item to update.

Responses

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

Bulk Delete Story Checklist Items

Bulk Delete Story Checklist Items deletes multiple Checklist Items from a Story.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "checklist_item_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

Body Parameters

Name	Description
checklist_item_ids Array [Integer]	Required. Ids of the Checklist Items to delete.

Responses

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

Get Story Checklist Item

Get Story Checklist Item returns information about a chosen Checklist Item for a Story.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}"

Example Response

{
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "checklist-item",
  "external_id": "foo",
  "id": 123,
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "position": 123,
  "story": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
checklist-item-public-id Integer	Required. The ID of the Checklist Item.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Story Checklist Item

Update Story Checklist Item is used to modify a Checklist Item on a Story.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "completed": true, "description": "foo", "set_position": { "anchor_checklist_item_id": 123, "position": "after" } }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}"

Example Response

{
  "completed": true,
  "completed_at": "2016-12-31T12:30:00Z",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "checklist-item",
  "external_id": "foo",
  "id": 123,
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "position": 123,
  "story": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
checklist-item-public-id Integer	Required. The ID of the Checklist Item.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
completed Boolean	True/false boolean indicating whether the Checklist Item is completed. Defaults to false.
description String (2048)	The Checklist Item description.
set_position Body5196883SetPosition	One of “first”, “last”, “before”, or “after”. This can be used to move the Checklist Item to the first or last position in the Story’s checklist, or before or after a given Checklist Item.

Responses

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

Delete Story Checklist Item

Delete a Checklist Item from a Story.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
checklist-item-public-id Integer	Required. The ID of the Checklist Item.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Checklist Item Mentioned Members

List Story Checklist Item Mentioned Members returns a paginated list of all Members mentioned in a Story Checklist Item in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}/mentioned-members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}/mentioned-members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
checklist-item-public-id Integer	Required. The ID of the Checklist Item.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (name)	Order the results by this property and direction.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

List Story Checklist Item Mentioned Teams

List Story Checklist Item Mentioned Teams returns a paginated list of all Teams mentioned in a Story Checklist Item in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}/mentioned-teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/checklist-items/{checklist-item-public-id}/mentioned-teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
checklist-item-public-id Integer	Required. The ID of the Checklist Item.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (name, updated_at)	Order the results by this property and direction.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

List Story Comments

List Story Comments returns a paginated list of all Comments for a Story in the Workspace. Note that deleted comments will also be returned, but will have minimal information. The deleted comments are included as they may be parents to other comments.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments"

Example Response

[
  {
    "app_url": "foo",
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "comment",
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_comment": {
      "app_url": "foo",
      "deleted": true,
      "entity_type": "comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    },
    "position": 123,
    "reactions": {
      "current_items": 123,
      "entities": [{
        "emoji": "foo",
        "entity_type": "reaction:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
ids String	A comma-separated list of ids. If included, only those entities will be considered for listing.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (position)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

Create Story Comment

Create Story is used to add a new Comment to a Story.

Definition

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

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "author_id": "12345678-9012-3456-7890-123456789012", "external_id": "foo", "parent_comment_id": 123, "text": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
author_id UUID	The Member ID of the Comment’s author. Defaults to the user identified by the API token. Requires the admin role to set.
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.
parent_comment_id Integer	The ID of the Comment that this comment is threaded under.
text String (100000)	Required. The comment text.

Responses

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

Bulk Create Story Comments

Bulk Create Story Comments creates multiple Comments on a Story, and returns a paginated list of the created Comments.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "comments": [{ "author_id": "12345678-9012-3456-7890-123456789012", "external_id": "foo", "parent_comment_id": 123, "text": "foo" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (position)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Body Parameters

Name	Description
comments Array [CreateStoryCommentParams]	Required. Payloads for each Comment to create.

Responses

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

Bulk Update Story Comments

Bulk Update Story Comments updates multiple Comments on a Story, and returns a paginated list of the updated Comments.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "comments": [{ "id": 123, "text": "foo" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/bulk"

Example Response

[
  {
    "app_url": "foo",
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "comment",
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_comment": {
      "app_url": "foo",
      "deleted": true,
      "entity_type": "comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    },
    "position": 123,
    "reactions": {
      "current_items": 123,
      "entities": [{
        "emoji": "foo",
        "entity_type": "reaction:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (position)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Body Parameters

Name	Description
comments Array [BulkUpdateStoryCommentsParams1]	Required. Payloads for each Comment to update.

Responses

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

Bulk Delete Story Comments

Bulk Delete Story Comments deletes multiple Comments from a Story.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "comment_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

Body Parameters

Name	Description
comment_ids Array [Integer]	Required. Ids of the Comments to delete.

Responses

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

Get Story Comment

Get Story Comment returns information about a chosen Story Comment.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}"

Example Response

{
  "app_url": "foo",
  "author": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "comment",
  "external_id": "foo",
  "id": 123,
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "parent_comment": {
    "app_url": "foo",
    "deleted": true,
    "entity_type": "comment:slim",
    "id": 123,
    "text": "foo",
    "uri": "foo"
  },
  "position": 123,
  "reactions": {
    "current_items": 123,
    "entities": [{
      "emoji": "foo",
      "entity_type": "reaction:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "story": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Story Comment

Update Story Comment is used to modify a Story Comment.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "text": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}"

Example Response

{
  "app_url": "foo",
  "author": {
    "entity_type": "member:slim",
    "id": "12345678-9012-3456-7890-123456789012",
    "name": "foo",
    "uri": "foo"
  },
  "created_at": "2016-12-31T12:30:00Z",
  "deleted": true,
  "entity_type": "comment",
  "external_id": "foo",
  "id": 123,
  "mentioned_members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mentioned_teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "parent_comment": {
    "app_url": "foo",
    "deleted": true,
    "entity_type": "comment:slim",
    "id": 123,
    "text": "foo",
    "uri": "foo"
  },
  "position": 123,
  "reactions": {
    "current_items": 123,
    "entities": [{
      "emoji": "foo",
      "entity_type": "reaction:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "story": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "text": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
text String (100000)	The comment text.

Responses

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

Delete Story Comment

Delete a Comment from a Story.

Definition

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

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Comment Comments

List Story Comment Comments returns a paginated list of all threaded reply Comments for a Story Comment in the Workspace.

Definition

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

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}/comments"

Example Response

[
  {
    "app_url": "foo",
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "deleted": true,
    "entity_type": "comment",
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_comment": {
      "app_url": "foo",
      "deleted": true,
      "entity_type": "comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    },
    "position": 123,
    "reactions": {
      "current_items": 123,
      "entities": [{
        "emoji": "foo",
        "entity_type": "reaction:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "text": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (position)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

List Story Comment Mentioned Members

List Story Comment Mentioned Members returns a paginated list of all Members mentioned in a Story Comment in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}/mentioned-members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}/mentioned-members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (name)	Order the results by this property and direction.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

List Story Comment Mentioned Teams

List Story Comment Mentioned Teams returns a paginated list of all Teams mentioned in a Story Comment in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}/mentioned-teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}/mentioned-teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (name, updated_at)	Order the results by this property and direction.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

List Story Comment Reactions

List Story Comment Reactions returns a paginated list of all Reactions to a Story Comment in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}/reactions

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}/reactions"

Example Response

[
  {
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "comment": {
      "app_url": "foo",
      "deleted": true,
      "entity_type": "comment:slim",
      "id": 123,
      "text": "foo",
      "uri": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "emoji": "foo",
    "entity_type": "reaction",
    "id": "12345678-9012-3456-7890-123456789012",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
order_by Enum (created_at)	Order the results by this property and direction.
filter Enum (all)	Filter options (default: :all).
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.

Responses

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

Create Story Comment Reaction

Create a Reaction to a Story Comment.

Definition

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

Example Request

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

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
comment-public-id Integer	Required. The ID of the Comment.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

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

Responses

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

Delete Story Comment Reaction

Delete a Reaction from a Story Comment.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}/reactions/{reaction-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/comments/{comment-public-id}/reactions/{reaction-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.
comment-public-id Integer	Required. The ID of the Comment.
reaction-public-id UUID	Required. The ID of the Reaction.

Responses

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

List Story Commits

List Story Commits returns a paginated list of all Commits associated with a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/commits

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/commits"

Example Response

[
  {
    "author": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "commit",
    "external_url": "foo",
    "hash": "foo",
    "id": 123,
    "message": "foo",
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "timestamp": "2016-12-31T12:30:00Z",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Custom Field Values

List Story Custom Field Values returns a paginated list of all Custom Field Values for a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/custom-field-values

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/custom-field-values"

Example Response

[
  {
    "color_key": "black",
    "enabled": true,
    "entity_type": "custom-field-value",
    "field": {
      "entity_type": "custom-field:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "id": "12345678-9012-3456-7890-123456789012",
    "position": 123,
    "value": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (field_name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story External Links

List Story External Links returns a paginated list of all External Links for a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/external-links

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/external-links"

Example Response

[
  {
    "entity_type": "external-link",
    "value": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (value)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Files

List Story Files returns a paginated list of all Files attached to a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/files

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/files"

Example Response

[
  {
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "file",
    "external_id": "foo",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "size": 123,
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "thumbnail_url": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "uri": "foo",
    "url": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Followers

List Story Followers returns a paginated list of all Members who are following a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/followers

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/followers"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Iterations

List Story Iterations returns a paginated list of all Iterations associated with a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/iterations

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/iterations"

Example Response

[
  {
    "app_url": "foo",
    "associated_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "end_date": "foo",
    "entity_type": "iteration",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "start_date": "foo",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (start_date, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Labels

List Story Labels returns a paginated list of all Labels for a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/labels

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/labels"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "label",
    "epics": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "epic:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "external_id": "foo",
    "id": 123,
    "name": "foo",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Linked Files

List Story Linked Files returns a paginated list of all Linked Files attached to a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/linked-files

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/linked-files"

Example Response

[
  {
    "content_type": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "linked-file",
    "id": 123,
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "name": "foo",
    "size": 123,
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "thumbnail_url": "foo",
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uploader": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "uri": "foo",
    "url": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Mentioned Members

List Story Mentioned Members returns a paginated list of all Members mentioned in a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/mentioned-members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/mentioned-members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Mentioned Teams

List Story Mentioned Teams returns a paginated list of all Teams mentioned in a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/mentioned-teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/mentioned-teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Owners

List Story Owners returns a paginated list of all Members who own a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/owners

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/owners"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Pull Requests

List Story Pull Requests returns a paginated list of all Pull Requests associated with a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/pull-requests

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/pull-requests"

Example Response

[
  {
    "branch": {
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "closed": true,
    "created_at": "2016-12-31T12:30:00Z",
    "draft": true,
    "entity_type": "pull-request",
    "external_id": "foo",
    "external_url": "foo",
    "id": 123,
    "repository": {
      "entity_type": "repository:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "target_branch": {
      "entity_type": "branch:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "title": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_closed, include_closed)	Filter options (default: :include_closed).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Story Links

List Story Story Links returns a paginated list of all Story Links associated with a Story in the Workspace. This includes links where the Story is either the subject or the object of the relationship.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/story-links

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/story-links"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "story-link",
    "id": 123,
    "object": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "subject": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "verb": "blocks"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Story Sub-Task Stories

List Story Sub-Task Stories returns a paginated list of all Sub-Task Stories for a Story in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/sub-task-stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/stories/{story-public-id}/sub-task-stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-public-id Integer	Required. The ID of the Story.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Story-Links

List Story Links

List Story Links returns a paginated list of all Story Links in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "story-link",
    "id": 123,
    "object": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "subject": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "verb": "blocks"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Story Link

Create Story Link is used to create a semantic relationship between two Stories. The subject Story acts on the object Story. For example, “Story A blocks Story B”.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "object_story_id": 123, "subject_story_id": 123, "verb": "blocks" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

Body Parameters

Name	Description
object_story_id Integer	Required. The unique ID of the Story defined as object.
subject_story_id Integer	Required. The unique ID of the Story defined as subject.
verb Enum (blocks, duplicates, relates to)	Required. How the subject Story acts on the object Story. This can be one of: “blocks”, “duplicates”, “relates to”

Responses

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

Bulk Create Story Links

Bulk Create Story Links creates multiple Story Links, and returns a paginated list of the created Story Links.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "story_links": [{ "object_story_id": 123, "subject_story_id": 123, "verb": "blocks" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
story_links Array [CreateStoryLinkParams]	Required. Payloads for each Story Link to create.

Responses

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

Bulk Update Story Links

Bulk Update Story Links updates multiple Story Links, and returns a paginated list of the updated Story Links.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "story_links": [{ "id": 123, "object_story_id": 123, "subject_story_id": 123, "verb": "blocks" }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/bulk"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "entity_type": "story-link",
    "id": 123,
    "object": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "subject": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "verb": "blocks"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
story_links Array [UpdateStoryLinkParams]	Required. Payloads for each Story Link to update.

Responses

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

Bulk Delete Story Links

Bulk Delete Story Links deletes multiple Story Links.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/bulk

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "story_link_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

Body Parameters

Name	Description
story_link_ids Array [Integer]	Required. IDs of the Story Links to delete.

Responses

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

Get Story Link

Get Story Link returns information about a chosen Story Link.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/{story-link-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/{story-link-public-id}"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "story-link",
  "id": 123,
  "object": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "subject": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "verb": "blocks"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-link-public-id Integer	Required. The ID of the Story Link.

Responses

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

Update Story Link

Update Story Link is used to modify the stories or verb of an existing Story Link.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/{story-link-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "object_story_id": 123, "subject_story_id": 123, "verb": "blocks" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/{story-link-public-id}"

Example Response

{
  "created_at": "2016-12-31T12:30:00Z",
  "entity_type": "story-link",
  "id": 123,
  "object": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "subject": {
    "app_url": "foo",
    "entity_type": "story:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "verb": "blocks"
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-link-public-id Integer	Required. The ID of the Story Link.

Body Parameters

Name	Description
object_story_id Integer	The unique ID of the Story defined as object.
subject_story_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 one of: “blocks”, “duplicates”, “relates to”

Responses

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

Delete Story Link

Delete Story Link removes the relationship between the Stories for the given Story Link.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/{story-link-public-id}

Example Request

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/story-links/{story-link-public-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
story-link-public-id Integer	Required. The ID of the Story Link.

Responses

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

Teams

List Teams

Returns a paginated list of all Teams in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Create Team

Creates a new Team in the Workspace.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/teams

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "color": "#6515dd", "color_key": "black", "default_workflow_id": 123, "description": "foo", "member_ids": ["12345678-9012-3456-7890-123456789012"], "mention_name": "foo", "name": "foo", "workflow_ids": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/teams"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
color Color	The hex color to be displayed with the Team (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)	The color key to be displayed with the Team.
default_workflow_id Integer	The ID of the default Workflow for Stories created in this Team.
description String (4096)	The Team’s description.
member_ids Array [UUID]	An array of UUIDs for Members to add to the Team.
mention_name String	Required. The Team’s mention name.
name String (63)	Required. The Team’s name.
workflow_ids Array [Integer]	Required. An array of IDs for Workflows to associate with the Team. At least one Workflow is required.

Responses

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

Bulk Create Teams

Creates multiple Teams and returns a paginated list of the created Teams.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/bulk

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "teams": [{ "color": "#6515dd", "color_key": "black", "default_workflow_id": 123, "description": "foo", "member_ids": ["12345678-9012-3456-7890-123456789012"], "mention_name": "foo", "name": "foo", "workflow_ids": [123] }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/bulk"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
teams Array [CreateTeamParams]	Required. Payloads for each Team to create.

Responses

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

Bulk Update Teams

Updates multiple Teams and returns a paginated list of the updated Teams.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/bulk

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "teams": [{ "archived": true, "color": "#6515dd", "color_key": "black", "default_workflow_id": 123, "description": "foo", "id": "12345678-9012-3456-7890-123456789012", "member_ids": ["12345678-9012-3456-7890-123456789012"], "member_ids_add": ["12345678-9012-3456-7890-123456789012"], "member_ids_remove": ["12345678-9012-3456-7890-123456789012"], "mention_name": "foo", "name": "foo", "workflow_ids": [123], "workflow_ids_add": [123], "workflow_ids_remove": [123] }] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/bulk"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
teams Array [BulkUpdateTeamsParams1]	Required. Payloads for each Team to update.

Responses

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

Get Team

Returns the specified Team.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "color_key": "black",
  "created_at": "2016-12-31T12:30:00Z",
  "default_workflow": {
    "entity_type": "workflow:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "description": "foo",
  "entity_type": "team",
  "id": "12345678-9012-3456-7890-123456789012",
  "members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mention_name": "foo",
  "name": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "workflows": {
    "current_items": 123,
    "entities": [{
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  }
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
team-public-id UUID	Required. The UUID of the Team.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Update Team

Updates the specified Team.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "archived": true, "color": "#6515dd", "color_key": "black", "default_workflow_id": 123, "description": "foo", "member_ids": ["12345678-9012-3456-7890-123456789012"], "member_ids_add": ["12345678-9012-3456-7890-123456789012"], "member_ids_remove": ["12345678-9012-3456-7890-123456789012"], "mention_name": "foo", "name": "foo", "workflow_ids": [123], "workflow_ids_add": [123], "workflow_ids_remove": [123] }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}"

Example Response

{
  "app_url": "foo",
  "archived": true,
  "color": "#6515dd",
  "color_key": "black",
  "created_at": "2016-12-31T12:30:00Z",
  "default_workflow": {
    "entity_type": "workflow:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  },
  "description": "foo",
  "entity_type": "team",
  "id": "12345678-9012-3456-7890-123456789012",
  "members": {
    "current_items": 123,
    "entities": [{
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "mention_name": "foo",
  "name": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "uri": "foo",
  "workflows": {
    "current_items": 123,
    "entities": [{
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  }
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
team-public-id UUID	Required. The UUID of the Team.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Body Parameters

Name	Description
archived Boolean	Whether the Team is archived.
color Color or null	The hex color to be displayed with the Team (for example, “#ff0000”). Set to null to clear.
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 Team. Set to null to clear.
default_workflow_id Integer or null	The ID of the default Workflow for Stories created in this Team. Set to null to clear.
description String (4096)	The Team’s description.
member_ids Array [UUID]	An array of UUIDs for Members to set as the Team’s members. Replaces current members.
member_ids_add Array [UUID]	An array of UUIDs for Members to add to the Team.
member_ids_remove Array [UUID]	An array of UUIDs for Members to remove from the Team.
mention_name String	The Team’s mention name.
name String (63)	The Team’s name.
workflow_ids Array [Integer]	An array of IDs for Workflows to associate with the Team. Replaces current Workflows.
workflow_ids_add Array [Integer]	An array of IDs for Workflows to add to the Team.
workflow_ids_remove Array [Integer]	An array of IDs for Workflows to remove from the Team.

Responses

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

List Team Members

Returns a paginated list of all Members for the specified Team.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}/members

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}/members"

Example Response

[
  {
    "created_at": "2016-12-31T12:30:00Z",
    "disabled": true,
    "email_address": "foo",
    "entity_type": "member",
    "id": "12345678-9012-3456-7890-123456789012",
    "mention_name": "foo",
    "name": "foo",
    "role": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo"
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
team-public-id UUID	Required. The UUID of the Team.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_disabled, include_disabled)	Filter options (default: :exclude_disabled).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Team Stories

Returns a paginated list of all Stories assigned to the specified Team.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
team-public-id UUID	Required. The UUID of the Team.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Team Workflows

Returns a paginated list of all Workflows for the specified Team.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}/workflows

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/teams/{team-public-id}/workflows"

Example Response

[
  {
    "auto_assign_owner": true,
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    },
    "description": "foo",
    "entity_type": "workflow",
    "id": 123,
    "name": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_states": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow-state:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo",
        "workflow_name": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
team-public-id UUID	Required. The UUID of the Team.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Workflow-States

List Workflow States

Returns a paginated list of all Workflow States in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/workflow-states

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/workflow-states"

Example Response

[
  {
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "workflow-state",
    "id": 123,
    "name": "foo",
    "num_stories": 123,
    "num_story_templates": 123,
    "position": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (position)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Get Workflow State

Returns the specified Workflow State.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/workflow-states/{workflow-state-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/workflow-states/{workflow-state-public-id}"

Example Response

{
  "color": "foo",
  "created_at": "2016-12-31T12:30:00Z",
  "description": "foo",
  "entity_type": "workflow-state",
  "id": 123,
  "name": "foo",
  "num_stories": 123,
  "num_story_templates": 123,
  "position": 123,
  "type": "foo",
  "updated_at": "2016-12-31T12:30:00Z",
  "verb": "foo",
  "workflow": {
    "entity_type": "workflow:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo"
  }
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
workflow-state-public-id Integer	Required. The ID of the Workflow State.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Workflow State Stories

Returns a paginated list of all Stories in the specified Workflow State.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/workflow-states/{workflow-state-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/workflow-states/{workflow-state-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
workflow-state-public-id Integer	Required. The ID of the Workflow State.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Workflows

List Workflows

Returns a paginated list of all Workflows in the Workspace.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows"

Example Response

[
  {
    "auto_assign_owner": true,
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    },
    "description": "foo",
    "entity_type": "workflow",
    "id": 123,
    "name": "foo",
    "teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "workflow_states": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow-state:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo",
        "workflow_name": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

Get Workflow

Returns the specified Workflow.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}"

Example Response

{
  "auto_assign_owner": true,
  "created_at": "2016-12-31T12:30:00Z",
  "default_workflow_state": {
    "entity_type": "workflow-state:slim",
    "id": 123,
    "name": "foo",
    "uri": "foo",
    "workflow_name": "foo"
  },
  "description": "foo",
  "entity_type": "workflow",
  "id": 123,
  "name": "foo",
  "teams": {
    "current_items": 123,
    "entities": [{
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  },
  "updated_at": "2016-12-31T12:30:00Z",
  "workflow_states": {
    "current_items": 123,
    "entities": [{
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }],
    "list_url": "foo",
    "total_items": 123
  }
}

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
workflow-public-id Integer	Required. The ID of the Workflow.

URL Query Parameters

Name	Description
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Workflow Projects

Returns a paginated list of all Projects associated with the specified Workflow. Projects are a deprecated feature.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}/projects

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}/projects"

Example Response

[
  {
    "abbreviation": "foo",
    "app_url": "foo",
    "archived": true,
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "days_to_thermometer": 123,
    "description": "foo",
    "entity_type": "project",
    "external_id": "foo",
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iteration_length": 123,
    "name": "foo",
    "show_thermometer": true,
    "start_time": "2016-12-31T12:30:00Z",
    "stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
workflow-public-id Integer	Required. The ID of the Workflow.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Workflow States within a Workflow

Returns a paginated list of all Workflow States within the specified Workflow.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}/states

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}/states"

Example Response

[
  {
    "color": "foo",
    "created_at": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "workflow-state",
    "id": 123,
    "name": "foo",
    "num_stories": 123,
    "num_story_templates": 123,
    "position": 123,
    "type": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "verb": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
workflow-public-id Integer	Required. The ID of the Workflow.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (position)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (all)	Filter options (default: :all).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Workflow Stories

Returns a paginated list of all Stories associated with the specified Workflow.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}/stories

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}/stories"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "blocked": true,
    "blocker": true,
    "branches": {
      "current_items": 123,
      "entities": [{
        "entity_type": "branch:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "checklist_items": {
      "current_items": 123,
      "entities": [{
        "description": "foo",
        "entity_type": "checklist-item:slim",
        "id": 123,
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "comments": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "deleted": true,
        "entity_type": "comment:slim",
        "id": 123,
        "text": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "commits": {
      "current_items": 123,
      "entities": [{
        "entity_type": "commit:slim",
        "id": 123,
        "message": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 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_field_values": {
      "current_items": 123,
      "entities": [{
        "entity_type": "custom-field-value:slim",
        "field": {
          "entity_type": "custom-field:slim",
          "id": "12345678-9012-3456-7890-123456789012",
          "name": "foo",
          "uri": "foo"
        },
        "id": "12345678-9012-3456-7890-123456789012",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "deadline": "2016-12-31T12:30:00Z",
    "description": "foo",
    "entity_type": "story",
    "epic": {
      "app_url": "foo",
      "entity_type": "epic:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "estimate": 123,
    "external_id": "foo",
    "external_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "external-link",
        "value": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "followers": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "id": 123,
    "iterations": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "iteration:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "labels": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "label:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "linked_files": {
      "current_items": 123,
      "entities": [{
        "entity_type": "linked-file:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mentioned_teams": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "team:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "moved_at": "2016-12-31T12:30:00Z",
    "name": "foo",
    "owners": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "parent_story": {
      "app_url": "foo",
      "entity_type": "story:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "position": 123,
    "project": {
      "app_url": "foo",
      "entity_type": "project:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "pull_requests": {
      "current_items": 123,
      "entities": [{
        "entity_type": "pull-request:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "requester": {
      "entity_type": "member:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "started": true,
    "started_at": "2016-12-31T12:30:00Z",
    "started_at_override": "2016-12-31T12:30:00Z",
    "story_links": {
      "current_items": 123,
      "entities": [{
        "entity_type": "story-link:slim",
        "id": 123,
        "object": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "subject": {
          "app_url": "foo",
          "entity_type": "story:slim",
          "id": 123,
          "name": "foo",
          "uri": "foo"
        },
        "uri": "foo",
        "verb": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "story_template": {
      "entity_type": "story-template:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "story_type": "bug",
    "sub_task_stories": {
      "current_items": 123,
      "entities": [{
        "app_url": "foo",
        "entity_type": "story:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "team": {
      "app_url": "foo",
      "entity_type": "team:slim",
      "id": "12345678-9012-3456-7890-123456789012",
      "name": "foo",
      "uri": "foo"
    },
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "workflow_state": {
      "entity_type": "workflow-state:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo",
      "workflow_name": "foo"
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
workflow-public-id Integer	Required. The ID of the Workflow.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (created_at, position, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

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

List Workflow Teams

Returns a paginated list of all Teams associated with the specified Workflow.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}/teams

Example Request

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/workflows/{workflow-public-id}/teams"

Example Response

[
  {
    "app_url": "foo",
    "archived": true,
    "color": "#6515dd",
    "color_key": "black",
    "created_at": "2016-12-31T12:30:00Z",
    "default_workflow": {
      "entity_type": "workflow:slim",
      "id": 123,
      "name": "foo",
      "uri": "foo"
    },
    "description": "foo",
    "entity_type": "team",
    "id": "12345678-9012-3456-7890-123456789012",
    "members": {
      "current_items": 123,
      "entities": [{
        "entity_type": "member:slim",
        "id": "12345678-9012-3456-7890-123456789012",
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    },
    "mention_name": "foo",
    "name": "foo",
    "updated_at": "2016-12-31T12:30:00Z",
    "uri": "foo",
    "workflows": {
      "current_items": 123,
      "entities": [{
        "entity_type": "workflow:slim",
        "id": 123,
        "name": "foo",
        "uri": "foo"
      }],
      "list_url": "foo",
      "total_items": 123
    }
  }
]

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
workflow-public-id Integer	Required. The ID of the Workflow.

URL Query Parameters

Name	Description
limit Integer	The number of results to include in a page. Can be between 1 and 100. Defaults to 10.
cursor String	The cursor indicating where we are in a paged response. If sent, it (and an optional `fields` parameter) must be the only parameters.
order_by Enum (name, updated_at)	Order the results by this property and direction.
order_dir Enum (asc, desc)	Order order_by in this direction. If order_by not provided, the default order property for this entity type will be used.
filter Enum (exclude_archived, include_archived)	Filter options (default: :exclude_archived).
fields String	Fields to include in the response, as a comma-separated string. If provided, only these fields will be included for each entity in the response. If not present, all fields will be returned.

Responses

Code	Description
200	[ Team, … ]
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.

Branch

The entity for this response.

Name	Description
created_at Date	The time/date the Branch was created.
deleted Boolean	Boolean indicating whether the Branch has been deleted.
entity_type Enum (branch)	The type of this entity.
external_url String	The URL of the Branch in the VCS provider.
id Integer	The unique ID of the Branch.
name String	The name of the Branch.
pull_requests NestedPullRequestSlimList	A list of Pull/Merge Requests attached to the Story.
repository RepositorySlim	The Repository that contains the Commit.
stories NestedStorySlimList	A list of Stories associated with this Project.
updated_at Date	The time/date the Branch was last updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

BranchEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Branch]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

BranchEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Branch	The entity for this response.

BranchPullRequestEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [PullRequest]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

BranchSlim

Name	Description
entity_type Enum (branch:slim)	The type of this entity.
id Integer	The unique ID of the Branch.
name String	The name of the Branch.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

BranchStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

BulkUpdateCategoriesParams1

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”).
id Integer	The id of the Category to update.
name String (128)	The name of the Category.

BulkUpdateCustomFieldsParams1

Name	Description
after_id UUID	Move this Custom Field to after the field with this ID.
before_id UUID	Move this Custom Field to before the field with this ID.
description String (1024)	A description of the Custom Field.
enabled Boolean	Whether the Custom Field is enabled.
icon_set_identifier String (63)	An identifier for the icon set for this Custom Field.
id UUID	The unique ID of the Custom Field to update.
name String (63)	The name of the Custom Field.
values Array [UpdateCustomFieldEnumValueParams]	The ordered list of enum values. Existing values not included will be deleted.
values_add Array [UpdateCustomFieldEnumValueParams]	Enum values to add to the Custom Field. Existing values are unchanged.
values_remove Array [UUID]	IDs of enum values to remove from the Custom Field.

BulkUpdateEntityTemplatesParams1

Name	Description
id UUID	The UUID of the Entity Template to update.
name String (128)	The updated template name.
story_contents UpdateEntityTemplateStoryContentsParams	Updated attributes for the template to populate.

BulkUpdateEpicCommentsParams1

Name	Description
id Integer	The id of the Comment to update.
text String (100000)	The comment text.

BulkUpdateEpicsParams1

Name	Description
archived Boolean	Whether the Epic is archived.
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)	An external ID for the Epic.
follower_ids Array [UUID]	An array of UUIDs for Members to set as Followers. This will replace the current Followers on the Epic. Sending an empty array will delete all existing Followers.
follower_ids_add Array [UUID]	An array of UUIDs for Members to add as Followers. These will be added to the current Followers on the Epic.
follower_ids_remove Array [UUID]	An array of UUIDs for Members to remove as Followers. These will be removed from the current Followers on the Epic.
id Integer	The id of the Epic to update.
name String (256)	The Epic’s name.
objective_ids Array [Integer]	An array of IDs for Objectives to which this Epic is related. This will replace the current Objectives on the Epic. Sending an empty array will remove all existing Objectives.
objective_ids_add Array [Integer]	An array of IDs for Objectives to add to the Epic. These will be added to the current Objectives on the Epic.
objective_ids_remove Array [Integer]	An array of IDs for Objectives to remove from the Epic. These will be removed from the current Objectives on the Epic.
owner_ids Array [UUID]	An array of UUIDs for Members to set as Owners. This will replace the current Owners on the Epic. Sending an empty array will delete all existing Owners.
owner_ids_add Array [UUID]	An array of UUIDs for Members to add as Owners. These will be added to the current Owners on the Epic.
owner_ids_remove Array [UUID]	An array of UUIDs for Members to remove as Owners. These will be removed from the current Owners on the Epic.
planned_start_date Date or null	The Epic’s planned start date.
requested_by_id UUID	The UUID of the Member that requested the Epic.
started_at_override Date or null	A manual override for the time/date the Epic was started.
team_ids Array [UUID]	An array of UUIDs for Teams to associate with the Epic. This will replace the current Teams on the Epic. Sending an empty array will remove all existing Teams.
team_ids_add Array [UUID]	An array of UUIDs for Teams to add to the Epic. These will be added to the current Teams on the Epic.
team_ids_remove Array [UUID]	An array of UUIDs for Teams to remove from the Epic. These will be removed from the current Teams on the Epic.

BulkUpdateIterationsParams1

Name	Description
description String (100000)	The description of the Iteration.
end_date String	The date this Iteration ends (ISO 8601 date format, e.g. ‘2024-01-15’).
follower_ids Array [UUID]	An array of UUIDs for any Members you want to set as Followers, replacing existing Followers.
follower_ids_add Array [UUID]	An array of UUIDs for any Members you want to add as Followers.
follower_ids_remove Array [UUID]	An array of UUIDs for any Members you want to remove as Followers.
id Integer	The id of the Iteration to update.
name String (256)	The name of this Iteration.
start_date String	The date this Iteration begins (ISO 8601 date format, e.g. ‘2024-01-01’).
team_ids Array [UUID]	An array of UUIDs for any Teams you want to set on the Iteration, replacing existing Teams.
team_ids_add Array [UUID]	An array of UUIDs for any Teams you want to add to the Iteration.
team_ids_remove Array [UUID]	An array of UUIDs for any Teams you want to remove from the Iteration.

BulkUpdateLabelsParams1

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 description of the Label.
id Integer	The id of the Label to update.
name String (128)	The name of the Label.

BulkUpdateLinkedFilesParams1

Name	Description
description String (512)	The description of the Linked File.
id Integer	The id of the Linked File to update.
name String (256)	The name of the Linked File.
thumbnail_url String (2048)	The URL of the thumbnail.
type String (63)	The integration type (e.g. google, dropbox, box, onedrive, url).
url String (2048)	The URL of the Linked File.

BulkUpdateMembersParams1

Name	Description
disabled Boolean	Set to true to disable the Member, false to re-enable them.
id UUID	The unique ID of the Member to update.
role Enum (admin, member, observer)	The new role to assign to the Member. One of “admin”, “member”, or “observer”.

BulkUpdateObjectivesParams1

Name	Description
archived Boolean	Whether the Objective is archived.
category_ids Array [Integer]	An array of IDs of Categories to set on the Objective. Replaces current Categories.
category_ids_add Array [Integer]	An array of IDs of Categories to add to the Objective.
category_ids_remove Array [Integer]	An array of IDs of Categories to remove from 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.
id Integer	The id of the Objective to update.
name String (256)	The name of the Objective.
owner_ids Array [UUID]	An array of UUIDs for Members to set as Owners. This will replace the current Owners on the Objective. Sending an empty array will delete all existing Owners.
owner_ids_add Array [UUID]	An array of UUIDs for Members to add as Owners. These will be added to the current Owners on the Objective.
owner_ids_remove Array [UUID]	An array of UUIDs for Members to remove as Owners. These will be removed from the current Owners on 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 of the Objective.
team_ids Array [UUID]	An array of UUIDs for Teams to associate with the Objective. This will replace the current Teams on the Objective. Sending an empty array will remove all existing Teams.
team_ids_add Array [UUID]	An array of UUIDs for Teams to add to the Objective. These will be added to the current Teams on the Objective.
team_ids_remove Array [UUID]	An array of UUIDs for Teams to remove from the Objective. These will be removed from the current Teams on the Objective.

BulkUpdateStoriesParams1

Name	Description
archived Boolean	Controls the Story’s archived state.
custom_field_values Array [CreateCustomFieldValueParams]	An array of objects specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a Custom Field. This will replace the current Custom Field values on the Story. Sending an empty array will delete all existing Custom Field values.
custom_field_values_add Array [CreateCustomFieldValueParams]	An array of objects specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a Custom Field. These will be added to the current Custom Field values on the Story.
custom_field_values_remove Array [CreateCustomFieldValueParams]	An array of objects specifying a CustomField ID and CustomFieldEnumValue ID that represents an assertion of some value for a Custom Field. These will be removed from the current Custom Field values on the Story.
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 (128)	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 the Story. This will replace the current External Links on the Story. Sending an empty array will delete all existing External Links.
external_links_add Array [String]	An array of External Links associated with the Story. These will be added to the current External Links on the Story.
external_links_remove Array [String]	An array of External Links associated with the Story. These will be removed from the current External Links on the Story.
file_ids Array [Integer]	An array of IDs of Files attached to the Story. This will replace the current Files on the Story. Sending an empty array will delete all existing Files.
file_ids_add Array [Integer]	An array of IDs of Files attached to the Story. These will be added to the current files on the Story.
file_ids_remove Array [Integer]	An array of IDs of Files attached to the Story. These will be added to the current files on the Story.
follower_ids Array [UUID]	An array of UUIDs of the Members that follow this Story. This will replace the current Followers on the Story. Sending an empty array will delete all existing Followers.
follower_ids_add Array [UUID]	An array of UUIDs of the Members that follow this Story. These will be added to the current followers on the Story.
follower_ids_remove Array [UUID]	An array of UUIDs of the Members that follow this Story. These will be removed from the current followers on the Story.
id Integer	The id of the Story to update.
iteration_id Integer or null	The ID of the Iteration the Story belongs to.
label_ids Array [Integer]	Labels to attach to the Story. This will replace the current Labels on the Story. Sending an empty array will delete all existing Labels.
label_ids_add Array [Integer]	Labels to attach to the Story. These will be added to the current Labels on the Story.
label_ids_remove Array [Integer]	Labels to detach from the Story. These will be removed to the current Labels on the Story.
linked_file_ids Array [Integer]	An array of IDs of Linked Files attached to the Story. This will replace the current Linked Files on the Story. Sending an empty array will delete all existing Linked Files.
linked_file_ids_add Array [Integer]	An array of IDs of Linked Files attached to the Story. These will be added to the current files on the Story.
linked_file_ids_remove Array [Integer]	An array of IDs of Linked Files attached to the Story. These will be added to the current files on the Story.
name String (512)	The name of the Story.
owner_ids Array [UUID]	An array of UUIDs of the Members that own this Story. This will replace the current Owners on the Story. Sending an empty array will delete all existing Owners.
owner_ids_add Array [UUID]	An array of UUIDs of the Members that own this Story. These will be added to the current owners on the Story.
owner_ids_remove Array [UUID]	An array of UUIDs of the Members that own this Story. These will be removed from the current owners on the Story.
parent_story_id Integer or null	The ID of the parent Story to associate with this Story (making the Story a sub-task). Field only applicable when Sub-task feature is enabled.
project_id Integer or null	The ID of the Project the Story belongs to.
requester_id UUID	The ID of the Member that requested the Story. Will default to the Member making the API call if not provided.
set_position Body5196914StoriesSetPosition	One of “first”, “last”, “before”, or “after”. This can be used to move the given story to the first or last position in the Workflow State, or before or after a given Story.
story_type Enum (bug, chore, feature)	The type of Story (feature, bug, chore).
team_id UUID or null	The id of the Team to associate with this Story.
workflow_state_id Integer	The ID of the Workflow State to move the Story to.

BulkUpdateStoryChecklistItemsParams1

Name	Description
completed Boolean	True/false boolean indicating whether the Checklist Item is completed. Defaults to false.
description String (2048)	The Checklist Item description.
id Integer	The id of the Checklist Item to update.
set_position Body5196828ChecklistItemsSetPosition	One of “first”, “last”, “before”, or “after”. This can be used to move the Checklist Item to the first or last position in the Story’s checklist, or before or after a given Checklist Item.

BulkUpdateStoryCommentsParams1

Name	Description
id Integer	The id of the Comment to update.
text String (100000)	The comment text.

BulkUpdateTeamsParams1

Name	Description
archived Boolean	Whether the Team is archived.
color Color or null	The hex color to be displayed with the Team (for example, “#ff0000”). Set to null to clear.
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 Team. Set to null to clear.
default_workflow_id Integer or null	The ID of the default Workflow for Stories created in this Team. Set to null to clear.
description String (4096)	The Team’s description.
id UUID	The UUID of the Team to update.
member_ids Array [UUID]	An array of UUIDs for Members to set as the Team’s members. Replaces current members.
member_ids_add Array [UUID]	An array of UUIDs for Members to add to the Team.
member_ids_remove Array [UUID]	An array of UUIDs for Members to remove from the Team.
mention_name String	The Team’s mention name.
name String (63)	The Team’s name.
workflow_ids Array [Integer]	An array of IDs for Workflows to associate with the Team. Replaces current Workflows.
workflow_ids_add Array [Integer]	An array of IDs for Workflows to add to the Team.
workflow_ids_remove Array [Integer]	An array of IDs for Workflows to remove from the Team.

CategoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Category]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

CategoryEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Category

CategoryObjectiveEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [ObjectiveSlim]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

CategorySlim

Name	Description
entity_type Enum (category:slim)	The type of this entity.
id Integer	The unique ID of the Category.
name String (128)	The name of the Category.
uri String (2048)	A resolvable URI for the entity.

ChecklistItem

Name	Description
completed Boolean	Boolean indicating whether the Checklist Item has been completed.
completed_at Date or null	The time/date the Checklist Item was completed.
created_at Date	The time/date the Checklist Item was created.
description String	The description of the Checklist Item.
entity_type Enum (checklist-item)	The type of this entity.
external_id String or null	This field can be set to another unique ID. In the case that the Checklist Item has been imported from another tool, the ID in the other tool can be indicated here.
id Integer	The unique ID of the Checklist Item.
mentioned_members NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
mentioned_teams NestedTeamSlimList	A list of Teams that this Member belongs to.
position Integer	The Comment’s position within the Story.
story StorySlim	The Story this Checklist Item belongs to.
updated_at Date or null	The time/date the Checklist Item was updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

ChecklistItemSlim

Name	Description
description String	The description of the Checklist Item.
entity_type Enum (checklist-item:slim)	The type of this entity.
id Integer	The unique ID of the Checklist Item.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

Comment

Name	Description
app_url String (2048) or null	The Shortcut application url for the Comment. Will be null if the comment is deleted.
author MemberSlim
created_at Date	The time/date the Comment was created.
deleted Boolean	True if the comment has been deleted.
entity_type Enum (comment)	The type of this entity.
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.
id Integer or null	The unique ID of the Comment. Will be null if the comment is deleted.
mentioned_members NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
mentioned_teams NestedTeamSlimList	A list of Teams that this Member belongs to.
parent_comment CommentSlim or null
position Integer	The Comment’s position within the Story.
reactions NestedReactionSlimList	A list of Reactions to this Comment.
story StorySlim	The Story this Checklist Item belongs to.
text String or null	The text of the Comment. Will be null if the comment is deleted.
updated_at Date	The time/date the Comment was last updated.
uri String (2048) or null	A resolvable URI for the entity that will return the full representation. Will be null if the comment is deleted.

CommentSlim

Name	Description
app_url String (2048) or null	The Shortcut application url for the Comment. Will be null if the comment is deleted.
deleted Boolean	True if the comment has been deleted.
entity_type Enum (comment:slim)	The type of this entity.
id Integer or null	The unique ID of the Comment. Will be null if the comment is deleted.
text String or null	The text of the Comment. Will be null if the comment is deleted.
uri String (2048) or null	A resolvable URI for the entity that will return the full representation. Will be null if the comment is deleted.

Commit

Name	Description
author MemberSlim or null
created_at Date	The time/date the Commit was created.
entity_type Enum (commit)	The type of this entity.
external_url String	The URL of the Commit in the VCS provider.
hash String	The Commit hash.
id Integer	The unique ID of the Commit.
message String	The Commit message, truncated to the first line (up to 1024 characters).
repository RepositorySlim	The Repository that contains the Commit.
stories NestedStorySlimList	A list of Stories associated with this Project.
timestamp Date	The time/date the Commit was pushed.
updated_at Date or null	The time/date the Commit was updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

CommitEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Commit]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

CommitEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Commit

CommitSlim

Name	Description
entity_type Enum (commit:slim)	The type of this entity.
id Integer	The unique ID of the Commit.
message String	The message of the Commit.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

CommitStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

CreateCategoryParams

Name	Description
color Color	The hex color to be displayed with the Category (for example, “#ff0000”).
external_id String (128)	An optional external ID for the Category.
name String (128)	The name of the new Category.

CreateCustomFieldValueParams

Name	Description
field_id UUID	The unique public ID for the Custom Field value.
value_id UUID	The unique public ID for the CustomFieldEnumValue.

CreateDocParams

Name	Description
content String	The content of the new Doc.
content_format Enum (html, markdown)	Format of the content being sent. Defaults to ‘html’. If ‘markdown’, content will be converted to HTML for storage.
description String (1024)	An optional description for the Doc.
title String (256)	The title of the new Doc.

CreateEntityTemplateParams

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

CreateEntityTemplateStoryContentsParams

A map of story attributes this template populates.

Name	Description
custom_fields Array [CreateCustomFieldValueParams]	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 (512)	The description of the story.
epic_id Integer or null	The ID of the epic 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 you want to add 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 to be populated.
label_ids Array [Integer]	An array of IDs for 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 for any Members you want to add as Owners.
story_type Enum (bug, chore, feature)	The type of story (feature, bug, chore).
sub_tasks Array [CreateEntityTemplateSubTaskParams]	An array of sub-tasks to be populated by the template.
tasks Array [CreateEntityTemplateTaskParams]	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.

CreateEntityTemplateSubTaskParams

Name	Description
name String (512)	The name of the Sub-Task.
owner_ids Array [UUID]	An array of UUIDs of the owners of this Sub-Task.
workflow_state_id Integer	The ID of the workflow state the Sub-Task is in.

CreateEntityTemplateTaskParams

Name	Description
complete Boolean	True/false boolean indicating whether the Task is completed. Defaults to false.
description String (2048)	The Task description.
owner_ids Array [UUID]	An array of UUIDs for any members you want to add as Owners on this new Task.

CreateEpicCommentParams

Name	Description
author_id UUID	The Member ID of the Comment’s author. Defaults to the user identified by the API token. Requires the admin role to set.
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.
parent_comment_id Integer	The ID of the Comment to reply to. When provided, creates a threaded reply rather than a top-level Comment.
text String (100000)	The comment text.

CreateEpicParams

Name	Description
completed_at_override Date	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)	An external ID for the Epic.
follower_ids Array [UUID]	An array of UUIDs for Members to add as Followers.
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 Members to add as Owners.
planned_start_date Date or null	The Epic’s planned start date.
requested_by_id UUID	The UUID of the Member that requested the Epic.
started_at_override Date	A manual override for the time/date the Epic was started.
team_ids Array [UUID]	An array of UUIDs for Teams to associate with the Epic.

CreateIterationParams

Name	Description
description String (100000)	The description of the Iteration.
end_date String	The date this Iteration ends (ISO 8601 date format, e.g. ‘2024-01-15’).
follower_ids Array [UUID]	An array of UUIDs for any Members you want to add as Followers.
name String (256)	The name of this Iteration.
start_date String	The date this Iteration begins (ISO 8601 date format, e.g. ‘2024-01-01’).
team_ids Array [UUID]	An array of UUIDs for any Teams you want to associate with the Iteration.

CreateLabelParams

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.

CreateLinkedFileParams

Name	Description
content_type String (128)	The content type of the Linked File.
description String (512)	The description of the Linked File.
name String (256)	The name of the Linked File.
size Integer	The size of the Linked File.
thumbnail_url String (2048)	The URL of the thumbnail.
type String (63)	The integration type (e.g. google, dropbox, box, onedrive, url).
url String (2048)	The URL of the Linked File.

CreateNestedStoryLinkParams

Name	Description
object_story_id Integer	The unique ID of the Story defined as object. At least one of `object_story_id` or `subject_story_id` must be present.
subject_story_id Integer	The unique ID of the Story defined as subject. At least one of `object_story_id` or `subject_story_id` must be present.
verb Enum (blocks, duplicates, relates to)	How the subject Story acts on the object Story. This can be one of: “blocks”, “duplicates”, “relates to”

CreateObjectiveParams

Name	Description
category_ids Array [Integer]	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.
owner_ids Array [UUID]	An array of UUIDs for Members to add as Owners.
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 of the Objective.
team_ids Array [UUID]	An array of UUIDs for Teams to associate with the Objective.

CreateStoryChecklistItemParams

Request parameters for creating a Checklist Item on a Story.

Name	Description
completed Boolean	True/false boolean indicating whether the Checklist Item is completed. Defaults to false.
description String (2048)	The Checklist Item description.
external_id String (128)	This field can be set to another unique ID. In the case that the Checklist Item has been imported from another tool, the ID in the other tool can be indicated here.
set_position Body5196829ChecklistItemsSetPosition	One of “first”, “last”, “before”, or “after”. This can be used to move the Checklist Item to the first or last position in the Story’s checklist, or before or after a given Checklist Item.

CreateStoryCommentParams

Name	Description
author_id UUID	The Member ID of the Comment’s author. Defaults to the user identified by the API token. Requires the admin role to set.
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.
parent_comment_id Integer	The ID of the Comment that this comment is threaded under.
text String (100000)	The comment text.

CreateStoryLinkParams

Name	Description
object_story_id Integer	The unique ID of the Story defined as object.
subject_story_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 one of: “blocks”, “duplicates”, “relates to”

CreateStoryParams

Name	Description
archived Boolean	Controls the Story’s archived state.
checklist_items Array [CreateStoryChecklistItemParams]	An array of Checklist Items connected to the Story.
custom_field_values Array [CreateCustomFieldValueParams]	An array of objects specifying a Custom Field value ID and CustomFieldEnumValue ID that represents an assertion of some value for a Custom Field value.
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 (128)	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 the 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 Members that follow this Story.
iteration_id Integer or null	The ID of the Iteration the Story belongs to.
label_ids Array [Integer]	Labels to attach to the Story.
linked_file_ids Array [Integer]	An array of IDs of Linked Files attached to the Story.
name String (512)	The name of the Story.
owner_ids Array [UUID]	An array of UUIDs of the Members that own this Story.
parent_story_id Integer or null	The ID of the parent Story to associate with this Story (making the Story a sub-task). Field only applicable when Sub-task feature is enabled.
project_id Integer or null	The ID of the Project the Story belongs to.
requester_id UUID	The ID of the Member that requested the Story. Will default to the Member making the API call if not provided.
set_position Body5196915StoriesSetPosition	One of “first”, “last”, “before”, or “after”. This can be used to move the given story to the first or last position in the Workflow State, or before or after a given Story.
story_links Array [CreateNestedStoryLinkParams]	An array of Story links attached to the Story.
story_type Enum (bug, chore, feature)	The type of Story (feature, bug, chore).
team_id UUID or null	The id of the Team to associate with this Story.
workflow_state_id Integer	The ID of the Workflow State the Story will be in.

CreateTeamParams

Name	Description
color Color	The hex color to be displayed with the Team (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)	The color key to be displayed with the Team.
default_workflow_id Integer	The ID of the default Workflow for Stories created in this Team.
description String (4096)	The Team’s description.
member_ids Array [UUID]	An array of UUIDs for Members to add to the Team.
mention_name String	The Team’s mention name.
name String (63)	The Team’s name.
workflow_ids Array [Integer]	An array of IDs for Workflows to associate with the Team. At least one Workflow is required.

CurrentIterationsOutput

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Iteration]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

CustomField

The entity for this response.

Name	Description
canonical_name String or null	The canonical name of a Shortcut-defined Custom Field.
created_at Date	The time/date the Custom Field was created.
description String (1024) or null	A description of the Custom Field.
enabled Boolean	Whether the Custom Field is enabled for the Workspace.
entity_type Enum (custom-field)	The type of this entity.
field_type String	The type of the Custom Field (e.g. “enum”).
fixed_position Boolean	Whether this Custom Field has a fixed position.
icon_set_identifier String (63) or null	An identifier for the icon set used for this Custom Field.
id UUID	The unique public ID for the Custom Field.
name String (63)	The name of the Custom Field.
position Integer or null	The display position of the Custom Field.
story_types Array [Enum (bug, chore, feature)] or null	The story types this Custom Field applies to, if restricted.
updated_at Date	The time/date the Custom Field was last updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.
values Array [CustomFieldValue] or null	The ordered list of enum values for this Custom Field.

CustomFieldEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [CustomField]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

CustomFieldEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity CustomField	The entity for this response.

CustomFieldSlim

The Custom Field for this value.

Name	Description
entity_type Enum (custom-field:slim)	The type of this entity.
id UUID	The unique public ID for the Custom Field.
name String	The name of the Custom Field.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

CustomFieldStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

CustomFieldValue

Name	Description
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 associated with this enum value.
enabled Boolean	Whether this enum value is enabled.
entity_type Enum (custom-field-value)	The type of this entity.
field CustomFieldSlim	The Custom Field for this value.
id UUID	The unique public ID for the enum value.
position Integer	The position of this enum value in the ordered list.
value String (63)	The string value for this enum value.

CustomFieldValueSlim

Name	Description
entity_type Enum (custom-field-value:slim)	The type of this entity.
field CustomFieldSlim	The Custom Field for this value.
id UUID	The unique public ID for the Custom Field Value.
value String	A string representation of the value.

DisabledFeatureError

Name	Description
feature_tag String	The feature that is disabled.
message String	The message explaining the error.

Doc

The entity for this response.

Name	Description
archived Boolean	A true/false boolean indicating if the Doc has been archived.
content_html String or null	The Doc content in HTML format. Only present on get-doc when content_format=html.
content_markdown String or null	The Doc content in Markdown format. Only present on get-doc when content_format is omitted or ‘markdown’.
created_at Date	The time/date the Doc was created.
creator MemberSlim
entity_type Enum (doc)	The type of this entity.
followers NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
id UUID	The unique ID of the Doc.
title String (256)	The title of the Doc.
updated_at Date	The time/date the Doc was last updated.
uri String (2048)	A resolvable URI for the entity.

DocEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Doc]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

DocEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Doc	The entity for this response.

DocFollowerEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EntityTemplate

The entity for this response.

Name	Description
author MemberSlim
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 EntityTemplateStoryContents	A container entity for the attributes this template should populate.
updated_at Date	The time/date when the entity template was last updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

EntityTemplateEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [EntityTemplate]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EntityTemplateEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity EntityTemplate	The entity for this response.

EntityTemplateStoryContents

A container entity for the attributes this template should populate.

Name	Description
custom_fields Array [CreateCustomFieldValueParams]	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 or null	The description of the story.
entity_type String	A string description of this resource.
epic EpicSlim	The Epic the story belongs to.
estimate Integer	The numeric point estimate of the story.
external_links Array [String]	An array of external links connected to the story.
files Array [FileSlim]	An array of files attached to the story.
followers Array [MemberSlim]	An array of Members listed as Followers.
iteration IterationSlim	The Iteration the story belongs to.
labels Array [LabelSlim]	An array of labels attached to the story.
linked_files Array [LinkedFileSlim]	An array of linked files attached to the story.
name String	The name of the story.
owners Array [MemberSlim]	An array of Members who own the story.
project ProjectSlim	The Project the story belongs to.
story_type String	The type of story (feature, bug, chore).
sub_tasks Array [EntityTemplateSubTask]	An array of sub-tasks connected to the story.
tasks Array [EntityTemplateTask]	An array of tasks connected to the story.
team TeamSlim
workflow_state WorkflowStateSlim	The default Workflow State of the Workspace’s default Workflow.

EntityTemplateSubTask

Name	Description
name String	The name of the Sub-Task.
owners Array [MemberSlim]	An array of Members who own this Sub-Task.
position Integer	The position of the Sub-Task within the list.
workflow_state WorkflowStateSlim	The default Workflow State of the Workspace’s default Workflow.

EntityTemplateTask

Name	Description
complete Boolean	True/false boolean indicating whether the Task has been completed.
description String	Full text of the Task.
owners Array [MemberSlim]	An array of Members who own this Task.
position Integer	The number corresponding to the Task’s position within a list of Tasks on a Story.

Epic

Name	Description
app_url String (2048)	The Shortcut application url for the Epic.
archived Boolean	Whether the Epic is archived.
comments NestedThreadedCommentSlimList	The Comments on the Epic.
completed Boolean	Whether the Epic is 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	The time/date the Epic was created.
deadline Date or null	The Epic’s deadline.
description String	The Epic’s description.
entity_type Enum (epic)	The type of this entity.
epic_state EpicStateSlim	The current Epic State.
external_id String or null	An external ID that can be used to identify the Epic.
followers NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
healths NestedHealthSlimList	The Health updates on the Objective.
id Integer	The unique ID of the Epic.
labels NestedLabelSlimList	A list of labels attached to the Story.
mentioned_members NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
mentioned_teams NestedTeamSlimList	A list of Teams that this Member belongs to.
name String	The name of the Epic.
objectives NestedObjectiveSlimList	The Objectives associated with this Epic.
owners NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
planned_start_date Date or null	The Epic’s planned start date.
requester MemberSlim or null
started Boolean	Whether 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.
stories NestedStorySlimList	A list of Stories associated with this Project.
teams NestedTeamSlimList	A list of Teams that this Member belongs to.
updated_at Date	The time/date the Epic was last updated.
uri String (2048)	A resolvable URI for the entity.

EpicCommentCommentEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [ThreadedComment]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicCommentEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [ThreadedComment]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicCommentEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity ThreadedComment	The entity for this response.

EpicCommentMentionedMemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicCommentMentionedTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Epic]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Epic

EpicFollowerEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicLabelEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Label]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicMentionedMemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicMentionedTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicObjectiveEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [ObjectiveSlim]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicOwnerEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicSlim

The Epic the story belongs to.

Name	Description
app_url String (2048)	The Shortcut application url for the Epic.
entity_type Enum (epic:slim)	The type of this entity.
id Integer	The unique ID of the Epic.
name String	The name of the Epic.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

EpicState

Name	Description
color String or null	The color of the Epic State.
created_at Date	The time/date the Epic State was created.
description String	The description of the Epic State.
entity_type Enum (epic-state)	The type of this entity.
id Integer	The unique ID of the Epic State.
name String	The name of the Epic State.
position Integer	The position of the Epic State.
type String	The type of the Epic State (unstarted, started, done).
updated_at Date	The time/date the Epic State was last updated.

EpicStateEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [EpicState]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicStateSlim

The current Epic State.

Name	Description
entity_type Enum (epic-state:slim)	The type of this entity.
id Integer	The unique ID of the Epic State.
name String	The name of the Epic State.
type String	The type of the Epic State (unstarted, started, done).

EpicStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

EpicWorkflow

The entity for this response.

Name	Description
created_at Date	The time/date the Epic Workflow was created.
default_epic_state EpicStateSlim	The current Epic State.
entity_type Enum (epic-workflow)	The type of this entity.
epic_states NestedEpicStateList	A list of Epic States in the Epic Workflow.
id Integer	The unique ID of the Epic Workflow.
updated_at Date	The time/date the Epic Workflow was last updated.

EpicWorkflowEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity EpicWorkflow	The entity for this response.

ExternalLink

Name	Description
entity_type Enum (external-link)	The type of this entity.
value String (2048)	The URL of the external link.

File

Name	Description
content_type String	The content type of the File.
created_at Date	The time/date the File was created.
description String	The description of the File.
entity_type Enum (file)	The type of this entity.
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.
id Integer	The unique ID for the File.
mentioned_members NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
mentioned_teams NestedTeamSlimList	A list of Teams that this Member belongs to.
name String	The name of the File.
size Integer	The size of the File in bytes.
stories NestedStorySlimList	A list of Stories associated with this Project.
thumbnail_url String (2048) or null	The URL of the thumbnail for the File.
updated_at Date	The time/date the File was last updated.
uploader MemberSlim
uri String (2048)	A resolvable URI for the entity that will return the full representation.
url String (2048)	The URL for the File.

FileEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [File]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

FileEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity File

FileMentionedMemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

FileMentionedTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

FileSlim

Name	Description
entity_type Enum (file:slim)	The type of this entity.
id Integer	The unique ID for the file.
name String	The name of the file.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

FileStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

Health

Name	Description
author MemberSlim
created_at Date	The time/date the Health was created.
entity_type Enum (health)	The type of this entity.
epic EpicSlim or null	The Epic the story belongs to.
id UUID	The unique ID of the Health.
objective ObjectiveSlim or null
status Enum (At Risk, No Health, Off Track, On Track)	The status of the Health.
text String or null	The text body of the Health update.
updated_at Date	The time/date the Health was last updated.

HealthEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Health]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

HealthEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Health

HealthSlim

Name	Description
created_at Date	The time/date the Health was created.
entity_type Enum (health:slim)	The type of this entity.
id UUID	The unique ID of the Health.
status String	The status of the Health (On Track, At Risk, Off Track, No Health).
updated_at Date	The time/date the Health was last updated.

Iteration

Name	Description
app_url String (2048)	The Shortcut application url for the Iteration.
associated_teams NestedTeamSlimList	A list of Teams that this Member belongs to.
created_at Date	The time/date the Iteration was created.
description String or null	The description of the Iteration.
end_date String	The end date of the Iteration (ISO 8601 date format, e.g. ‘2024-01-15’).
entity_type Enum (iteration)	The type of this entity.
followers NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
id Integer	The unique ID of the Iteration.
labels NestedLabelSlimList	A list of labels attached to the Story.
mentioned_members NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
mentioned_teams NestedTeamSlimList	A list of Teams that this Member belongs to.
name String	The name of the Iteration.
start_date String	The start date of the Iteration (ISO 8601 date format, e.g. ‘2024-01-01’).
stories NestedStorySlimList	A list of Stories associated with this Project.
teams NestedTeamSlimList	A list of Teams that this Member belongs to.
updated_at Date	The time/date the Iteration was last updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

IterationAssociatedTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

IterationEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Iteration]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

IterationEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Iteration

IterationFollowerEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

IterationLabelEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Label]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

IterationMentionedMemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

IterationMentionedTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

IterationSlim

The Iteration the story belongs to.

Name	Description
app_url String (2048)	The Shortcut application url for the Iteration.
entity_type Enum (iteration:slim)	The type of this entity.
id Integer	The unique ID of the Iteration.
name String	The name of the Iteration.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

IterationStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

IterationTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

KeyResult

Name	Description
created_at Date	The time/date the Key Result was created.
current_observed_value KeyResultValue	The starting observed value of the Key Result.
current_target_value KeyResultValue	The starting observed value of the Key Result.
entity_type Enum (key-result)	The type of this entity.
id UUID	The unique ID of the Key Result.
initial_observed_value KeyResultValue	The starting observed value of the Key Result.
name String (1024)	The name of the Key Result.
objective ObjectiveSlim
progress Integer	A percentage (0-100) indicating progress toward the target value.
type Enum (boolean, numeric, percent)	The type of this Key Result’s values.
updated_at Date	The time/date the Key Result was last updated.
uri String (2048)	A resolvable URI for the Key Result.

KeyResultEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [KeyResult]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

KeyResultEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity KeyResult

KeyResultSlim

Name	Description
entity_type Enum (key-result:slim)	The type of this entity.
id UUID	The unique ID of the Key Result.
name String (1024)	The name of the Key Result.
uri String (2048)	A resolvable URI for the entity.

KeyResultValue

The starting observed value of the Key Result.

Name	Description
boolean_value Boolean	The boolean value. Present for boolean key results.
created_at Date	The time/date this value was created.
creator MemberSlim
numeric_value String	The numeric value as a decimal string. Present for numeric and percent key results.

Label

Name	Description
app_url String (2048)	The Shortcut application url for the Label.
archived Boolean	A true/false boolean indicating if the Label has been archived.
color String or null	The hex color to be displayed with the Label (for example, “#ff0000”).
created_at Date	The time/date that the Label was created.
description String	The description of the Label.
entity_type Enum (label)	The type of this entity.
epics NestedEpicSlimList	A list of Epics that have this Label.
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.
stories NestedStorySlimList	A list of Stories associated with this Project.
updated_at Date	The time/date that the Label was updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

LabelEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Label]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

LabelEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Label

LabelEpicEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Epic]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

LabelSlim

Name	Description
app_url String (2048)	The Shortcut application url for the Label.
entity_type Enum (label:slim)	The type of this entity.
id Integer	The unique ID of the Label.
name String	The name of the Label.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

LabelStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

LinkedFile

Name	Description
content_type String (128) or null	The content type of the linked file.
created_at Date	The time/date the Linked File was created.
description String (512) or null	The description of the Linked File.
entity_type Enum (linked-file)	The type of this entity.
id Integer	The unique ID of the Linked File.
mentioned_members NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
mentioned_teams NestedTeamSlimList	A list of Teams that this Member belongs to.
name String (256)	The name of the Linked File.
size Integer or null	The size of the Linked File, if available.
stories NestedStorySlimList	A list of Stories associated with this Project.
thumbnail_url String (2048) or null	The URL of the thumbnail, if the integration provided it.
type String (63)	The integration type (e.g. google, dropbox, box, onedrive, url).
updated_at Date	The time/date the Linked File was updated.
uploader MemberSlim
uri String (2048)	A resolvable URI for the entity that will return the full representation.
url String (2048)	The URL of the Linked File.

LinkedFileEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [LinkedFile]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

LinkedFileEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity LinkedFile

LinkedFileMentionedMemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

LinkedFileMentionedTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

LinkedFileSlim

Name	Description
entity_type Enum (linked-file:slim)	The type of this entity.
id Integer	The unique ID of the Linked File.
name String (256)	The name of the Linked File.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

LinkedFileStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

Member

The Member the caller is authenticated as.

Name	Description
created_at Date	The time/date the Member was created.
disabled Boolean	True if the Member is disabled (no longer has access to the Workspace).
email_address String	The Member’s email address.
entity_type Enum (member)	The type of this entity.
id UUID	The unique ID of the Member.
mention_name String	The Member’s mention name, used to @mention them in text fields.
name String	The full name of the Member.
role String	The role of the Member in the Workspace.
teams NestedTeamSlimList	A list of Teams that this Member belongs to.
updated_at Date	The time/date the Member was last updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

MemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

MemberEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Member	The Member the caller is authenticated as.

MemberSlim

Name	Description
entity_type Enum (member:slim)	The type of this entity.
id UUID	The unique ID of the Member.
name String	The name of the Member.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

MemberStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

MemberTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

NestedBranchSlimList

A list of Git branches attached to the Story.

Name	Description
current_items Integer
entities Array [BranchSlim]
list_url String (2048)
total_items Integer

NestedChecklistItemSlimList

A list of Checklist Items attached to the Story.

Name	Description
current_items Integer
entities Array [ChecklistItemSlim]
list_url String (2048)
total_items Integer

NestedCommentSlimList

A list of comments attached to the Story.

Name	Description
current_items Integer
entities Array [CommentSlim]
list_url String (2048)
total_items Integer

NestedCommitSlimList

A list of commits attached to the Story.

Name	Description
current_items Integer
entities Array [CommitSlim]
list_url String (2048)
total_items Integer

NestedCustomFieldValueSlimList

A list of Custom Field values for the Story.

Name	Description
current_items Integer
entities Array [CustomFieldValueSlim]
list_url String (2048)
total_items Integer

NestedEpicSlimList

A list of Epics that have this Label.

Name	Description
current_items Integer
entities Array [EpicSlim]
list_url String (2048)
total_items Integer

NestedEpicStateList

A list of Epic States in the Epic Workflow.

Name	Description
current_items Integer
entities Array [EpicState]
list_url String (2048)
total_items Integer

NestedExternalLinkList

A list of external links connected to the Story.

Name	Description
current_items Integer
entities Array [ExternalLink]
list_url String (2048)
total_items Integer

NestedFileSlimList

A list of files attached to the Story.

Name	Description
current_items Integer
entities Array [FileSlim]
list_url String (2048)
total_items Integer

NestedHealthSlimList

The Health updates on the Objective.

Name	Description
current_items Integer
entities Array [HealthSlim]
list_url String (2048)
total_items Integer

NestedIterationSlimList

A list of Iterations that this Story has been attached to.

Name	Description
current_items Integer
entities Array [IterationSlim]
list_url String (2048)
total_items Integer

NestedKeyResultSlimList

The Key Results associated with the Objective.

Name	Description
current_items Integer
entities Array [KeyResultSlim]
list_url String (2048)
total_items Integer

NestedLabelSlimList

A list of labels attached to the Story.

Name	Description
current_items Integer
entities Array [LabelSlim]
list_url String (2048)
total_items Integer

NestedLinkedFileSlimList

A list of linked files attached to the Story.

Name	Description
current_items Integer
entities Array [LinkedFileSlim]
list_url String (2048)
total_items Integer

NestedMemberSlimList

A list of Members mentioned in the text of this Comment.

Name	Description
current_items Integer
entities Array [MemberSlim]
list_url String (2048)
total_items Integer

NestedObjectiveSlimList

The Objectives associated with this Epic.

Name	Description
current_items Integer
entities Array [ObjectiveSlim]
list_url String (2048)
total_items Integer

NestedPullRequestSlimList

A list of Pull/Merge Requests attached to the Story.

Name	Description
current_items Integer
entities Array [PullRequestSlim]
list_url String (2048)
total_items Integer

NestedReactionSlimList

A list of Reactions to this Comment.

Name	Description
current_items Integer
entities Array [ReactionSlim]
list_url String (2048)
total_items Integer

NestedStoryLinkSlimList

A list of Story links attached to the Story.

Name	Description
current_items Integer
entities Array [StoryLinkSlim]
list_url String (2048)
total_items Integer

NestedStorySlimList

A list of Stories associated with this Project.

Name	Description
current_items Integer
entities Array [StorySlim]
list_url String (2048)
total_items Integer

NestedTeamSlimList

A list of Teams that this Member belongs to.

Name	Description
current_items Integer
entities Array [TeamSlim]
list_url String (2048)
total_items Integer

NestedThreadedCommentSlimList

The Comments on the Epic.

Name	Description
current_items Integer
entities Array [ThreadedCommentSlim]
list_url String (2048)
total_items Integer

NestedWorkflowSlimList

A list of Workflows associated with this Team.

Name	Description
current_items Integer
entities Array [WorkflowSlim]
list_url String (2048)
total_items Integer

NestedWorkflowStateSlimList

A list of Workflow States in the Workflow.

Name	Description
current_items Integer
entities Array [WorkflowStateSlim]
list_url String (2048)
total_items Integer

Objective

Name	Description
app_url String (2048)	The Shortcut application url for the Objective.
archived Boolean	Whether the Objective is archived.
categories Array [CategorySlim]	The Categories associated with the Objective.
completed Boolean	Whether the Objective has 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 description of the Objective.
entity_type Enum (objective)	The type of this entity.
epics NestedEpicSlimList	A list of Epics that have this Label.
healths NestedHealthSlimList	The Health updates on the Objective.
id Integer	The unique ID of the Objective.
key_results NestedKeyResultSlimList	The Key Results associated with the Objective.
name String (512)	The name of the Objective.
owners NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
started Boolean	Whether 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 Enum (done, in progress, to do)	The workflow state of the Objective.
teams NestedTeamSlimList	A list of Teams that this Member belongs to.
updated_at Date	The time/date the Objective was last updated.
uri String (2048)	A resolvable URI for the entity.

ObjectiveCategoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Category]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

ObjectiveEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Objective]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

ObjectiveEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Objective

ObjectiveEpicEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [EpicSlim]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

ObjectiveKeyResultEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [KeyResult]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

ObjectiveOwnerEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

ObjectiveSlim

Name	Description
app_url String (2048)	The Shortcut application url for the Objective.
entity_type Enum (objective:slim)	The type of this entity.
id Integer	The unique ID of the Objective.
name String	The name of the Objective.
uri String (2048)	A resolvable URI for the entity.

ObjectiveTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

Project

The entity for this response.

Name	Description
abbreviation String or null	The Project’s abbreviation.
app_url String (2048)	The Shortcut application url for the Project.
archived Boolean	True if the Project has been archived.
color String or null	The hex color assigned to the Project.
created_at Date	The time/date the Project was created.
days_to_thermometer Integer or null	The number of days before the thermometer is shown.
description String or null	The description of the Project.
entity_type Enum (project)	The type of this entity.
external_id String or null	The external ID for the Project, set when imported from another tool.
followers NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
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	Whether the thermometer is shown for this Project.
start_time Date or null	The date at which the Project was started.
stories NestedStorySlimList	A list of Stories associated with this Project.
updated_at Date	The time/date the Project was last updated.
uri String (2048)	A resolvable URI for the entity.
workflow WorkflowSlim or null	The default Workflow for the Workspace the caller is authenticated against.

ProjectEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Project]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

ProjectEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Project	The entity for this response.

ProjectFollowerEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

ProjectSlim

The Project the story belongs to.

Name	Description
app_url String (2048)	The Shortcut application url for the Project.
entity_type Enum (project:slim)	The type of this entity.
id Integer	The unique ID of the Project.
name String	The name of the Project.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

ProjectStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

PullRequest

Name	Description
branch BranchSlim
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 Pull Request is in draft state.
entity_type Enum (pull-request)	The type of this entity.
external_id String	The Pull Request’s id in the VCS provider.
external_url String	The URL for the Pull Request in the VCS provider.
id Integer	The unique ID of the Pull Request.
repository RepositorySlim	The Repository that contains the Commit.
stories NestedStorySlimList	A list of Stories associated with this Project.
target_branch BranchSlim
title String	The title of the Pull Request.
updated_at Date	The time/date the Pull Request was last updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

PullRequestEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [PullRequest]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

PullRequestEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity PullRequest

PullRequestSlim

Name	Description
entity_type Enum (pull-request:slim)	The type of this entity.
id Integer	The unique ID of the Pull Request.
name String	The name of the Pull Request.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

PullRequestStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

Reaction

Name	Description
author MemberSlim
comment CommentSlim
created_at Date	The time/date the Reaction was created.
emoji String	The emoji used for the Reaction.
entity_type Enum (reaction)	The type of this entity.
id UUID	The unique ID of the Reaction.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

ReactionSlim

Name	Description
emoji String	The emoji used for the Reaction.
entity_type Enum (reaction:slim)	The type of this entity.
id UUID	The unique ID of the Reaction.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

Repository

Name	Description
branches NestedBranchSlimList	A list of Git branches attached to the Story.
commits NestedCommitSlimList	A list of commits attached to the Story.
created_at Date	The time/date the Repository was created.
entity_type Enum (repository)	The type of this entity.
external_url String	The URL of the Repository in the VCS provider.
full_name String	The full name of the Repository (e.g. owner/repo-name).
id Integer	The unique ID of the Repository.
name String	The name of the Repository.
pull_requests NestedPullRequestSlimList	A list of Pull/Merge Requests attached to the Story.
updated_at Date	The time/date the Repository was last updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

RepositoryBranchEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Branch]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

RepositoryCommitEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Commit]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

RepositoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Repository]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

RepositoryEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Repository

RepositoryPullRequestEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [PullRequest]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

RepositorySlim

The Repository that contains the Commit.

Name	Description
entity_type Enum (repository:slim)	The type of this entity.
id Integer	The unique ID of the Repository.
name String	The name of the Repository.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

Story

Name	Description
app_url String (2048)	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 NestedBranchSlimList	A list of Git branches attached to the Story.
checklist_items NestedChecklistItemSlimList	A list of Checklist Items attached to the Story.
comments NestedCommentSlimList	A list of comments attached to the Story.
commits NestedCommitSlimList	A list 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_field_values NestedCustomFieldValueSlimList	A list of Custom Field values for the Story.
deadline Date or null	The Story’s deadline.
description String	The description of the Story.
entity_type Enum (story)	The type of this entity.
epic EpicSlim or null	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 NestedExternalLinkList	A list of external links connected to the Story.
files NestedFileSlimList	A list of files attached to the Story.
followers NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
id Integer	The unique ID of the Story.
iterations NestedIterationSlimList	A list of Iterations that this Story has been attached to.
labels NestedLabelSlimList	A list of labels attached to the Story.
linked_files NestedLinkedFileSlimList	A list of linked files attached to the Story.
mentioned_members NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
mentioned_teams NestedTeamSlimList	A list of Teams that this Member belongs to.
moved_at Date or null	The time this Story was last moved between Workflow States.
name String	The name of the Story.
owners NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
parent_story StorySlim or null	The Story this Checklist Item belongs to.
position Integer	The Story’s relative position.
project ProjectSlim or null	The Project the story belongs to.
pull_requests NestedPullRequestSlimList	A list of Pull/Merge Requests attached to the Story.
requester MemberSlim
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.
story_links NestedStoryLinkSlimList	A list of Story links attached to the Story.
story_template StoryTemplateSlim or null
story_type Enum (bug, chore, feature)	The type of Story (feature, bug, chore).
sub_task_stories NestedStorySlimList	A list of Stories associated with this Project.
team TeamSlim or null
updated_at Date	The time/date the Story was updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.
workflow WorkflowSlim	The default Workflow for the Workspace the caller is authenticated against.
workflow_state WorkflowStateSlim	The default Workflow State of the Workspace’s default Workflow.

StoryBranchEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Branch]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryChecklistItemEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [ChecklistItem]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryChecklistItemEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity ChecklistItem

StoryChecklistItemMentionedMemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryChecklistItemMentionedTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryCommentCommentEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Comment]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryCommentEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Comment]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryCommentEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Comment

StoryCommentMentionedMemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryCommentMentionedTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryCommentReactionEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Reaction]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryCommentReactionEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Reaction

StoryCommitEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Commit]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryCustomFieldValueEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [CustomFieldValue]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Story

StoryExternalLinkEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [ExternalLink]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryFileEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [File]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryFollowerEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryIterationEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Iteration]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryLabelEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Label]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryLink

The entity for this response.

Name	Description
created_at Date	The time/date the Story Link was created.
entity_type Enum (story-link)	The type of this entity.
id Integer	The unique identifier of the Story Link.
object StorySlim	The Story this Checklist Item belongs to.
subject StorySlim	The Story this Checklist Item belongs to.
updated_at Date	The time/date the Story Link was last updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.
verb Enum (blocks, duplicates, relates to)	How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”.

StoryLinkEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [StoryLink]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryLinkEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity StoryLink	The entity for this response.

StoryLinkSlim

Name	Description
entity_type Enum (story-link:slim)	The type of this entity.
id Integer	The unique identifier of the Story Link.
object StorySlim	The Story this Checklist Item belongs to.
subject StorySlim	The Story this Checklist Item belongs to.
uri String (2048)	A resolvable URI for the entity that will return the full representation.
verb String	How the subject Story acts on the object Story. This can be “blocks”, “duplicates”, or “relates to”.

StoryLinkedFileEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [LinkedFile]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryMentionedMemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryMentionedTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryOwnerEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryPullRequestEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [PullRequest]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StorySlim

The Story this Checklist Item belongs to.

Name	Description
app_url String (2048)	The Shortcut application url for the Story.
entity_type Enum (story:slim)	The type of this entity.
id Integer	The unique ID of the Story.
name String	The name of the Story.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

StoryStoryLinkEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [StoryLink]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StorySubTaskStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

StoryTemplateSlim

Name	Description
entity_type Enum (story-template:slim)	The type of this entity.
id UUID	The unique ID of the Story Template.
name String	The name of the Story Template.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

Team

Name	Description
app_url String (2048)	The Shortcut application url for the Team.
archived Boolean	True if the Team has been archived.
color Color or null	The hex color to be displayed with the Team (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 Team.
created_at Date	The time/date the Team was created.
default_workflow WorkflowSlim or null	The default Workflow for the Workspace the caller is authenticated against.
description String	The description of the Team.
entity_type Enum (team)	The type of this entity.
id UUID	The unique ID of the Team.
members NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
mention_name String or null	The Team’s mention name, used to @mention the team in text fields.
name String	The name of the Team.
updated_at Date	The time/date the Team was last updated.
uri String (2048)	A resolvable URI for the entity that will return the full representation.
workflows NestedWorkflowSlimList	A list of Workflows associated with this Team.

TeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

TeamEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Team

TeamMemberEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Member]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

TeamSlim

Name	Description
app_url String (2048)	The Shortcut application url for the Team.
entity_type Enum (team:slim)	The type of this entity.
id UUID	The unique ID of the Team.
name String	The name of the Team.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

TeamStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

TeamWorkflowEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Workflow]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

ThreadedComment

The entity for this response.

Name	Description
app_url String (2048) or null	The Shortcut application url for the Comment. Will be null if the comment is deleted.
author MemberSlim
comments NestedThreadedCommentSlimList	The Comments on the Epic.
created_at Date	The time/date the Comment was created.
deleted Boolean	Whether the Comment has been deleted.
entity_type Enum (threaded-comment)	The type of this entity.
epic EpicSlim	The Epic the story belongs to.
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.
id Integer or null	The unique ID of the Comment. Will be null if the comment is deleted.
mentioned_members NestedMemberSlimList	A list of Members mentioned in the text of this Comment.
mentioned_teams NestedTeamSlimList	A list of Teams that this Member belongs to.
parent_comment ThreadedCommentSlim or null
text String or null	The text of the Comment. Will be null if the comment is deleted.
updated_at Date	The time/date the Comment was last updated.
uri String (2048) or null	A resolvable URI for the entity that will return the full representation. Will be null if the comment is deleted.

ThreadedCommentSlim

Name	Description
app_url String (2048)	The Shortcut application url for the Comment.
deleted Boolean	Whether the Comment has been deleted.
entity_type Enum (threaded-comment:slim)	The type of this entity.
id Integer	The unique ID of the Comment.
text String	The text of the Comment.
uri String (2048)	A resolvable URI for the entity.

Token

Name	Description
created_at Date	The time/date the Token was created.
description String	The description of the Token.
disabled Boolean	True if the Token has been disabled.
email_address String	The email address of the Member this Token belongs to.
entity_type Enum (token)	The type of this entity.
id UUID	The unique ID of the Token.
last_used_at Date or null	The date the Token was last used. Null if never used.
member MemberSlim
scopes Array [String] or null	The scopes granted to this token. Possible values: “read”, “write”, “story-write”, “comment-write”, “admin”. Null for legacy tokens.
updated_at Date	The time/date the Token was last updated.
uri String (2048)	A resolvable URI for the entity.

TokenAuthorization

The authorization details for the token used to authenticate this request.

Name	Description
scopes Array [String]	The scopes granted by the token. Possible values are “read”, “write”, “story-write”, “comment-write”, and “admin”.

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.

UpdateCustomFieldEnumValueParams

Name	Description
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 for this enum value. Pass null to clear.
enabled Boolean	Whether this enum value is enabled.
id UUID	The ID of an existing enum value to update. Omit to create a new value.
value String (63)	The string value for this enum value.

UpdateEntityTemplateStoryContentsParams

Updated attributes for the template to populate.

Name	Description
custom_fields Array [CreateCustomFieldValueParams]	An array of CustomField value assertions to set on the template, replacing existing values.
custom_fields_add Array [CreateCustomFieldValueParams]	An array of CustomField value assertions to add to the template.
custom_fields_remove Array [CreateCustomFieldValueParams]	An array of CustomField value assertions to remove from the template.
deadline Date or null	The due date of the story.
description String (512)	The description of the story.
epic_id Integer or null	The ID of the epic to be populated.
estimate Integer or null	The numeric point estimate to be populated.
external_links Array [String]	An array of external links to set on the template, replacing existing links.
external_links_add Array [String]	An array of external links to add to the template.
external_links_remove Array [String]	An array of external links to remove from the template.
file_ids Array [Integer]	An array of file IDs to set on the template, replacing existing files.
file_ids_add Array [Integer]	An array of file IDs to add to the template.
file_ids_remove Array [Integer]	An array of file IDs to remove from the template.
follower_ids Array [UUID]	An array of UUIDs for any Members you want to set as Followers, replacing existing Followers.
follower_ids_add Array [UUID]	An array of UUIDs for any Members you want to add as Followers.
follower_ids_remove Array [UUID]	An array of UUIDs for any Members you want to remove 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 to be populated.
label_ids Array [Integer]	An array of label IDs to set on the template, replacing existing labels.
label_ids_add Array [Integer]	An array of label IDs to add to the template.
label_ids_remove Array [Integer]	An array of label IDs to remove from the template.
linked_file_ids Array [Integer]	An array of linked file IDs to set on the template, replacing existing linked files.
linked_file_ids_add Array [Integer]	An array of linked file IDs to add to the template.
linked_file_ids_remove Array [Integer]	An array of linked file IDs to remove from the template.
name String (512)	The name of the story.
owner_ids Array [UUID]	An array of UUIDs for any Members you want to set as Owners, replacing existing Owners.
owner_ids_add Array [UUID]	An array of UUIDs for any Members you want to add as Owners.
owner_ids_remove Array [UUID]	An array of UUIDs for any Members you want to remove as Owners.
project_id Integer or null	The ID of the project the story belongs to.
story_type Enum (bug, chore, feature)	The type of story (feature, bug, chore).
sub_tasks Array [CreateEntityTemplateSubTaskParams]	An array of sub-tasks to be populated by the template.
tasks Array [CreateEntityTemplateTaskParams]	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.

UpdateKeyResultValueParams

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.

UpdateStoryLinkParams

Name	Description
id Integer	The unique ID of the Story Link to update.
object_story_id Integer	The unique ID of the Story defined as object.
subject_story_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 one of: “blocks”, “duplicates”, “relates to”

Whoami

The entity for this response.

Name	Description
authorization TokenAuthorization	The authorization details for the token used to authenticate this request.
default_workflow WorkflowSlim	The default Workflow for the Workspace the caller is authenticated against.
default_workflow_state WorkflowStateSlim	The default Workflow State of the Workspace’s default Workflow.
entity_type Enum (whoami)	The type of this entity.
member Member	The Member the caller is authenticated as.
workspace WorkspaceSlim	The Workspace the caller is authenticated against.

WhoamiEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Whoami	The entity for this response.

Workflow

Name	Description
auto_assign_owner Boolean	Indicates if an owner is automatically assigned when an unowned story is started.
created_at Date	The time/date the Workflow was created.
default_workflow_state WorkflowStateSlim	The default Workflow State of the Workspace’s default Workflow.
description String or null	The description of the Workflow.
entity_type Enum (workflow)	The type of this entity.
id Integer	The unique ID of the Workflow.
name String	The name of the Workflow.
teams NestedTeamSlimList	A list of Teams that this Member belongs to.
updated_at Date	The time/date the Workflow was last updated.
workflow_states NestedWorkflowStateSlimList	A list of Workflow States in the Workflow.

WorkflowEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Workflow]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

WorkflowEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Workflow

WorkflowProjectEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Project]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

WorkflowSlim

The default Workflow for the Workspace the caller is authenticated against.

Name	Description
entity_type Enum (workflow:slim)	The type of this entity.
id Integer	The unique ID of the Workflow.
name String	The name of the Workflow.
uri String (2048)	A resolvable URI for the entity that will return the full representation.

WorkflowState

Name	Description
color String or null	The color of the 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 Enum (workflow-state)	The type of this entity.
id Integer	The unique ID of the Workflow State.
name String	The name of the Workflow State.
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 the Workflow State (backlog, unstarted, started, done).
updated_at Date	The time/date the Workflow State was last updated.
verb String or null	The verb that triggers a move to that Workflow State when making VCS commits.
workflow WorkflowSlim	The default Workflow for the Workspace the caller is authenticated against.

WorkflowStateEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [WorkflowState]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

WorkflowStateEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity WorkflowState

WorkflowStateSlim

The default Workflow State of the Workspace’s default Workflow.

Name	Description
entity_type Enum (workflow-state:slim)	The type of this entity.
id Integer	The unique ID of the Workflow State.
name String	The name of the Workflow State.
uri String (2048)	A resolvable URI for the entity that will return the full representation.
workflow_name String	The name of the Workflow this state belongs to.

WorkflowStoryEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Story]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

WorkflowTeamEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Team]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

WorkspaceSlim

The Workspace the caller is authenticated against.

Name	Description
app_url String (2048)	The Shortcut application url for the Workspace.
entity_type Enum (workspace:slim)	The type of this entity.
id UUID	The unique ID of the Workspace.
name String	The name of the Workspace.
slug String	The URL Slug for the Workspace (aka `workspace-slug`).

WorkspaceTokenEntityListWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
current_items Integer	The number of items on the current page.
current_page Integer	The number of the current page.
entities Array [Token]	The entities for this page.
next_page_url String (2048)	A URL to get the next page. Will be absent on the last page.
total_items Integer	The number of total items across all pages.
total_pages Integer	The total number of pages.

Name	Description
workspace-slug String	Required. The slug for the Workspace.
category-public-id Integer	Required. The ID of the Category.

Introduction

API Status

Examples

Authentication

Workspace Slug

Pagination

Field Filtering

Rate Limiting

String Length Limits

Setting Colors

Response Formats

Nullable Fields

OpenAPI file

Migrating from v3 to v4

{schema-Name}

Get Schema

URL Parameters

Responses

Whoami

Get Whoami

Responses

Admin

List Workspace Tokens

URL Parameters

URL Query Parameters

Responses

Delete Workspace Token

URL Parameters

Responses

Branches

List Branches

URL Parameters

URL Query Parameters

Responses

Get Branch

URL Parameters

URL Query Parameters

Responses

List Branch Pull Requests

URL Parameters

URL Query Parameters

Responses

List Branch Stories

URL Parameters

URL Query Parameters

Responses

Categories

List Categories

URL Parameters

URL Query Parameters

Responses

Create Category

URL Parameters

URL Query Parameters

Body Parameters

Responses

Bulk Create Categories

URL Parameters

URL Query Parameters

Body Parameters

Responses

Bulk Update Categories

URL Parameters

URL Query Parameters

Body Parameters

Responses

Bulk Delete Categories

URL Parameters

Body Parameters

Responses

Get Category

URL Parameters

URL Query Parameters

Responses

Update Category

URL Parameters

URL Query Parameters

Body Parameters

Responses

Delete Category