> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/shortcut.md).

# Shortcut

Create and manage stories in Shortcut, the project management platform for software teams.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| Shortcut  | API Token      |

### Shortcut

Connect to Shortcut with a workspace API token to create and manage stories.

#### Set up in Shortcut

1. Prepare the Shortcut account or service that the workflow will access. Grant access to the required resources and operations.
2. **API Token:** Shortcut API token for your workspace. Create one in Shortcut under Settings > Account > API Tokens.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **Shortcut**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                       |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Token     | Yes      | Shortcut API token for your workspace. Create one in Shortcut under Settings > Account > API Tokens. [Provider instructions](https://app.shortcut.com/settings/account/api-tokens). |

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **Shortcut** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### Create Story

Create a new story in Shortcut.

#### Inputs

| Field          | Type            | Required | Description                                                                                                |
| -------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| Name           | string          | Yes      | The story's title (max 512 characters).                                                                    |
| Description    | textarea        | No       | Optional details about the story.                                                                          |
| Story Type     | select (string) | No       | The kind of story: feature, bug, or chore. Available values: Feature, Bug, Chore. Default: feature.        |
| Workflow State | select (string) | No       | Select a workflow state, or type its numeric ID manually. Options load from the selected connection.       |
| Epic           | select (string) | No       | Select an epic to attach this story to, or type its numeric ID. Options load from the selected connection. |
| Deadline       | datetime        | No       | Optional due date for the story.                                                                           |

#### Outputs

| Field             | Type    | Description                                                |
| ----------------- | ------- | ---------------------------------------------------------- |
| Story ID          | integer | The numeric ID of the created story, for downstream nodes. |
| Name              | string  | The story's title.                                         |
| Story URL         | string  | Link to the story in the Shortcut web app.                 |
| Story Type        | string  | The story's type: feature, bug, or chore.                  |
| Workflow State ID | integer | The numeric ID of the story's current workflow state.      |
| Epic ID           | integer | The numeric ID of the epic this story belongs to, if any.  |
| Deadline          | string  | The story's due date, if set.                              |
| Created At        | string  | When the story was created.                                |
| Result Message    | string  | Human-readable result summary.                             |

### Search Stories

Search for stories in Shortcut using search operators.

#### Inputs

| Field            | Type    | Required | Description                                                            |
| ---------------- | ------- | -------- | ---------------------------------------------------------------------- |
| Query            | string  | Yes      | Shortcut search query using search operators.                          |
| Page Size        | integer | No       | Number of stories to return per page (max 100).                        |
| Next Page Cursor | string  | No       | Cursor from a previous search's 'next' output, to fetch the next page. |

#### Outputs

| Field            | Type    | Description                                                             |
| ---------------- | ------- | ----------------------------------------------------------------------- |
| Stories          | array   | The stories matching the search query on this page.                     |
| Next Page Cursor | string  | Cursor for the next page of results, or empty if this is the last page. |
| Story IDs        | array   | Numeric IDs of the matching stories, for downstream nodes.              |
| Stories Count    | integer | Number of stories returned on this page.                                |
| Result Message   | string  | Human-readable result summary.                                          |

### Get Story

Fetch a single story from Shortcut by its ID.

#### Inputs

| Field    | Type   | Required | Description                           |
| -------- | ------ | -------- | ------------------------------------- |
| Story ID | string | Yes      | The numeric ID of the story to fetch. |

#### Outputs

| Field             | Type    | Description                                               |
| ----------------- | ------- | --------------------------------------------------------- |
| Story ID          | integer | The numeric ID of the story, for downstream nodes.        |
| Name              | string  | The story's title.                                        |
| Story URL         | string  | Link to the story in the Shortcut web app.                |
| Story Type        | string  | The story's type: feature, bug, or chore.                 |
| Workflow State ID | integer | The numeric ID of the story's current workflow state.     |
| Epic ID           | integer | The numeric ID of the epic this story belongs to, if any. |
| Description       | string  | The story's description, if any.                          |
| Deadline          | string  | The story's due date, if set.                             |
| Estimate          | integer | The story's point estimate, if set.                       |
| Archived          | boolean | Whether the story is archived.                            |
| Created At        | string  | When the story was created.                               |
| Updated At        | string  | When the story was last updated.                          |
| Result Message    | string  | Human-readable result summary.                            |

### Update Story

Update a story in Shortcut. Only the fields you set are changed.

#### Inputs

| Field          | Type            | Required | Description                                                                                                          |
| -------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| Story ID       | string          | Yes      | The numeric ID of the story to update.                                                                               |
| Name           | string          | No       | New title for the story. Leave blank to keep the current title.                                                      |
| Description    | textarea        | No       | New description. Replaces the current description; leave blank to keep it.                                           |
| Story Type     | select (string) | No       | New story type: feature, bug, or chore. Leave blank to keep the current type. Available values: Feature, Bug, Chore. |
| Workflow State | select (string) | No       | Move the story to a different workflow state, or type its numeric ID. Options load from the selected connection.     |
| Epic           | select (string) | No       | Attach the story to a different epic, or type its numeric ID. Options load from the selected connection.             |
| Deadline       | datetime        | No       | New due date for the story. Leave blank to keep the current deadline.                                                |
| Archived       | boolean         | No       | Archive or unarchive the story. Leave blank to keep its current state.                                               |
| Estimate       | integer         | No       | New point estimate for the story. Leave blank to keep the current estimate.                                          |
| Labels         | string          | No       | Comma-separated label names.                                                                                         |

#### Outputs

| Field             | Type    | Description                                                |
| ----------------- | ------- | ---------------------------------------------------------- |
| Story ID          | integer | The numeric ID of the updated story, for downstream nodes. |
| Name              | string  | The story's current title.                                 |
| Story URL         | string  | Link to the story in the Shortcut web app.                 |
| Story Type        | string  | The story's current type: feature, bug, or chore.          |
| Workflow State ID | integer | The numeric ID of the story's current workflow state.      |
| Epic ID           | integer | The numeric ID of the epic this story belongs to, if any.  |
| Archived          | boolean | Whether the story is archived after the update.            |
| Updated At        | string  | When the story was last updated.                           |
| Result Message    | string  | Human-readable result summary.                             |

### Create Epic

Create a new epic in Shortcut.

#### Inputs

| Field       | Type     | Required | Description                      |
| ----------- | -------- | -------- | -------------------------------- |
| Name        | string   | Yes      | The epic's title.                |
| Description | textarea | No       | Optional details about the epic. |

#### Outputs

| Field          | Type    | Description                                               |
| -------------- | ------- | --------------------------------------------------------- |
| Epic ID        | integer | The numeric ID of the created epic, for downstream nodes. |
| Name           | string  | The epic's title.                                         |
| Description    | string  | The epic's description, if any.                           |
| Epic URL       | string  | Link to the epic in the Shortcut web app.                 |
| Archived       | boolean | Whether the epic is archived.                             |
| Created At     | string  | When the epic was created.                                |
| Result Message | string  | Human-readable result summary.                            |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/shortcut.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
