canonical: https://jentic.com/apis/app.shortcut.com/shortcut

# Shortcut API

The Shortcut API gives engineering teams programmatic control over the issue tracker behind their planning workflow, covering stories, epics, iterations, milestones, objectives, projects, workflows, and members. The 123 endpoints span search, comment threads, custom fields, key results, repository links, and entity templates so external automations can drive sprint planning end to end. Authentication uses the Shortcut-Token header, and the API exposes a search operation that mirrors the in-app filter language.

## For AI agents

Create stories, manage epics and iterations, search the workspace, and update workflow states so an agent can run sprint planning and triage from outside the Shortcut UI.

## Scope

Does not handle source code hosting, CI/CD, or chat messaging - use for managing Shortcut stories, epics, iterations, and search only.

## Capabilities

- Create and update stories via `/api/v3/stories` with workflow state and assignee fields
- Manage epics, iterations, and milestones for higher-level planning
- Search the workspace using Shortcut's filter language via `/api/v3/search`
- Comment on epics and stories programmatically
- Link repositories and external pull requests to stories
- Manage custom fields and entity templates for repeatable workflows
- List groups and members to assign work and audit team load

## Use cases

### Inbound Bug Triage Automation

Convert customer-reported bugs into Shortcut stories automatically by calling POST `/api/v3/stories` with the bug description, label, and the right project ID. The triage agent watches the support inbox, dedupes against existing open stories via `/api/v3/search`, and assigns the new story to the on-call engineer through the workflow_state_id field. This removes the manual copy-paste from Zendesk or Slack into Shortcut.

Example prompt: On a new bug ticket, search Shortcut via POST `/api/v3/search` for matching stories, and if none exist call POST `/api/v3/stories` with the bug summary, label 'bug', and the on-call assignee

### Iteration Planning Reports

Generate a weekly iteration plan report by listing `/api/v3/iterations` and walking each iteration's stories to summarise points, owners, and workflow states. The report can be posted to Slack at the start of the sprint so the team has a single canonical view of committed work, removing the need to browse Shortcut filters manually.

Example prompt: List active iterations via GET `/api/v3/iterations`, for each iteration enumerate stories via `/api/v3/iterations/{id}/stories`, and post a summary to the team's Slack channel

### Repository and Deployment Linkage

Attach commit and deployment context to stories by creating external links via `/api/v3/external-link/stories` whenever a CI run completes. The agent reads the commit message for a story-id reference, calls the linkage endpoint, and posts a comment via `/api/v3/stories/{id}/comments` with the deployment status, giving PMs a single place to see whether a story has shipped.

Example prompt: Parse the story ID from the merge commit, call POST `/api/v3/external-link/stories` with the deploy URL, and add a comment confirming the deploy timestamp

### Custom Field Workflow Enforcement

Enforce process rules by creating and validating custom fields on stories - for example, requiring a 'Customer Impact' selection on every bug. The agent reads `/api/v3/custom-fields`, then on every new story checks whether the required field is populated and posts a comment if it is missing, removing the need for human reviewers to police story hygiene.

Example prompt: List `/api/v3/custom-fields`, then for every newly created story confirm the 'Customer Impact' field is populated and otherwise add a comment requesting it

### Agent-Driven Planning Assistant

Let an AI assistant create and update Shortcut stories from natural-language messages by searching Jentic for 'create a shortcut story', loading the operation schema, and executing. The agent never holds the Shortcut-Token header value, which matters because Shortcut tokens carry write access to the entire workspace.

Example prompt: Search Jentic for 'create a shortcut story', load POST `/api/v3/stories` schema, and execute with the title and description from the user's chat message

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v3/stories` | Create a story |
| GET | `/api/v3/stories/{story-public-id}` | Fetch a specific story |
| POST | `/api/v3/search` | Search the workspace |
| GET | `/api/v3/epics` | List epics |
| POST | `/api/v3/epics/{epic-public-id}/comments` | Comment on an epic |
| GET | `/api/v3/iterations` | List iterations |
| POST | `/api/v3/external-link/stories` | Link external URLs to stories |
| GET | `/api/v3/workflows` | List workflow definitions |

## Key resources

- **Stories** — Create, list, update, and comment on stories - the core unit of work
- **Epics** — Group stories into higher-level epics with their own comment threads
- **Iterations** — Define sprint-style iterations and pull stories within each
- **Search** — Query the workspace using Shortcut's filter language
- **Workflows** — Read workflow definitions and move stories between states
- **Members and Groups** — List members and groups for assignment and ownership

## Why Jentic

- **Setup:** Wiring Shortcut by hand means learning its Shortcut-Token header scheme and its story filter language across a large story, epic, and iteration surface yourself. Through Jentic you install once, import the Shortcut API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Shortcut puts story and epic ids in the URL path (`/api/v3/stories/{story-public-id}`, `/api/v3/epics/{epic-public-id}/comments`), so a rule can pin your agent to specific stories or epics. You choose the operations it may call, so creating stories or posting external links is not included unless you add it.
- **Credential handling:** Your Shortcut token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a story' or 'search for stories in an iteration', and Jentic returns the matching Shortcut operation with its input schema so the agent calls the right endpoint without learning Shortcut's filter language up front.

## Related APIs

- **Linear API** — Linear is a streamlined issue tracker focused on speed and keyboard workflows
- **Asana API** — Asana focuses on cross-functional project tracking beyond engineering
- **GitHub API** — GitHub holds the source code; Shortcut holds the planning context - link them via external-link/stories
- **ClickUp API** — ClickUp covers tasks, docs, and goals across the company beyond engineering

## FAQ

### What authentication does the Shortcut API use?

API key in the Shortcut-Token header. Tokens are issued from the Shortcut user settings page. Through Jentic the token is stored encrypted in the vault (your Jentic One instance) and never enters agent context - agents receive scoped access only.

### Can I create a story with the Shortcut API?

Yes. POST `/api/v3/stories` creates a story with title, description, project_id, workflow_state_id, and optional epic_id, iteration_id, and labels. The response returns the story's public ID for follow-up calls.

### What are the rate limits for the Shortcut API?

The OpenAPI spec does not encode explicit rate limits. Shortcut publicly documents a 200-request-per-minute soft limit per token; sustained over-limit traffic returns HTTP 429. Inspect the X-RateLimit headers in responses for live state.

### How do I create a story through Jentic?

Run pip install jentic, then search 'create a shortcut story'. Jentic returns POST `/api/v3/stories` with its input schema - load the schema, populate name and project_id, and execute. The agent never sees the Shortcut-Token value.

### How do I search across the workspace?

POST `/api/v3/search` accepts a query string in Shortcut's filter language (e.g. 'is:story owner:foo state:in-progress') and returns matching stories, epics, and iterations. Search is the recommended way to dedupe before creating new stories.

### Can I link external pull requests to a story?

Yes. POST `/api/v3/external-link/stories` registers an external URL against one or more stories. Combined with `/api/v3/stories/{id}/comments` this is the typical pattern for surfacing CI/CD status inside the story timeline.

### Can I limit what my agent is allowed to do with the Shortcut API?

Yes. Jentic One runs self-hosted, so your own rules decide which Shortcut operations and which stored credential the agent may use. Because Shortcut puts story and epic ids in the URL path, such as `/api/v3/stories/{story-public-id}` and `/api/v3/epics/{epic-public-id}/comments`, you can pin the agent to specific stories or epics. You also choose the operations it may call, so creating stories via POST `/api/v3/stories` or posting external links via POST `/api/v3/external-link/stories` is excluded unless you add it.