Shortcut API

Name: Shortcut API API
Brand: Shortcut API
Availability: InStock

✓ Official Vendor SpecDeveloper ToolsProject ManagementapiKey143 EndpointsREST

For 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.

Quickstart

Get started with Shortcut API in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"create a story in shortcut"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

Capabilities

What an agent can do with Shortcut API API.

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

GET STARTED

Start building with Shortcut API API

Explore with Jentic

View OpenAPI Document

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.

Use Cases

Patterns agents use Shortcut API API for, with concrete tasks.

★ 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.

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.

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.

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.

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

143 endpoints — the shortcut api (formerly clubhouse) is the integration surface for the shortcut project management platform used by software teams.

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

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

Why though Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

The Shortcut-Token API key is stored encrypted in the Jentic vault (MAXsystem) and injected into the Shortcut-Token header only at execution time. The agent never sees the raw token, and it is not written into prompt history.

Intent-based discovery

Agents search by intent (e.g. 'create a story', 'move a story to done') and Jentic returns the matching Shortcut operation with its input schema, so the agent can call /api/v3/stories or /api/v3/workflows without reading developer.shortcut.com.

Time to first call

Direct Shortcut integration: 1-2 days to wire up create/update for stories, plus workflow state lookups and webhook signature verification. Through Jentic: under 1 hour — search, load, execute.

Related APIs

Alternatives and complements available in the Jentic catalogue.

Alternative

Linear API

Linear is a directly comparable issue tracker for software teams with stories, projects, and cycles

Choose Linear for teams already on its UI; choose Shortcut when the workspace already uses its iteration and epic model

Alternative

Asana API

Asana is a broader work management platform covering tasks, projects, and goals across teams beyond engineering

Choose Asana for cross-functional work tracking; choose Shortcut when the workflow is engineering-centric with epics and iterations

Complementary

GitHub API

GitHub holds the source code and pull requests that Shortcut stories track in the workflow

Use GitHub to read PR status and merges, then call Shortcut PUT /api/v3/stories to update the story's workflow state

FAQs

Specific to using Shortcut API API through Jentic.

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.