Last updated: Tuesday, November 03, 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!

Why v4

v4 is a redesign of the Shortcut API, not an extension of v3. v3 grew one endpoint at a time over many years. One list endpoint is paginated and the rest are not, nested collections have no size limit, entity names lag behind the product (Groups are Teams, Milestones are Objectives), and a token grants full access to everything. A developer can read around those gaps. A program that has to infer the rules from responses cannot.

v4 trades backwards compatibility for consistency. Every endpoint follows the same rules, so what you learn from one entity applies to all of them:

Entity and list responses come wrapped in an envelope. The envelope’s $schema field links to the JSON Schema for that response.
Every list endpoint pages its results with a cursor. The cursor pins results to a point in time, so pages stay consistent even when the workspace changes between requests.
Nested collections return the first page of slim entities plus a link to the full, paged list, so no single response is unbounded.
Updates use PATCH with partial payloads. Set-valued fields take _add and _remove variants, so you can change membership without resending the whole set.
Bulk create, update, and delete endpoints handle up to 100 entities per request.
Entities use their current product names: Team, Objective, Checklist Item, Member.
Every entity carries created_at and updated_at, and workflowed entities carry started_at and completed_at.
v4 enforces the limit of 200 requests per minute.

Built for agents

We expect a growing share of v4 clients to be AI agents and the tools built around them: coding agents that pick up Stories, assistants that plan and report inside Shortcut, and MCP servers that expose the API as tools. An agent cannot ask a colleague what a field means, and it will not notice a truncated list. v4 puts that information in the API:

A machine-readable contract. The OpenAPI 3 document at /api/v4/openapi describes every route, parameter, and response. Each entity and list response also links to the JSON Schema for its own shape, so a client can check what it received without loading the whole document. You can generate tool definitions from the OpenAPI document instead of writing them by hand. The soon to be released full rebuild of the Shortcut MCP server generates its tools from this document.
Bounded, predictable responses. Field filtering returns only the fields a client asks for, which keeps context windows small. Paged lists and capped nested collections mean no response can grow without limit.
Scoped delegation. A token belongs to one workspace and acts as the member who created it. Its scopes narrow that further. A token with the read and comment-write scopes can read the workspace and comment on Stories, and nothing else. You can give an agent exactly the access its job needs.
Explicit failure. Unknown field names, tampered cursors, and writes with a read-only token return a 4xx error instead of a partial result.
Context and history. Cross-entity search returns one ranked, paged list across Epics, Stories, Iterations, Objectives, and Docs. History endpoints for Stories and Epics expose what changed and when, so an agent can reconstruct how work reached its current state.
Agent sessions (coming soon). A session groups an agent’s work on a Story or Epic inside its Activity Feed: the plan it is following, the actions it takes, the questions it asks, and its final result. Members reply to or stop a session from the same feed, and the agent reads those prompts back through the API, so a human and an agent can hand work back and forth without leaving Shortcut.

API Status

This is a beta version of the Shortcut API. We consider it stable and close to a full release, but it may still change in backwards-incompatible ways during this period.

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 take the form sct_{scopes}_{workspace-slug}_{secret}. v3 tokens do not work with v4 endpoints.

The scopes segment holds one letter for each scope the token has:

Letter	Scope	Allows
`r`	read	Every read endpoint
`w`	write	Every write endpoint
`s`	story-write	Create Story and Update Story
`c`	comment-write	Create Story Comment and Update Story Comment
`a`	admin	Listing and disabling the workspace’s API tokens. Only workspace admins can grant it.

A read-only token starts with sct_r_. A full-access token starts with sct_rw_, or sct_rwa_ when a workspace admin creates it. A token with only the story-write, comment-write, or admin scope can call only the endpoints that scope names, and every other request returns 403 Forbidden. Older read-only tokens start with sct_ro_ and still work as read-only tokens.

To make it easier to explore our API, we recommend saving this token as an environment variable in your local dev environment:

export SHORTCUT_API_TOKEN="YOUR API TOKEN HERE"

This will allow you to copy and paste many of the example curl requests on this page into your terminal to try them out.

Requests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS. Tokens provide complete access to your Shortcut account, so keep them secure. Don’t paste them into your source code, use an environment variable instead. For security reasons, we will immediately invalidate any tokens we find have been made public.

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"

Responses

Code	Description
200
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"

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

Agent-Sessions

List Agent Sessions

List sessions on a Story or Epic, newest first.

Definition

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

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}/agent-sessions"

URL Parameters

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

URL Query Parameters

Name	Description
entity_type Enum (epic, story)	Required. The type of entity the sessions belong to.
entity_id Integer	Required. The public ID of the Story or Epic.
cursor Integer	The next_cursor value from the previous page.
limit Integer	Maximum number of sessions to return, 1-100. Defaults to 50.

Responses

Code	Description
200
400	Schema mismatch
403	Either: (1) Resource does not exist or (2)
404	Either: (1) Resource does not exist or (2)
409	Either: (1) Resource does not exist or (2)
422	Either: (1) Resource does not exist or (2)
503	Either: (1) Resource does not exist or (2)

Create Agent Session

Create work owned by the authenticated agent on a Story or Epic. Repeated identical idempotency keys return the same session.

Definition

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

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "entity_id": 123, "entity_type": "epic", "idempotency_key": "foo" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions"

URL Parameters

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

Body Parameters

Name	Description
entity_id Integer	Required. The public ID of the Story or Epic.
entity_type Enum (epic, story)	Required. The type of entity the session belongs to.
idempotency_key String	Required. Client key that makes repeated identical requests return the same session.

Responses

Code	Description
201
400	Schema mismatch
403	Either: (1) Resource does not exist or (2)
404	Either: (1) Resource does not exist or (2)
409	Either: (1) Resource does not exist or (2)
422	Either: (1) Resource does not exist or (2)
429	Either: (1) Resource does not exist or (2)
503	Either: (1) Resource does not exist or (2)

Opt the authenticated agent installation into session events instead of legacy interaction webhooks.

Definition

PUT https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/subscription

Example Request

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "enabled": true }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/subscription"

URL Parameters

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

Body Parameters

Name	Description
enabled Boolean	Required. Enable or disable session events for this installation.

Responses

Code	Description
200
400	Schema mismatch
403	Either: (1) Resource does not exist or (2)
404	Either: (1) Resource does not exist or (2)
409	Either: (1) Resource does not exist or (2)
422	Either: (1) Resource does not exist or (2)
429	Either: (1) Resource does not exist or (2)
503	Either: (1) Resource does not exist or (2)

Get Agent Session

Get a session visible to the current member.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/{agent-session-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}/agent-sessions/{agent-session-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
agent-session-id UUID	Required. The ID of the Agent Session.

Responses

Code	Description
200
400	Schema mismatch
403	Either: (1) Resource does not exist or (2)
404	Either: (1) Resource does not exist or (2)
409	Either: (1) Resource does not exist or (2)
422	Either: (1) Resource does not exist or (2)
503	Either: (1) Resource does not exist or (2)

Update Agent Session

Replace a session plan or external links using its current version.

Definition

PATCH https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/{agent-session-id}

Example Request

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "external_urls": [{ "label": "foo", "url": "foo" }], "plan": [{ "content": "foo", "status": "canceled" }], "version": 123 }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/{agent-session-id}"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
agent-session-id UUID	Required. The ID of the Agent Session.

Body Parameters

Name	Description
external_urls Array [SessionExternalUrl]	Replaces all external links. URLs must be unique.
plan Array [SessionPlanItem]	Replaces the whole plan.
version Integer	Required. The current session version. The update fails with 409 if it has changed.

Responses

Code	Description
200
400	Schema mismatch
403	Either: (1) Resource does not exist or (2)
404	Either: (1) Resource does not exist or (2)
409	Either: (1) Resource does not exist or (2)
422	Either: (1) Resource does not exist or (2)
429	Either: (1) Resource does not exist or (2)
503	Either: (1) Resource does not exist or (2)

List Agent Activities

Read session activities in stable sequence order.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/{agent-session-id}/activities

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}/agent-sessions/{agent-session-id}/activities"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
agent-session-id UUID	Required. The ID of the Agent Session.

URL Query Parameters

Name	Description
after Integer	Return activities with a sequence greater than this value. Defaults to 0.
limit Integer	Maximum number of activities to return, 1-100. Defaults to 100.

Responses

Code	Description
200
400	Schema mismatch
403	Either: (1) Resource does not exist or (2)
404	Either: (1) Resource does not exist or (2)
409	Either: (1) Resource does not exist or (2)
422	Either: (1) Resource does not exist or (2)
503	Either: (1) Resource does not exist or (2)

Create Agent Activity

Publish a typed activity as the agent owning the session.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/{agent-session-id}/activities

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "content": { "action": "foo", "body": "foo", "parameter": "foo", "result": "foo", "type": "action" }, "ephemeral": true, "idempotency_key": "foo", "signal": "auth", "signal_metadata": { "options": [{
    "label": "foo",
    "value": "foo"
  }], "url": "foo" }, "turn": 123 }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/{agent-session-id}/activities"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
agent-session-id UUID	Required. The ID of the Agent Session.

Body Parameters

Name	Description
content ActivityContent	Required. Typed activity content: thought, action, elicitation, response or error.
ephemeral Boolean	Replace this thought or action when the next agent activity arrives.
idempotency_key String	Required. Client key that makes repeated identical requests return the same activity.
signal Enum (auth, select)	Optional signal on an elicitation.
signal_metadata SignalMetadata	Metadata for the signal: a url for auth, options for select.
turn Integer	Required. The session turn this activity belongs to. Must match the current turn.

Responses

Code	Description
201
400	Schema mismatch
403	Either: (1) Resource does not exist or (2)
404	Either: (1) Resource does not exist or (2)
409	Either: (1) Resource does not exist or (2)
422	Either: (1) Resource does not exist or (2)
429	Either: (1) Resource does not exist or (2)
503	Either: (1) Resource does not exist or (2)

Get Agent Session Context

Get current authorized entity context for a session.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/{agent-session-id}/context

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}/agent-sessions/{agent-session-id}/context"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
agent-session-id UUID	Required. The ID of the Agent Session.

Responses

Code	Description
200
400	Schema mismatch
403	Either: (1) Resource does not exist or (2)
404	Either: (1) Resource does not exist or (2)
409	Either: (1) Resource does not exist or (2)
422	Either: (1) Resource does not exist or (2)
503	Either: (1) Resource does not exist or (2)

Prompt Agent Session

Continue an explicitly selected session or request that its agent stop.

Definition

POST https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/{agent-session-id}/prompts

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "body": "foo", "idempotency_key": "foo", "in_reply_to": "12345678-9012-3456-7890-123456789012", "signal": "stop", "turn": 123 }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/agent-sessions/{agent-session-id}/prompts"

URL Parameters

Name	Description
workspace-slug String	Required. The slug for the Workspace.
agent-session-id UUID	Required. The ID of the Agent Session.

Body Parameters

Name	Description
body String	Required. The message to the agent. Markdown is supported.
idempotency_key String	Required. Client key that makes repeated identical requests return the same prompt.
in_reply_to UUID	The ID of the elicitation activity this prompt answers.
signal Enum (stop)	Ask the agent to stop and publish a final response or error.
turn Integer	Required. The current session turn.

Responses

Code	Description
201
400	Schema mismatch
403	Either: (1) Resource does not exist or (2)
404	Either: (1) Resource does not exist or (2)
409	Either: (1) Resource does not exist or (2)
422	Either: (1) Resource does not exist or (2)
503	Either: (1) Resource does not exist or (2)

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"

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
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}"

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
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"

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
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"

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
400	Schema mismatch
404	Resource does not exist
422	Unprocessable

Collections

List Collections

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

Definition

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

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}/collections"

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)	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, favorited, 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
400	Schema mismatch
403
404	Resource does not exist
422	Unprocessable

Create Collection

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

Definition

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

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SHORTCUT_API_TOKEN" \
  -d '{ "name": "foo", "parent_collection_id": "12345678-9012-3456-7890-123456789012" }' \
  -L "https://api.app.shortcut.com/api/v4/{workspace-slug}/collections"

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
name String (63)	Required. The name of the new Collection. Must be between 1 and 40 characters and unique (case-insensitive) among Collections with the same parent.
parent_collection_id UUID	The ID of an existing Collection to nest the new Collection under.

Responses

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

Get Collection

Get Collection returns information about a chosen Collection.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/collections/{collection-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}/collections/{collection-public-id}"

URL Parameters

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

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
400	Schema mismatch
403
404	Resource does not exist
422	Unprocessable

Favorite Collection

Favorite Collection marks the Collection as a favorite of the current Member, and returns the updated Collection.

Definition

PUT https://api.app.shortcut.com/api/v4/{workspace-slug}/collections/{collection-public-id}/favorite

Example Request

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

URL Parameters

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

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
400	Schema mismatch
403
404	Resource does not exist
422	Unprocessable

Unfavorite Collection

Unfavorite Collection removes the Collection from the current Member’s favorites.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/collections/{collection-public-id}/favorite

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}/collections/{collection-public-id}/favorite"

URL Parameters

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

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
403
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"

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
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}"

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
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"

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
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"

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
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"

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
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}"

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
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}"

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
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"

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
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"

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
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 '{ "collection_ids": ["12345678-9012-3456-7890-123456789012"], "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
collection_ids Array [UUID]	The IDs of Collections to add the new Doc to.
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
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
400	Schema mismatch
403
404	Resource does not exist
422	Unprocessable

Search Docs

Search Docs lets you search Docs by title, with optional archived/created_by_me/followed_by_me filters.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/documents/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}/documents/search"

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	Search text to match against Doc titles. Supports fuzzy matching. Required if `cursor` is not sent.
archived Boolean	When true, find archived Docs. When false, find non-archived Docs.
created_by_me Boolean	When true, find Docs created by the current user. When false, find Docs NOT created by the current user.
followed_by_me Boolean	When true, find Docs that the current user is following. When false, find Docs NOT followed by the current user.
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
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}"

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
content_format Enum (html, markdown)	The format to include the Doc’s content in. Without it, the response has no content.
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
400	Schema mismatch
403
404	Resource does not exist
422	Unprocessable

Update Doc

Update Doc changes the title and/or content of a Doc, and returns the updated Doc. New content replaces the existing content. Requires write access to the Doc.

Definition

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

Example Request

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

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.

Body Parameters

Name	Description
content String	The new content of the Doc. Replaces the existing content.
content_format Enum (html, markdown)	Format of the content being sent. Defaults to ‘markdown’, matching get-doc’s default output. Content is converted to HTML for storage.
title String (256)	The new title of the Doc.

Responses

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

List Doc Collections

List Doc Collections returns a paginated list of the Collections the Doc belongs to.

Definition

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

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}/collections"

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 (created_at, 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_archived, favorited, 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
400	Schema mismatch
403
404	Resource does not exist
422	Unprocessable

Add Doc to Collection

Add Doc to Collection adds the Doc to the chosen Collection, preserving its other Collection memberships, and returns the updated Doc. Requires write access to the Doc.

Definition

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

Example Request

curl -X PUT \
  -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}/collections/{collection-public-id}"

URL Parameters

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

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
400	Schema mismatch
403
404	Resource does not exist
422	Unprocessable

Remove Doc from Collection

Remove Doc from Collection removes the Doc from the chosen Collection, preserving its other Collection memberships. Requires write access to the Doc.

Definition

DELETE https://api.app.shortcut.com/api/v4/{workspace-slug}/documents/{doc-public-id}/collections/{collection-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}/documents/{doc-public-id}/collections/{collection-public-id}"

URL Parameters

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

Responses

Code	Description
204	No Content
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"

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
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"

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
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
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
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"

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
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}"

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
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}"

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
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"

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
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"

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
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"

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
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
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
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"

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

Search Epics

Search Epics lets you search Epics based on a query.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/epics/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}/epics/search"

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
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}"

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
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}"

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
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"

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
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
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
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"

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
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}"

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
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}"

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
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"

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
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"

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
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"

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
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"

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
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
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}"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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"

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
400	Schema mismatch
404	Resource does not exist
422	Unprocessable

Get Epic Stats

Get Epic Stats returns calculated stats for a chosen Epic. Stats are served from this dedicated sub-endpoint (rather than the Epic response itself) to avoid the performance impact of computing them on bulk list requests.

Definition

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

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}/stats"

URL Parameters

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

Responses

Code	Description
200
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"

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
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"

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
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"

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
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"

URL Parameters

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

Form Parameters

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

Responses

Code	Description
201
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}"

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
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"

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
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"

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
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"

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
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"

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
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
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
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"

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
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"

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
400	Schema mismatch
404	Resource does not exist
422	Unprocessable

Search Iterations

Search Iterations lets you search Iterations based on a query.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/iterations/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}/iterations/search"

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
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}"

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
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}"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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}"

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
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}"

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
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"

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
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
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
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"

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
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}"

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
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}"

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
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"

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
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"

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
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"

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
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
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
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"

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
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}"

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
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}"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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}"

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
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}"

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
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"

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
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"

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
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"

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
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
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
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"

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

Search Objectives

Search Objectives lets you search Objectives based on a query.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/objectives/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}/objectives/search"

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
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}"

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
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}"

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
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"

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
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"

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
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"

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
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"

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
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
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}"

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
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"

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
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"

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
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"

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
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
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}"

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
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}"

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
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"

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
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"

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
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"

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
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}"

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
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"

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
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"

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
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}"

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
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"

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
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"

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
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"

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
400	Schema mismatch
404	Resource does not exist
422	Unprocessable

Search

Search lets you search across Epics, Stories, Iterations, Objectives, and Docs with a single query, returning one combined, paginated list of results.

Definition

GET https://api.app.shortcut.com/api/v4/{workspace-slug}/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}/search"

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.
entity_types String	A comma-separated list of entity types to search. Defaults to all supported types. Supported: epic, story, iteration, objective, doc. Docs are only included when the docs feature is enabled for the Workspace.

Responses

Code	Description
200
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"

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
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 Body1269263SetPosition	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
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
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"

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

Get Multiple Stories History

Returns history of changes for multiple Stories in chronological order (oldest first by default; newest first with order_dir=desc), across all attributes, with a deterministic tie-break for changes at the same instant. Ordering is stable across pages. Requires ?ids= parameter. Supports cursor-based pagination. History is currently tracked for these attributes: archived, blocked, blocker, branches, checklist_items, commits, completed, custom_field_values, deadline, description, epic, estimate, followers, iterations, labels, mentioned_members, name, owners, parent_story, project, requester, started, story_links, story_type, team, workflow_state. Changes to other attributes are not included yet but will be added.

Definition

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

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/history"

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.
ids String	Comma-separated Story IDs (max 100).
fields String	Filter history to specific attributes (e.g., workflow_state,epic).
order_dir Enum (asc, desc)	Sort direction by change instant: asc (default, oldest first) or desc (newest first). Entries at the same instant keep the same deterministic tie-break order in both directions.

Responses

Code	Description
200
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"

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
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}"

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
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}"

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 Body1269210SetPosition	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
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"

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
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"

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
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 Body1269249SetPosition	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
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
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"

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
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}"

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
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}"

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 Body1269253SetPosition	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
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"

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
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"

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
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"

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
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
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
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"

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
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}"

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
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}"

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
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"

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
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"

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
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"

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
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"

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
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
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"

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
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"

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
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"

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
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"

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
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"

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
400	Schema mismatch
404	Resource does not exist
422	Unprocessable

Get Story History

Returns history of changes for a Story in chronological order (oldest first by default; newest first with order_dir=desc), across all attributes, with a deterministic tie-break for changes at the same instant. Ordering is stable across pages. Supports cursor-based pagination and optional field filtering. History is currently tracked for these attributes: archived, blocked, blocker, branches, checklist_items, commits, completed, custom_field_values, deadline, description, epic, estimate, followers, iterations, labels, mentioned_members, name, owners, parent_story, project, requester, started, story_links, story_type, team, workflow_state. Changes to other attributes are not included yet but will be added.

Definition

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

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}/history"

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.
fields String	Filter history to specific attributes (e.g., workflow_state,epic).
order_dir Enum (asc, desc)	Sort direction by change instant: asc (default, oldest first) or desc (newest first). Entries at the same instant keep the same deterministic tie-break order in both directions.

Responses

Code	Description
200
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"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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"

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
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
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
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"

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
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}"

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
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}"

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
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"

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
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 '{ "card_aging_mode": "gradual", "card_aging_threshold_days": 123, "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
card_aging_mode Enum (gradual, immediate, off) or null	The card aging mode for stories in this Team: “gradual” (fixed fade steps at 1, 2, and 4 weeks), “immediate”, or “off” (explicitly disabled for this Team). Set to null to inherit the Workspace default.
card_aging_threshold_days Integer or null	The number of days an in-progress Story can go without activity before it is considered stale. Required when card_aging_mode is “immediate”; not allowed otherwise.
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
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": [{ "card_aging_mode": "gradual", "card_aging_threshold_days": 123, "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
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, "card_aging_mode": "gradual", "card_aging_threshold_days": 123, "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"

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
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}"

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
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, "card_aging_mode": "gradual", "card_aging_threshold_days": 123, "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}"

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.
card_aging_mode Enum (gradual, immediate, off) or null	The card aging mode for stories in this Team: “gradual” (fixed fade steps at 1, 2, and 4 weeks), “immediate”, or “off” (explicitly disabled for this Team). Set to null to inherit the Workspace default (also clears card_aging_threshold_days).
card_aging_threshold_days Integer or null	The number of days an in-progress Story can go without activity before it is considered stale. Required when card_aging_mode is “immediate”; not allowed otherwise.
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
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"

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
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"

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
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"

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
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"

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
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}"

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
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"

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
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"

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
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}"

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
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"

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
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"

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
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"

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
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"

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

ActivityContent

Typed activity content: thought, action, elicitation, response or error.

Name	Description
action String
body String
parameter String
result String
type Enum (action, elicitation, error, prompt, response, thought)

ActivityList

Name	Description
data Array [AgentActivity]
next_cursor String or null

AgentActivity

Name	Description
author_id UUID
content ActivityContent	Typed activity content: thought, action, elicitation, response or error.
created_at Date
ephemeral Boolean
id UUID
in_reply_to UUID or null
sequence Integer
session_id UUID
signal String or null
signal_metadata SignalMetadata or null	Metadata for the signal: a url for auth, options for select.
superseded Boolean
turn Integer
workspace_id UUID

AgentSession

Name	Description
acknowledged_at Date or null
agent_member_id UUID
closed_reason String or null
created_at Date
created_by UUID
entity_id Integer
entity_type Enum (epic, story)
external_urls Array [SessionExternalUrl]
first_delivery_at Date or null
id UUID
installation_id UUID
last_agent_activity_at Date or null
last_delivery_error String or null
last_delivery_failed_at Date or null
plan Array [SessionPlanItem]
status Enum (active, awaiting_input, complete, error, pending, stale)
stop_requested_at Date or null
thread_comment_id Integer or null
turn Integer
updated_at Date
version Integer
workspace_id UUID

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 Body1269279StoriesSetPosition	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 Body1269205ChecklistItemsSetPosition	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.
card_aging_mode Enum (gradual, immediate, off) or null	The card aging mode for stories in this Team: “gradual” (fixed fade steps at 1, 2, and 4 weeks), “immediate”, or “off” (explicitly disabled for this Team). Set to null to inherit the Workspace default (also clears card_aging_threshold_days).
card_aging_threshold_days Integer or null	The number of days an in-progress Story can go without activity before it is considered stale. Required when card_aging_mode is “immediate”; not allowed otherwise.
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	The Members who followers of the Doc.
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.

Collection

The entity for this response.

Name	Description
archived Boolean	A true/false boolean indicating if the Collection has been archived.
created_at Date	The time/date the Collection was created.
entity_type Enum (collection)	The type of this entity.
favorited Boolean	True if the current Member has favorited the Collection.
id UUID	The unique ID of the Collection.
name String (63)	The name of the Collection.
parent_collection CollectionSlim or null
uri String (2048)	A resolvable URI for the entity.

CollectionEntityListWrapper

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 [Collection]	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.

CollectionEntityWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity Collection	The entity for this response.

CollectionSlim

Name	Description
entity_type Enum (collection:slim)	The type of this entity.
id UUID	The unique ID of the Collection.
name String (63)	The name of the Collection.
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	The Member who created the Doc.
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	The Members who followers of the Doc.
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	The Member who created the Doc.
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 Body1269206ChecklistItemsSetPosition	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 Body1269280StoriesSetPosition	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
card_aging_mode Enum (gradual, immediate, off) or null	The card aging mode for stories in this Team: “gradual” (fixed fade steps at 1, 2, and 4 weeks), “immediate”, or “off” (explicitly disabled for this Team). Set to null to inherit the Workspace default.
card_aging_threshold_days Integer or null	The number of days an in-progress Story can go without activity before it is considered stale. Required when card_aging_mode is “immediate”; not allowed otherwise.
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

Name	Description
archived Boolean	A true/false boolean indicating if the Doc has been archived.
collections NestedCollectionSlimList	The Collections the Doc belongs to.
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	The Member who created the Doc.
entity_type Enum (doc)	The type of this entity.
followers NestedMemberSlimList	The Members who followers of the Doc.
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.

DocCollectionEntityListWrapper

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 [Collection]	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.

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

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	The Member who created the Doc.
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	The Members who followers of the Doc.
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	The Members who followers of the Doc.
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	The Members who followers of the Doc.
planned_start_date Date or null	The Epic’s planned start date.
requester MemberSlim or null	The Member who created the Doc.
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).

EpicStats

The entity for this response.

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

EpicStatsWrapper

Name	Description
$schema String (2048)	The URI for the json-schema for this response.
entity EpicStats	The entity for this response.

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	The Members who followers of the Doc.
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	The Member who created the Doc.
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	The Member who created the Doc.
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	The Members who followers of the Doc.
id Integer	The unique ID of the Iteration.
labels NestedLabelSlimList	A list of labels attached to the Story.
mentioned_members NestedMemberSlimList	The Members who followers of the Doc.
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	The Member who created the Doc.
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	The Epics associated with the Objective.
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	The Members who followers of the Doc.
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	The Member who created the Doc.
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
agent MemberAgent or null
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 or null	The Member’s email address, if the Member has one. Commonly null for bot/application users such as Korey.
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.

MemberAgent

Name	Description
assignable Boolean	True if the agent may be set as an owner on Stories and Epics.
mentionable Boolean	True if the agent may be @-mentioned in comments and descriptions.

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

The Member who created the Doc.

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

NestedCollectionSlimList

The Collections the Doc belongs to.

Name	Description
current_items Integer
entities Array [CollectionSlim]
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

The Epics associated with the Objective.

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

The Members who followers of the Doc.

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	The Epics associated with the Objective.
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	The Members who followers of the Doc.
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	The Members who followers of the Doc.
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.

PromptContext

Name	Description
comment_text String
text String
truncated Boolean

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	The Member who created the Doc.
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.

SearchEntitiesOutput

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 OR Story OR Iteration OR Objective OR 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.

SessionError

Name	Description
message String

SessionExternalUrl

Name	Description
label String
url String

SessionList

Name	Description
data Array [AgentSession]
next_cursor String or null

SessionPlanItem

Name	Description
content String
status Enum (canceled, completed, in_progress, pending)

SignalMetadata

Metadata for the signal: a url for auth, options for select.

Name	Description
options Array [SignalOption]
url String

SignalOption

Name	Description
label String
value String

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	The Members who followers of the Doc.
formatted_vcs_branch_name String or null	The suggested Git branch name for the Story, built from the Workspace’s branch name format. Null if the Workspace has no branch name format.
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	The Members who followers of the Doc.
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	The Members who followers of the Doc.
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	The Member who created the Doc.
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.

StoryHistoryChange

A single history change entry.

Name	Description
action String	The type of action: create, update, or delete.
actor	The actor who made this change (slim representation): a member:slim, or a vcs-identity:slim for changes driven by an external VCS identity. Null when no actor can be resolved.
adds Array []	Values that were added.
attribute String	The attribute that was changed.
entity	The story that was changed (slim representation).
removes Array []	Values that were removed.
timestamp Date	When this change occurred.
tx_id UUID	The unique identifier for the transaction.

StoryHistoryResponseWrapper

Response wrapper for story history.

Name	Description
$schema String	The URI of the JSON schema for this response.
changes Array [StoryHistoryChange]	The list of change entries, ordered chronologically by the instant each change occurred (ascending by default; descending with order_dir=desc) across all attributes. Entries at the same instant are ordered deterministically by attribute, in the same tie-break order in both directions. Ordering is stable across pages.
current_items Integer	The number of items on this page.
current_page Integer	The current page number.
next_page_url String	URL to fetch the next page, if available.
total_items Integer	The total number of 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.

Subscription

Name	Description
enabled Boolean
enabled_after_t Integer
enabled_at Date
installation_id UUID
workspace_id UUID

Team

Name	Description
app_url String (2048)	The Shortcut application url for the Team.
archived Boolean	True if the Team has been archived.
card_aging_mode Enum (gradual, immediate, off) or null	The card aging mode for stories in this Team: “gradual” or “immediate”. Null if card aging is off.
card_aging_threshold_days Integer or null	The number of days an in-progress Story can go without activity before it is considered stale.
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	The Members who followers of the Doc.
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	The Member who created the Doc.
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	The Members who followers of the Doc.
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 or null	The email address of the Member this Token belongs to. Null if the Member was removed from the Organization.
entity_type Enum (token)	The type of this entity.
expires_at Date or null	The time/date the Token expires. Null if it never expires.
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	The Member who created the Doc.
scopes Array [String] or null	The scopes granted to this token. Possible values: “read”, “write”, “story-write”, “comment-write”, “admin”. Null for legacy tokens.
status Enum (active, disabled, expired, owner_removed)	Whether the Token can authenticate. “active”: it can. “disabled”: the Token was disabled. “owner_removed”: the Member it belongs to was removed from the Workspace or Organization; it works again if they are restored. “expired”: the Token is past its expiration date. When several apply, the first in the order disabled, owner_removed, expired is reported.
token_type Enum (legacy, v4)	The format of the Token: “legacy” or “v4”.
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

Why v4

Built for agents

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

Agent-Sessions

List Agent Sessions

URL Parameters

URL Query Parameters

Responses

Create Agent Session

URL Parameters

Body Parameters

Responses

Subscribe to Agent Sessions

URL Parameters

Body Parameters

Responses

Get Agent Session

URL Parameters

Responses

Update Agent Session

URL Parameters

Body Parameters

Responses

List Agent Activities

URL Parameters

URL Query Parameters

Responses

Create Agent Activity

URL Parameters

Body Parameters

Responses

Get Agent Session Context

URL Parameters

Responses

Prompt Agent Session

URL Parameters

Body 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