Community OpenAPI document · agent-readyDeveloper ToolsProject ManagementapiKey123 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For 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.
Use for: I need to create a new story in Shortcut, Search for stories assigned to a specific member, Update a story workflow state to in-progress, List all open epics in a workspace
Not supported: Does not handle source code hosting, CI/CD, or chat messaging - use for managing Shortcut stories, epics, iterations, and search only.
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.
Install Jentic One Beta
Connect the Shortcut API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Shortcut API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapp.shortcut.com%2Fshortcut" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapp.shortcut.com%2Fshortcut" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Shortcut API.
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
Patterns agents use Shortcut API for, with concrete tasks.
★ 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.
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.
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.
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.
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.
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
123 endpoints — 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.
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
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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
S
Shortcut API
- Foundational (C+)57/100
89
Foundational Compliance63
Developer Experience & Jentic Compatibility35
AI-Readiness & Agent Experience78
Agent Usability50
Security100
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
89
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: ASignals: 4
94%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
100%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
60%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
63
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: B-Signals: 4
0%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
50%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
35
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
79%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
0%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
63%
Summary Coverage
Coverage of summaries across operations/tags/info.
78
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A-Signals: 1
78%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
50
Security
Trust, risk posture, and security compliance.
Grade: C-Signals: 1
50%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
100
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A+Signals: 1
100%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Shortcut API through Jentic.
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.
GET STARTED