> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/issue-trackers/shortcut.md). # Shortcut {% hint style="warning" %} The Shortcut integration is currently in **beta**. {% endhint %} Swarmia connects to Shortcut with an API token. Once connected, your stories and epics sync automatically, so you can see them next to the commits and pull requests that delivered them. A Shortcut API token is scoped to a single workspace, so the token you paste decides which workspace Swarmia syncs. There's nothing else to pick. Issue types and statuses map automatically. ## Before you start You need the [admin role](/settings/organization/managing-users-and-roles.md) in Swarmia to connect an issue tracker. {% hint style="info" %} **Recommended: create the token with a service account** A Shortcut API token stops working when the member who created it is deactivated, and syncing stops with it. Create the token from a dedicated member account (for example, `integrations@yourcompany.com`) so the connection doesn't depend on any one person. {% endhint %} ## Step 1: Create the API token in Shortcut 1. Open [API tokens](https://app.shortcut.com/settings/account/api-tokens) in your Shortcut account settings. 2. Name the token and give it permission to read all workspace data. 3. Copy the token before closing the dialog. ## Step 2: Connect Shortcut in Swarmia 1. Go to [issue tracker settings](https://app.swarmia.com/settings/issue-trackers), click **Connect**, and choose **Connect Shortcut**. 2. Paste the token and click **Connect**. Swarmia validates the token against Shortcut, stores it encrypted, and starts syncing. The first sync covers every epic in the workspace and the stories updated during the past year. You can connect one Shortcut workspace per Swarmia organization. ## Step 3: Assign Shortcut teams to Swarmia teams Your Shortcut Teams sync to Swarmia, and you assign them to Swarmia teams in [Settings → Team → Issues](https://app.swarmia.com/settings/team/issues). Do this for every team: a team's Shortcut work shows up in Swarmia only after you've assigned it. Read more about [issue ownership](/settings/team/issue-ownership.md). ## Linking pull requests to stories Every Shortcut story and epic gets the issue key `SC-`, the same key Shortcut uses in the branch names it generates. Branches and pull requests that mention the key are linked to the story automatically. See [linking pull requests to issues](/settings/organization/linking-pull-requests-to-issues.md) for all the ways Swarmia detects a link. ## Keeping the data up to date Swarmia keeps your Shortcut data in sync automatically — there's nothing to maintain. When you create or update a story or epic in Shortcut, the change shows up in Swarmia within an hour. Changes to your Shortcut Teams and workflows take a bit longer. ## When the token stops working If the token is revoked or its Shortcut account is deactivated, syncing stops and your Swarmia admins get an email about it. The workspace shows as Disconnected in [issue tracker settings](https://app.swarmia.com/settings/issue-trackers), where you can reconnect it with a new token. The new token has to belong to the same Shortcut workspace. A token for a different workspace is rejected, because reconnecting rotates the token of an existing connection rather than creating a second one. ## How do I disconnect Shortcut? Contact us at and we'll disconnect the workspace for you. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.swarmia.com/settings/integrations/issue-trackers/shortcut.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.