canonical: https://jentic.com/apis/clubhouse.io/clubhouse

# Clubhouse Shortcut API

The Shortcut API (formerly Clubhouse) is the integration surface for the Shortcut project management platform used by software teams. It exposes endpoints for stories, epics, iterations, objectives, projects, workflows, members, custom fields, documents, files, labels, and webhooks. Authentication uses a Shortcut-Token header API key, and the API covers the full lifecycle of agile work - creating stories, attaching them to epics and iterations, moving them through workflow states, adding comments and tasks, and linking related documents.

## For AI agents

Manage Shortcut software project work - create stories and epics, move work through iterations and workflows, add comments and tasks, and search across the workspace.

## Scope

Does not handle source-control commits, CI builds, or chat messaging - use for Shortcut project, story, epic, and iteration management only.

## Capabilities

- Create, update, and search stories with epics, iterations, labels, and custom fields
- Manage epics, milestones, objectives, and iterations across the project hierarchy
- Move stories through workflow states and assign owners
- Add comments, tasks, and file attachments to existing stories
- Manage members, groups, teams, and workspace categories
- Create and link Shortcut docs to epics and stories

## Use cases

### Automated Story Creation From Bug Reports

Customer support teams that receive bug reports through email, chat, or a third-party tool create Shortcut stories automatically rather than copying details by hand. POST `/api/v3/stories` accepts a name, description, project ID, owner IDs, and labels, and returns the story object including its public URL. Pairing this with a custom field for the source of the report keeps the connection back to the originating ticket and removes a manual step from triage.

Example prompt: Create a story titled 'Login fails on Safari 17' in project ID 5 with the bug label and owner ID set to the on-call engineer via POST `/api/v3/stories`

### Cross-Tool Status Sync With Source Control

Engineering teams keep Shortcut stories in sync with pull request status by listening on a source-control webhook and calling the Shortcut API. PUT `/api/v3/stories/{story-public-id}` moves the story between workflow states based on PR events, and POST `/api/v3/stories/{story-public-id}/comments` adds a comment when the PR is merged. The 143-endpoint surface covers all the supporting reads - workflow states, members, projects - so a status sync can be wired up without going outside the API.

Example prompt: When a GitHub PR mentioning sc-1234 is merged, look up workflow state ID for 'Done' via GET `/api/v3/workflows` then PUT `/api/v3/stories/1234` to move the story to that state

### Sprint Reporting and Iteration Insights

Engineering managers want sprint summaries that go beyond Shortcut's built-in views. The API exposes `/api/v3/iterations` endpoints to list iterations and their stories, `/api/v3/stories/search` for scoped queries, and `/api/v3/epics` for higher-level rollups. A scheduled job can build a weekly sprint readout including velocity, scope changes, and at-risk stories, posted to a chat channel as part of the team's regular cadence.

Example prompt: List iterations via GET `/api/v3/iterations`, pick the active one, then call GET `/api/v3/iterations/{id}/stories` to compute completed vs remaining story count

### AI Agent Triaging Work in Shortcut via Jentic

AI agents working in product engineering can call Shortcut through Jentic to triage incoming bugs, file follow-up stories from a code review, or post status updates back to a story. The agent expresses an intent like 'create a story' or 'add a comment to a story', Jentic loads the matching Shortcut operation and supplies the Shortcut-Token from the vault, and returns the structured response so the agent can take the next step without browsing developer.shortcut.com.

Example prompt: Through Jentic, search for 'create a story', load the clubhouse.io `/api/v3/stories` operation, and execute it for a user-reported bug with name, description, and project ID

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v3/stories` | Create a story |
| GET | `/api/v3/stories/search` | Search stories |
| POST | `/api/v3/epics` | Create an epic |
| GET | `/api/v3/iterations` | List iterations |
| GET | `/api/v3/workflows` | List workflows and their states |
| POST | `/api/v3/documents` | Create a Shortcut doc |
| GET | `/api/v3/members` | List workspace members |

## Key resources

- **Stories** — Create, update, search, and comment on individual work items
- **Epics** — Group related stories and track higher-level initiatives
- **Iterations** — Sprint-style time boxes that contain stories
- **Objectives and Milestones** — Higher-level goals spanning multiple epics
- **Projects** — Long-running buckets of work above the iteration
- **Workflows** — State machines that stories progress through
- **Members and Groups** — Workspace users, teams, and group memberships
- **Documents** — Shortcut docs that can be linked to epics and stories
- **Custom Fields** — User-defined fields attached to stories
- **Categories and Labels** — Tagging mechanisms for cross-cutting filtering

## Why Jentic

- **Setup:** Wiring Shortcut by hand means learning its Shortcut-Token header auth, targeting api.app.shortcut.com, and handling paging and retries across a large project-management 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 works over collection endpoints for stories, epics, and iterations, so scope the agent to the operations it needs, such as searching stories or listing workflows. You choose that set, so write operations like creating a story or an epic are not included unless you add them.
- **Credential handling:** Your Shortcut token is stored once, encrypted, by your own Jentic One instance and injected into the Shortcut-Token header 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 'move a story to done', and Jentic returns the matching Shortcut operation with its input schema so the agent calls the right endpoint without reading developer.shortcut.com.

## Related APIs

- **Linear API** — Linear is a directly comparable issue tracker for software teams with stories, projects, and cycles
- **Asana API** — Asana is a broader work management platform covering tasks, projects, and goals across teams beyond engineering
- **GitHub API** — GitHub holds the source code and pull requests that Shortcut stories track in the workflow

## FAQ

### What authentication does the Shortcut API use?

The Shortcut API uses an apiKey scheme with the token passed in a Shortcut-Token header. Tokens are generated from the Shortcut workspace settings. Through Jentic the token is stored encrypted in the vault and added to the header only at execution time, so it never appears in the agent context.

### Can I create and update stories with the Shortcut API?

Yes. POST `/api/v3/stories` creates a story with name, description, project, owners, labels, and custom field values. PUT `/api/v3/stories/{story-public-id}` updates any of those fields plus workflow state, and POST `/api/v3/stories/{story-public-id}/comments` adds a comment to an existing story.

### How do I find stories matching a query through the Shortcut API?

Use GET `/api/v3/stories/search` with a Shortcut search expression in the query parameter. The same expressions used in the Shortcut web UI search bar work here, including filters by project, epic, owner, and state.

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

Shortcut applies a workspace-level rate limit and returns standard HTTP 429 when exceeded; the OpenAPI specification does not formally declare the threshold but the limit and current usage are surfaced in response headers. High-volume callers should batch reads via the search endpoints rather than fetching one story at a time.

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

Install the SDK with pip install jentic, search for 'create a story', load the clubhouse.io `/api/v3/stories` operation, and execute it with the story name, description, and project_id. Jentic supplies the Shortcut-Token header automatically and returns the new story including its public URL.

### Can I move stories through workflow states with the Shortcut API?

Yes. List workflows via GET `/api/v3/workflows` to discover the state IDs for each workflow, then call PUT `/api/v3/stories/{story-public-id}` with workflow_state_id set to the target state. This is the standard pattern for syncing Shortcut state with PR or build events.

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

Yes. Because you run Jentic One yourself, your own rules decide exactly which Shortcut operations and credentials the agent may use. You can scope it to read-only calls such as searching stories via GET `/api/v3/stories/search` or listing workflow states via GET `/api/v3/workflows`, and leave out write operations like creating a story with POST `/api/v3/stories` or an epic with POST `/api/v3/epics` unless you add them. The Shortcut-Token is held by your instance and injected only at execution time, so the agent can call only the operations you have granted.