CoIsland
Download
esc
↑↓ move↵ openesc close
Connectors · Issues & docs

Connect Shortcut

Set up with your AI

Know when a story lands on you, moves to review, or an iteration is about to end with work still open.

You need
API token Settings › Your Account › API Tokens
The form asks
  • Connector name
  • API token
You can watch
  • Stories
  • Entered a state
  • Iteration ending
Access
GET requests only; it never moves or edits a story
On this page

To connect Shortcut to CoIsland you need one thing: an API token you generate under your own Shortcut account. No admin, no app to register, no OAuth. CoIsland calls Shortcut’s REST API straight from your Mac, keeps the token in your login Keychain, and only ever reads.

Generate a Shortcut API token

  1. In Shortcut, open Settings, then Your Account, then API Tokens.
  2. Enter a name, such as CoIsland, and select Generate Token.
  3. Copy the token now.

A token belongs to you and to one workspace: it stops working if you leave that workspace. It acts with your permissions; an Observer’s token may be refused by Shortcut’s API.

Connect Shortcut in CoIsland

Open Settings › Connectors, click +, and choose Shortcut.

Field What to enter
Connector name What monitors call it: shortcut. Letters, digits, _ and -.
API token The token you generated.

Test connector calls GET /api/v3/member and shows your name, mention name and workspace. It saves nothing. The token is kept in your login Keychain and only ever sent to https://api.app.shortcut.com, in the Shortcut-Token header.

Choose what to watch: the three Shortcut monitor kinds

Stories

Any search in Shortcut’s own operators, as in its search bar. A story alerts when it starts matching. owner:me and requester:me are you: CoIsland writes your mention name in their place at each check. Shortcut returns the first 1,000 matches.

owner:me !is:done !is:archived

Entered a state

A story alerts when it moves into the workflow state you pick, within within: (1d, 3d, 7d or 14d; 7d unless given), and again if it leaves and comes back. The state is picked by name and saved by its ID, so another workflow’s state of the same name does not count.

state:500000011 within:7d

Iteration ending

A started iteration alerts once when its end falls within within: (1d, 2d, 3d or 7d). It checks every hour by default.

within:2d

What a Shortcut alert shows

The notch lists a story as sc-123 · In Development · Ana Silva · Due 25 Sept, and an iteration as Iteration · Ends 23 Sept · 3 open · 8 done. Clicking opens the alert in CoIsland: a story’s description and latest comments, its owners, requester, type, estimate and deadline; an iteration’s stories still open. Open in Shortcut goes to it.

What a Shortcut monitor’s watch file looks like

-- name: My open stories
-- kind: shortcut.stories
-- connector: shortcut
-- alert: new-rows

owner:me !is:done !is:archived

The kinds are shortcut.stories, shortcut.state and shortcut.iteration.

Rate limits

Shortcut allows 200 requests a minute per token. A stories check costs one request per 100 stories plus two to read the workspace’s states and members’ names. When Shortcut asks CoIsland to slow down, checks back off on their own.

Troubleshooting Shortcut connector errors

  • The token was refused. Shortcut answered 401: the token was deleted, or you were removed from the workspace. Generate a new one.
  • Shortcut did not allow this for the token’s member. Shortcut answered 403, as it does for an Observer.
  • Shortcut refused the request: then Shortcut’s words, such as a search it cannot read.
  • No workflow state … in this workspace. The state was deleted; pick it again.
  • This story no longer exists in Shortcut, or the token cannot see it. The alert keeps the story as it was.

Stuck? Open an issue on GitHub, or write to hello@coisland.app.

Docs