VX Agents

API directory · Productivity & Project Management

Shortcut Stories, Epics & Iterations

v1.0.0 · 14 endpoints · 0 connections · shared by vx.ai

Run sprint check-ins in Shortcut: search stories with the same query syntax as the app (owner:, state:, iteration:), see what is left in the current iteration or an epic, file new stories, move them through workflow states and leave comments.

Connect this API to an AI agent Browse all specs

What you can do with Shortcut Stories, Epics & Iterations via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /api/v3/member getCurrentMember Get the token owner's member id and workspace
GET /api/v3/members listMembers List workspace members (to find owner ids)
GET /api/v3/workflows listWorkflows List workflows and their states (Backlog, In Progress, Done)
GET /api/v3/groups listTeams List teams
GET /api/v3/search/stories searchStories Search stories with Shortcut search syntax
GET /api/v3/stories/{story-public-id} getStory Get a story with its description, state, owners and tasks
PUT /api/v3/stories/{story-public-id} updateStory Move a story to another state, iteration or owner, or edit it
POST /api/v3/stories createStory Create a story (feature, bug or chore)
GET /api/v3/stories/{story-public-id}/comments listStoryComments List comments on a story
POST /api/v3/stories/{story-public-id}/comments createStoryComment Comment on a story
GET /api/v3/epics listEpics List epics with their state and progress
GET /api/v3/epics/{epic-public-id}/stories listEpicStories List the stories in an epic
GET /api/v3/iterations listIterations List iterations (sprints) with dates and status
GET /api/v3/iterations/{iteration-public-id}/stories listIterationStories List the stories in an iteration

Authentication

shortcutToken

API key — sent as the Shortcut-Token header

Shortcut API token sent in the Shortcut-Token header.

How to get a credential

  1. In Shortcut, open Settings > Your Account > API Tokens (app.shortcut.com/settings/account/api-tokens).
  2. Enter a name (e.g. VX Agents) and click Generate Token.
  3. Copy the token; Shortcut shows it only once.

Permissions used

Tokens are per user and per workspace and act with that member's role.

Role needed Operations
Observer or above (read) getCurrentMember, listMembers, listWorkflows, listTeams, searchStories, getStory, listStoryComments, listEpics, listEpicStories, listIterations, listIterationStories
Member or above (write) createStory, updateStory, createStoryComment

Common errors

  • 401 Unauthorized: token missing, revoked or for another workspace. Generate a new token in the right workspace.
  • 403 Forbidden: the member is an Observer and tried to write.
  • 400 / 422: invalid body, e.g. an unknown workflow_state_id, or a story without name or a team/workflow state.
  • 429 Too Many Requests: limit is 200 requests per minute per token; wait a minute and retry.

Store the token as a VX Agents credential so it is never pasted into chat.

Usage guide

Setup

  • Add an API key credential: a Shortcut API token (Settings > Your Account > API Tokens), sent in the Shortcut-Token header. The token is tied to one workspace and acts as you.
  • Call getCurrentMember once for your member id (a UUID) and listWorkflows for the state ids (workflow_state_id) of Backlog, In Progress, Done and so on. Pin your team's group_id (from listTeams) if you always file stories there.

Sprint check-in

  1. listIterations and pick the one with status: started (or search iteration:"Sprint 42").
  2. listIterationStories with its id, or searchStories with a query such as owner:jane state:"In Progress", type:bug label:urgent or epic:"Billing revamp". Use detail=slim for shorter results and a small page_size; follow next for more.
  3. getStory for the description, tasks, owners and links; listStoryComments for the discussion.
  4. listEpics / listEpicStories to report progress on a larger piece of work.

Make changes

Show the user what will change and wait for confirmation first.

  • New story: createStory with name (required) plus story_type (feature, bug, chore), description (Markdown), workflow_state_id or group_id, owner_ids, iteration_id, epic_id, estimate, labels: [{"name": "urgent"}].
  • Move or reassign: updateStory with only the fields that change, e.g. {"workflow_state_id": 500000008} or {"owner_ids": ["<member uuid>"], "iteration_id": 1234}.
  • Comment: createStoryComment with text (Markdown).

Good to know

  • Story, epic and iteration ids are integers (the number in app.shortcut.com/<workspace>/story/1234); member and team ids are UUIDs.
  • Dates are ISO 8601 UTC.
  • Search queries use the same operators as the Shortcut search bar.
  • Rate limit is 200 requests per minute per token.
  • This spec cannot delete stories, epics or iterations.

Source: Shortcut REST API v3 reference (https://developer.shortcut.com/api/rest/v3), checked 2026-10-21.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Shortcut Stories, Epics & Iterations” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs

  • Notion Pages & Databases — Before stand-up, pull this week's open tasks from a Notion data source with filters and sorts, read the spec page behin…
  • Jira Issues — Lets an agent work Jira Cloud issues: search with JQL, read issues and comments, create and edit issues, assign them, c…
  • Smartsheet Sheets & Rows — For teams that run projects in Smartsheet: find a sheet, read its rows and columns, add or update rows by column id, an…
  • Asana Tasks & Projects — Lets an agent work in Asana: find workspaces, projects, sections and people, search and read tasks with their comments,…
  • Confluence Pages — Find, read and write Confluence Cloud pages: browse spaces, look up pages by title or space, read page bodies, walk the…
  • Trello Boards & Cards — Lets an agent work on Trello boards: list your boards, read lists, cards, labels and members, search cards, create and …