Shortcut Automation

Key parameters for SHORTCUT_CREATE_STORY:

• name (required) -- the story title
• workflow_state_id -- the workflow state to place the story in (recommended over project_id)
• story_type -- "feature", "bug", or "chore"
• description -- story body/description
• estimate -- numeric point estimate (or null for unestimated)
• epic_id -- associate with an epic
• iteration_id -- associate with an iteration
• labels -- array of label objects with name (and optional color, description)
• owner_ids -- array of member UUIDs to assign
• deadline -- due date in ISO 8601 format
• tasks -- inline task array with description and optional complete, owner_ids
• comments -- inline comment array with text
• story_links -- link stories with verb ("blocks", "duplicates", "relates to")

Important: Either workflow_state_id or project_id must be provided, but not both. workflow_state_id is recommended as Projects are being sunset in Shortcut.

2. Batch Create Stories

Create multiple stories in a single API call.

Tool: SHORTCUT_CREATE_MULTIPLE_STORIES

Create 3 bug stories: "Login page 500 error", "Cart total rounding issue", and "Search results empty state broken"

• Requires stories array where each element follows the same schema as SHORTCUT_CREATE_STORY
• Each story in the array requires name
• Efficient for bulk imports, sprint planning, or template-based story creation

3. List Stories in a Project

Retrieve all stories within a specific project.

Tool: SHORTCUT_LIST_STORIES

List all stories in project 42 with their descriptions

• Requires project__public__id (integer project ID)
• Optional includes_description: true to include story descriptions in the response
• Returns all stories with their attributes (status, type, estimate, etc.)

4. Manage Story Tasks

Create tasks (checklists) within stories for tracking sub-work.

Tool: SHORTCUT_CREATE_TASK

Add a task "Write unit tests for dark mode toggle" to story 12345

Key parameters:

• story__public__id (required) -- the parent story ID
• description (required) -- the task description
• complete -- boolean, defaults to false
• owner_ids -- array of member UUIDs to assign the task
• external_id -- ID from an external tool if imported

5. Add Story Comments

Post comments on stories for discussion and documentation.

Tool: SHORTCUT_CREATE_STORY_COMMENT

Add a comment to story 12345: "Reviewed the implementation -- looks good, but needs accessibility testing"

Key parameters:

• story__public__id (required) -- the story ID
• text (required) -- the comment body
• author_id -- member UUID (defaults to API token owner)
• parent_id -- ID of parent comment for threaded replies

6. Workflow and Project Discovery

List workflows and projects to resolve IDs for story creation.

Tools: SHORTCUT_LIST_WORKFLOWS, SHORTCUT_LIST_PROJECTS

Show me all workflows in our Shortcut workspace so I can find the right workflow state ID

• SHORTCUT_LIST_WORKFLOWS returns all workflows with their states (IDs, names, types)
• SHORTCUT_LIST_PROJECTS returns all projects with their attributes
• Use these to discover valid workflow_state_id and project_id values before creating stories

Known Pitfalls

• workflow_state_id vs project_id: SHORTCUT_CREATE_STORY requires exactly one of these. Providing both or neither causes a rejection. Prefer workflow_state_id since Projects are being sunset.
• Projects are being sunset: Shortcut is deprecating Projects in favor of workflow-based organization. Use workflow_state_id for new stories.
• Label creation is inline: Labels in the labels array are created on-the-fly if they do not exist. The name field is required for each label object.
• Story type defaults: If story_type is omitted, it defaults to "feature". Always set it explicitly for bugs and chores.
• Batch limits: SHORTCUT_CREATE_MULTIPLE_STORIES processes all stories in a single request. Very large batches may time out -- keep batches under 25 stories.
• Integer IDs for stories/projects: Story and project IDs are integers, not UUIDs. Member and group IDs are UUIDs. Mixing these formats causes errors.
• move_to positioning: The move_to field ("first" or "last") moves the story within its workflow state, not across states.

Quick Reference

Powered by Composio