Menu

Mattering Automations Shortcut integration

Connect Shortcut to Mattering Automations: stories, epics, iterations, objectives, docs, teams, workflows, labels and custom fields as workflow steps, authorized by a single API token sent as the Shortcut-Token header.

The Mattering Automations Shortcut integration puts Shortcut REST API v3 on your automation canvas: create and update stories singly and in bulk, run their tasks, comments and links, manage epics, iterations, objectives and key results, write docs, maintain teams, workflows, labels, categories and custom fields, and read all six of Shortcut's search endpoints. 126 nodes in total, 66 that read and 60 that act, generated one for one from Shortcut's own machine-readable OpenAPI document.

The credential is a single API token rather than an OAuth sign-in. You generate it in Shortcut under Settings > Account > API Tokens, paste it into Mattering once, and every node sends it as the Shortcut-Token header. There is no refresh, no expiry and no consent screen. The decision that carries weight is whose token it is, because a Shortcut token acts as the member who minted it: it inherits that person's access, and comments written through the integration are attributed to them unless a node names another author.

Three things about this API shape how workflows should be built here, and all three are easier to read now than to hit later. Pagination has four different shapes, and most list endpoints have none at all, so Shortcut: List Epics returns every epic the token can see in one response. The rate limit is 200 requests per minute with no Retry-After header on the 429, so back-off has to be fixed or exponential rather than header driven. And deletes are real deletes with no undelete anywhere on the API. Each is covered in full below, and this guide ends with the complete node reference.

Before you start

  • A Shortcut workspace. Shortcut's pricing table lists API and Webhook Access as included on all four plans, and the Free plan is perpetual rather than a trial: Shortcut states that if you have ten or fewer users when the trial ends you can simply keep using Shortcut for free. So API access is not a paid feature here.
  • A decision about which Shortcut member holds the token. It carries that member's own permissions and nothing more, anything they cannot see in the web app is invisible to every node, and unattended workflows keep running on it, so a member the team controls beats an individual's personal account.
  • An awareness of the plan limits that touch specific nodes. Shortcut's pricing table caps the Free plan at one team and one customizable workflow, and the Team plan at five of each, which is worth knowing before building on Shortcut: Create Team or on multiple workflows. It lists Strategic Objectives and Key Results on the Business and Enterprise plans while Tactical Objectives appear on every plan, so treat Shortcut: Get Key Result and Shortcut: Update Key Result as plan dependent. Advanced Custom Fields are Business and Enterprise, while ordinary custom fields and labels are on every plan.
  • The team and workflow you intend to write into. Workflow states in Shortcut are scoped to one workflow, so a state id borrowed from another team's board is rejected, and the state pickers in this integration ask you to choose a workflow before they populate.
  • A Mattering workspace with access to the Automations app.

Generate a Shortcut API token

Shortcut authenticates with a single API token sent as the Shortcut-Token header. There is no OAuth flow, no application to register and no scope list to configure, which makes this the shortest credential setup in the fleet and puts all the weight on one choice: which member mints the token.

Sign in to Shortcut as the member whose access the automation should have.
Open Settings > Account > API Tokens and generate a token.
Copy the token immediately and treat it as a password. It grants everything that member can do in Shortcut, and it does not expire or rotate on its own, so it stays valid until somebody revokes it or the member is deactivated.
The token acts AS the member who minted it. That has two visible consequences. Anything that member cannot see in Shortcut is invisible to every node, so a read that returns fewer records than you expect is often the token's identity rather than a broken filter. And a comment written by an automation is attributed to that member unless the node's author id names someone else, so a shared automation posting under one person's name is worth deciding deliberately.

Connect Shortcut to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Shortcut from the list.
Click Create new credential and paste the token into the API token field. It is stored encrypted and never appears in workflow logs.
Click Test Connection. Mattering calls Shortcut's member endpoint, the cheapest authenticated call on the API, and reports back which member the token acts as.
The three failure statuses mean different things here and the test names each one. A 401 means the token was revoked, the member was deactivated, or the value was pasted with whitespace around it, since Shortcut tokens do not go stale on their own. A 403 means the token is valid and that member's own role forbids the call, which is a different finding rather than a worse one. A 429 means the 200 per minute limit was already reached.
All 126 Shortcut nodes appear in your canvas palette and over MCP.

Verify it works

Drop Shortcut: Get Current Member onto a canvas and run a test step. It is the integration's natural probe: it takes no parameters, and it answers the question that matters before any write, which is which member this token acts as. It also returns the workspace slug and the workspace's estimate scale, and that scale is published nowhere else on the API, so a workflow that sets story estimates needs this node first anyway.

Run Shortcut: List Workflows, then Shortcut: Get Workflow for the team you plan to write into. This is the second verify step for a reason rather than a formality: workflow states are scoped to a single workflow in Shortcut, this node is what powers every workflow-state picker in the integration, and its output is where a valid state id comes from. If you skip it, the first Shortcut: Create Story you run lands in the workspace default state rather than the column you meant.

Run Shortcut: List Epics without changing anything. What comes back is the whole collection rather than a first page, which is the correct behaviour on this API and the thing most worth seeing once before you design around it. If the response is large enough to be awkward, that is the signal to use Shortcut: List Epics (Paginated) in the workflow you are actually building.

Open any epic or team picker on a node and confirm it populates with real names. The pickers read from the listers in this integration, so a working picker confirms the credential, the identity behind it and the option wiring in one look. Everything in this verify path is read-only, so it cannot reach a delete node and is safe to re-run whenever you want to check the connection.

Node reference

126 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 66

Shortcut: Find Stories by External Link

shortcut_get_stories_by_external_link

Find every story carrying a given external link. This is the reverse lookup that makes a two-way sync possible: given a URL in another system, it answers which Shortcut stories point at it, without searching. The match is on the whole URL, so a trailing slash or a query string that differs will not match.

Shortcut: Get Category

shortcut_get_category

Fetch one category with its name, colour and archived flag.

Shortcut: Get Current Member

shortcut_get_current_member

Who this API token acts as: the member's id, name, mention name, role and owner flag, plus the workspace slug and its ESTIMATE SCALE. Two uses. It is the cheapest call on the API, so it is the natural connection test, and it is the only place the legal estimate values are published, which a story-creating automation needs before it sets an estimate.

Shortcut: Get Custom Field

shortcut_get_custom_field

Fetch one custom field definition with its type, enabled flag, the story types it applies to, and every value it allows.

Shortcut: Get Doc

shortcut_get_doc

Fetch one doc with its body. The response always carries content_markdown; ask for html in content_format and it also carries content_html. Doc ids are UUID strings, so this takes the id from Shortcut: List Docs or Shortcut: List Epic Docs rather than anything you can read off a URL number.

Shortcut: Get Epic

shortcut_get_epic

Fetch one epic in full, including its comment thread, its current health record, and the stats block counting stories and points by state. The stats are what a progress readout wants: num_points_done against num_points, and num_stories_done against num_stories_total.

Shortcut: Get Epic Comment

shortcut_get_epic_comment

Fetch one comment on an epic, with its replies nested inside it. Both ids are required, because a comment id is only resolvable in the context of its epic.

Shortcut: Get Epic Health

shortcut_get_epic_health

The CURRENT health status of one epic: On Track, At Risk, Off Track or No Health, with the author and the explanatory note. Health is a deliberate human statement about an epic rather than anything computed from its stories, which is what makes it worth reporting on beside the stats block.

Shortcut: Get Epic Workflow

shortcut_get_epic_workflow

The workspace's epic workflow and its states. There is exactly ONE epic workflow per workspace, which is why this takes no id and why epic states, unlike story states, are not scoped to a team. Use it to turn an epic_state_id into a name, or to find the id to move an epic to.

Shortcut: Get File

shortcut_get_file

Fetch one uploaded file's metadata: name, size, content type, uploader and the stories it is attached to. This returns the record, not the bytes; fetching the bytes means requesting the url with the same Shortcut token.

Shortcut: Get Iteration

shortcut_get_iteration

Fetch one iteration with its dates, status, associated teams and stats. The stats block is what a sprint report needs: points done against points total, plus average cycle time and average lead time in SECONDS, which is the unit to convert before charting.

Shortcut: Get Key Result

shortcut_get_key_result

One key result on an objective: its name, type, progress percentage, and its initial, current and target values. There is no key results lister on this API, so the id comes from the key_result_ids array on Shortcut: Get Objective.

Shortcut: Get Label

shortcut_get_label

Fetch one label with its stats block: how many stories and points carry it, split by state, and how many epics. This is the cheapest way to answer how much work is tagged a given way without listing the stories.

Shortcut: Get Linked File

shortcut_get_linked_file

Fetch one linked file with its URL, type and the stories it is attached to.

Shortcut: Get Member

shortcut_get_member

Fetch one member by UUID: role, state, team memberships and profile. Use this to turn an owner id from a story into a name and an email address for a notification.

Shortcut: Get Objective

shortcut_get_objective

Fetch one objective with its state, categories, stats and the ids of its key results. The key result ids are UUIDs and are the only way to reach Shortcut: Get Key Result, which has no lister of its own.

Shortcut: Get Objective Health

shortcut_get_objective_health

The current health status of one objective: On Track, At Risk, Off Track or No Health, with its author and note. Same mechanism as epic health, one level up the hierarchy.

Shortcut: Get Outgoing Webhook

shortcut_get_webhook_integration

Fetch one registered outgoing webhook. This connector BLANKS the shared secret in the response, on this node and everywhere else, so a credential never reaches an automation's output or its run log. If you need the secret, it is the one you set when creating the integration.

Shortcut: Get Project

shortcut_get_project

Fetch one project with its workflow, abbreviation, followers and stats block.

Shortcut: Get Repository

shortcut_get_repository

Fetch one connected repository by id. Note the path parameter is spelled repo, not repository, which is the one place Shortcut abbreviates a resource name in a URL.

Shortcut: Get Story

shortcut_get_story

Fetch one story in full: description, owners, labels, custom field values, estimate, workflow state, and the nested tasks, comments, files, branches, commits and pull requests. This is the only way to read a story's TASKS, which have no lister of their own and arrive in the tasks array here.

Shortcut: Get Story Comment

shortcut_get_story_comment

Fetch one comment on a story with its text, author, reactions and thread position. Both ids are required, because a comment id is only resolvable in the context of its story.

Shortcut: Get Story History

shortcut_get_story_history

The full audit trail for one story: who changed what and when, as a bare array of history entries. Each entry carries the actor, the timestamp, an actions array whose changes object holds the old and new value of every field touched, and a references array naming the ids that appear in those changes, so a workflow state id can be rendered as a state name without a second call. This is the node behind cycle-time and state-transition reporting: it is the only place the API says when a story entered a given column.

Shortcut: Get Story Link

shortcut_get_story_link

Fetch one story link: its verb, the two story ids and the subject's current workflow state. There is no story links lister, so the id comes from the story_links array on Shortcut: Get Story.

Shortcut: Get Story Template

shortcut_get_entity_template

Fetch one story template with the exact story contents it applies: name, description, type, workflow state, team, labels, owners and tasks. Read this before creating from a template if you need to know what you are about to inherit.

Shortcut: Get Task on Story

shortcut_get_story_task

Fetch one checklist task on a story. There is no lister for tasks on this API, so the task id comes from the tasks array on Shortcut: Get Story, or from the response of Shortcut: Create Task on Story.

Shortcut: Get Team

shortcut_get_group

Fetch one team with its member ids, workflow ids, default workflow and story counts. The member_ids array is the authoritative roster, and each id resolves through Shortcut: Get Member.

Shortcut: Get Workflow

shortcut_get_workflow

Fetch one workflow with its states, their order, their types and how many stories sit in each. This node also powers every workflow-state picker in the connector, which is why those fields ask you to choose a workflow first.

Shortcut: List Categories

shortcut_list_categories

Every category in the workspace. Categories group OBJECTIVES, which is the whole of their scope: they are not story labels and they do not apply to epics. Archived categories are included, so filter on the archived flag if you only want live ones.

Shortcut: List Category Objectives

shortcut_list_category_objectives

Every objective carrying one category. Shortcut also exposes an identical endpoint under the older milestones spelling; this connector builds only the objectives one, because they return the same records and shipping both would suggest they are different things.

Shortcut: List Custom Fields

shortcut_list_custom_fields

Every custom field defined in the workspace, each with the full list of enum values it allows. This is the node to run BEFORE setting a custom field on a story: a story carries field_id plus value_id pairs, and both are UUIDs that only this endpoint can tell you. The field id is the row's id; the value id is the id of one entry in that row's values array.

Shortcut: List Doc Epics

shortcut_list_doc_epics

The epics one doc is linked to. The relationship is many to many, so this is the other half of Shortcut: List Epic Docs: one doc can be attached to several epics, and one epic can carry several docs.

Shortcut: List Docs

shortcut_list_docs

Every doc the token's member can see, in SLIM form: id, title and app URL only, with no body content at all. That is by design, since doc bodies are large. Fetch the text one at a time with Shortcut: Get Doc. Doc ids are UUID strings, unlike the integer ids most of this API uses.

Shortcut: List Epic Comments

shortcut_list_epic_comments

The comment thread on one epic. Epic comments nest differently from story comments: each top-level comment carries its replies in its own comments array, rather than the replies carrying a parent id. Walk the nested array rather than filtering on a parent field.

Shortcut: List Epic Docs

shortcut_list_epic_documents

The docs linked to one epic, returned in slim form: id, title and app URL, with no body content. Fetch the text with Shortcut: Get Doc once you have the id.

Shortcut: List Epic Health History

shortcut_list_epic_health_history

Every health status ever recorded on one epic, newest first, with each one's author, note and timestamp. This is what turns a single current status into a narrative: when the epic first went At Risk, who said so, and what changed.

Shortcut: List Epic Stories

shortcut_list_epic_stories

Every story inside one epic, with workflow state, owners, estimate and labels on each. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response. This is also the node behind the story pickers in this connector, which is why several nodes carry an epic field they never send: Shortcut has no unscoped story lister, so a picker has to be narrowed to something.

Shortcut: List Epics

shortcut_list_epics

Every epic in the workspace, with its state, owners, teams, labels, deadline, health and a stats block counting the stories and points inside it. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response. Use Shortcut: List Epics (Paginated) instead when the workspace has enough epics for that to matter. This is also the source for every epic picker in this connector.

Shortcut: List Epics (Paginated)

shortcut_list_epics_paginated

The same epics as Shortcut: List Epics, one page at a time. This is the ONLY page-numbered endpoint on the whole Shortcut API: everything else either returns a bare array or uses the search cursor. The response is an object rather than an array, with the epics at data, a total count, and next holding the next page NUMBER or null on the last page. Ask for page 1 first; there is no page 0.

Shortcut: List Files

shortcut_list_files

Every file uploaded to the workspace, with its name, content type, size, uploader and the stories it is attached to. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response. The url on each row points at Shortcut's own API and needs the same token to fetch, so it is not a link you can hand to someone outside the workspace.

Shortcut: List Iteration Stories

shortcut_list_iteration_stories

Every story in one iteration, with workflow state, owners, estimate and labels on each. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response. This is the raw material for a standup summary or an end-of-sprint report: group the rows by workflow_state_id and sum the estimates.

Shortcut: List Iterations

shortcut_list_iterations

Every iteration in the workspace, with its dates, status, teams, labels and a stats block counting points and stories by state, plus average cycle and lead time in seconds. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response. The status field is derived from the dates rather than set by hand: unstarted, started or done.

Shortcut: List Label Epics

shortcut_list_label_epics

Every epic carrying one label. Labels are shared between stories and epics, so the same label id answers both this node and Shortcut: List Label Stories.

Shortcut: List Label Stories

shortcut_list_label_stories

Every story carrying one label, across all teams, epics and iterations. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response. This is the node behind cross-cutting reports that no single board shows, such as everything tagged for a compliance push.

Shortcut: List Labels

shortcut_list_labels

Every label in the workspace. By default each row carries a stats block counting the stories, points and epics using that label, which is expensive on a workspace with many labels; set slim to true to drop the stats and get just the label records. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response.

Shortcut: List Linked Files

shortcut_list_linked_files

Every linked file in the workspace, with its URL, integration type and the stories it is attached to. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response. A linked file is a REFERENCE to a document somewhere else, not a copy, so Shortcut holds only the URL and the metadata around it.

Shortcut: List Members

shortcut_list_members

Every member of the workspace, with each one's role, state, teams and profile (name, mention name, email address). Member ids are UUIDs and this is where every owner, follower and author id in the connector comes from. Disabled members are included by default, which matters for a directory sync: filter on the disabled flag rather than assuming the list is current staff.

Shortcut: List Objective Epics

shortcut_list_objective_epics

Every epic rolling up into one objective, each with its own state, deadline and stats block. Summing the epics' stats is how you get progress for a whole objective, since the objective's own stats block does not count stories.

Shortcut: List Objective Health History

shortcut_list_objective_health_history

Every health status ever recorded on one objective, newest first, with author, note and timestamp on each.

Shortcut: List Objectives

shortcut_list_objectives

Every objective in the workspace, with its state, categories, key result ids and a stats block. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response. Objectives are what Shortcut used to call Milestones: the entity_type on each row still reads milestone, which is a renaming artefact rather than a different kind of record.

Shortcut: List Project Stories

shortcut_list_project_stories

Every story in one project. This endpoint returns a bare JSON array with no pagination of any kind, so one call returns everything the token can see. On a large workspace that is a large response.

Shortcut: List Projects

shortcut_list_projects

Every project in the workspace, with its abbreviation, colour, workflow and stats. Projects are Shortcut's older way of grouping stories and most workspaces now organise by TEAM instead, so this often returns an empty array on a newer workspace, which is a correct answer rather than a failure.

Shortcut: List Repositories

shortcut_list_repositories

Every version control repository connected to the workspace, with its full name, type and URL. This lists what Shortcut's own GitHub, GitLab or Bitbucket integration has connected; it does not connect anything, and the connector cannot add a repository.

Shortcut: List Story Comments

shortcut_list_story_comments

Every comment on one story, including replies (a reply carries the id of its parent in parent_id) and each comment's emoji reactions. Deleted comments are returned with deleted set to true and their text removed, so the length of this array is not a count of live comments.

Shortcut: List Story Sub-tasks

shortcut_list_story_sub_tasks

The stories linked as sub-tasks of one parent story, returned as full story records rather than as ids. Sub-tasks are STORIES in Shortcut, which is the thing to know before wiring this up: they have their own workflow state, owners and estimate. That makes them different from a story's TASKS, which are checklist items living inside the story and readable through Shortcut: Get Story. Sub-tasks require the workspace feature of the same name.

Shortcut: List Story Templates

shortcut_list_entity_templates

Every story template in the workspace, each with its author, last-used timestamp and the full story contents it will apply. Feed a template id from here into Shortcut: Create Story From Template. If this returns an error rather than an empty list, the workspace has story templates switched off.

Shortcut: List Team Stories

shortcut_list_group_stories

Every story owned by one team. This is the ONLY endpoint on the Shortcut API that takes limit and offset, and it still returns a bare array with no total, so there is no way to know you have reached the end except by receiving fewer rows than you asked for. Leave both blank to get everything in one call.

Shortcut: List Teams

shortcut_list_groups

Every team in the workspace, with its members, workflows, mention name, colour and story counts. Teams are called Groups throughout this API and their ids are UUIDs, which is what to check first when a group_id is rejected: an integer there is always the wrong kind of id. This is the source for every team picker in the connector.

Shortcut: List Workflows

shortcut_list_workflows

Every story workflow in the workspace, each with its full list of states in board order. Run this first when a workflow_state_id is rejected: states belong to ONE workflow, a team works in a specific set of workflows, and a state id borrowed from another team's board is not valid. Each state carries a type of unstarted, started or done, which is the portable way to ask what a column means across teams that named theirs differently.

Shortcut: Search Docs

shortcut_search_documents

Find docs by TITLE. This is the odd one out among the search endpoints: it takes a title rather than a query, understands none of Shortcut's search operators, and searches titles only rather than doc bodies. It adds three filters the others do not have: archived, created by me and followed by me, where me is the member who owns the API token.

Shortcut: Search Epics

shortcut_search_epics

Find epics with a Shortcut search query. Same operators and same cursor contract as Shortcut: Search Stories, restricted to epics.

Shortcut: Search Everything

shortcut_search

Run one Shortcut search query across several entity types at once. The response is an OBJECT with a separate result envelope per type (stories, epics, iterations and objectives), each with its own total, data array and next value, rather than one merged list. Defaults to stories and epics; set entity_types to widen or narrow it. Result ordering can shift between calls as search ranking decays and new work is created, which is exactly why paging must follow the next value rather than counting pages.

Shortcut: Search Iterations

shortcut_search_iterations

Find iterations with a Shortcut search query. Worth knowing that Shortcut: List Iterations returns every iteration in one call with no query at all, so this node earns its place only when you want the search operators, for instance to find iterations belonging to one team.

Shortcut: Search Objectives

shortcut_search_objectives

Find objectives with a Shortcut search query. Shortcut also exposes the identical search under the older milestones spelling; this connector builds only the objectives one, because both return the same records.

Shortcut: Search Stories

shortcut_search_stories

Find stories with a Shortcut search query, the same syntax the web app's search box takes: owner:example, state:"In Progress", is:blocked, label:security, created:2026-01-01..2026-02-01, and so on. Use this when a human would type the question; use Shortcut: Search Stories by Field when a machine is assembling the filters. The response carries total, data and next.

Shortcut: Search Stories by Field

shortcut_search_stories_advanced

Find stories by structured field values rather than by a text query: every story owned by a member, in an epic, in a workflow state, created between two dates. Every filter is optional and the ones you set are combined, so this is the node for report-style questions that Shortcut: Search Stories cannot express in a query string. It is a POST because the filter set is a body rather than a URL, but it reads and changes nothing. The response is a bare array with no pagination and no total, so a broad filter returns a broad response.

Action nodes 60

Shortcut: API Request

shortcut_api_request

Call any Shortcut v3 endpoint directly, with the connector's credential applied for you. This exists so nothing on the API is unreachable: the endpoints this connector does not ship as their own node, and anything Shortcut adds after it was built. Give it a method and a path such as /api/v3/epics, plus a query object or a JSON body if the endpoint takes one. It is marked Safe Read because a GET is, but the method is yours to choose: a DELETE typed here deletes, with none of the warnings the dedicated nodes carry. Prefer a dedicated node whenever one exists, because those bring validated fields, pickers and sample outputs.

Shortcut: Add Reaction to Story Comment

shortcut_create_story_reaction

Add an emoji reaction to a story comment, as the member who owns the API token. The response is the comment's full reaction list after the change rather than just the one added. Reacting twice with the same emoji is not an error.

Shortcut: Create Category

shortcut_create_category

Create a category for objectives. Only the name is required. Note you rarely need this node: attaching a category by name through Shortcut: Create Objective or Update Objective creates it on the spot if it does not exist. Use this one when you want to set the colour up front, or to pre-create the vocabulary before anything uses it.

Shortcut: Create Doc

shortcut_create_doc

Create a doc. Title and content are both required. Storage is always HTML: content_format tells Shortcut what you are SENDING, and markdown is converted on the way in. The default is html, which is the trap on this endpoint, because Markdown posted without setting content_format is stored as literal text with its hashes and asterisks showing. Set markdown explicitly when you are sending Markdown.

Shortcut: Create Epic

shortcut_create_epic

Create an epic. Only the name is required. Two pairs of fields on this endpoint are legacy and this node deliberately exposes only the current one of each: use epic_state_id rather than state, because Shortcut ignores state whenever epic_state_id is set, and use objective_ids rather than milestone_id, because Milestones were renamed Objectives and the old field is marked deprecated in Shortcut's own API description. Stories are added to an epic from the story side, by setting epic_id on Shortcut: Create Story or Update Story.

Shortcut: Create Epic Comment

shortcut_create_epic_comment

Post a top-level comment on an epic. To reply to an existing comment instead, use Shortcut: Reply to Epic Comment, which takes the parent comment's id in the path. As with story comments, the comment is attributed to the token owner unless author_id names another member.

Shortcut: Create Iteration

shortcut_create_iteration

Create an iteration. Name, start date and end date are all required, and the dates are plain calendar dates (2026-02-01), not timestamps. This is the node to schedule if you want sprints created ahead of time rather than by hand. Stories are pulled in afterwards by setting iteration_id on Shortcut: Update Story or Shortcut: Update Stories in Bulk.

Shortcut: Create Label

shortcut_create_label

Create a label. Only the name is required. Labels are created implicitly whenever a story or epic is given a label name that does not exist yet, so use this node when you want to set the colour and description up front, or to seed a vocabulary before anything writes to it. Creating a label that already exists by name is rejected.

Shortcut: Create Linked File

shortcut_create_linked_file

Attach an external document to Shortcut by URL. Name, type and url are all required. This is the node that gets a spec, a design file or a dashboard onto a story without uploading anything: set story_id and the link appears on that story. Use type url for a plain web link and the named integration types when the document really does live in that service, since the type only affects how Shortcut labels and icons the link.

Shortcut: Create Objective

shortcut_create_objective

Create an objective, the strategic goal that epics roll up into. Only the name is required. Epics are attached from the epic side, by setting objective_ids on Shortcut: Create Epic or Update Epic, so a fresh objective starts empty.

Shortcut: Create Outgoing Webhook

shortcut_create_webhook_integration

Register a URL for Shortcut to POST its activity events to. This is the OUTBOUND direction: Shortcut calls you when something changes, which is how a workflow reacts to Shortcut in real time instead of polling. Set the secret and verify the signature on every delivery, because the endpoint is otherwise open to anyone who learns the URL. Note the response is 204 with no body, so the integration's own id is not returned here: list or read it afterwards to get it.

Shortcut: Create Project

shortcut_create_project

Create a project. Name and team_id are both required. Note team_id here is the INTEGER id Shortcut's API uses for a workflow grouping, not the UUID that identifies a Team in the modern sense: read it from the team_id field on Shortcut: List Workflows. If your workspace organises by team rather than by project, you probably want Shortcut: Create Team instead.

Shortcut: Create Stories in Bulk

shortcut_create_stories_bulk

Create many stories in one request. Each element takes exactly the same fields as Shortcut: Create Story, so this is the node to use when an upstream step produced a list rather than a single item. The response is the array of created stories in the order they were sent. There is no documented partial-success mode: a malformed element fails the whole request, so validate the array upstream rather than relying on the good elements landing.

Shortcut: Create Story

shortcut_create_story

Create one story: a feature, a bug or a chore. Only the name is required, so a minimal call files an unestimated story into the workspace's default workflow state. Everything else is optional and can be set later with Shortcut: Update Story. Two fields are worth setting on creation rather than after: workflow_state_id, because a story created without one lands in the default state rather than where you meant it, and group_id, because the team owning a story governs which workflow its states come from. The response is the created story, so the new id is available to the rest of the automation immediately.

Shortcut: Create Story Comment

shortcut_create_story_comment

Post a comment on a story, or reply to an existing comment by setting parent_id. The comment is attributed to the member who minted the API token unless author_id names someone else, which matters when a shared automation posts on a team's behalf: without author_id every comment appears to come from one person.

Shortcut: Create Story From Template

shortcut_create_story_from_template

Create a story from a story template, applying the template's name, description, tasks, labels, owners and workflow state, then layering your own changes on top. This is the node that actually uses a template; setting story_template_id on Shortcut: Create Story only records an association and copies nothing. The fields here are the ADD and REMOVE variants on purpose: Shortcut's own documentation says the add and remove forms cannot be combined with their whole-value counterparts on the same request, so this node exposes the additive forms and leaves wholesale replacement to Shortcut: Update Story afterwards.

Shortcut: Create Story Link

shortcut_create_story_link

Relate two stories. All three fields are required and the DIRECTION matters: the sentence reads subject verb object, so blocks with subject 100 and object 200 means story 100 blocks story 200, and reversing the ids reverses the meaning. Shortcut shows the inverse on the other story automatically, so there is no need to create the mirror link yourself.

Shortcut: Create Task on Story

shortcut_create_story_task

Add a checklist task to a story. A task is a line item inside the story rather than a story of its own: it has a description, a complete flag and optional owners, and it never has a workflow state or an estimate. Use sub-tasks instead when the work needs to move across a board on its own.

Shortcut: Create Team

shortcut_create_group

Create a team. Name and mention_name are both required, and the mention name is what people type after @@ in comments, so it should be short and unique. Give the team at least one workflow id: a team with no workflow has no board for its stories to live on, and Shortcut will not infer one.

Shortcut: Delete Category

shortcut_delete_category

Permanently delete one category. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. It is removed from every objective carrying it, and those objectives are otherwise untouched. Archiving through Shortcut: Update Category is almost always the better move, because it retires the category without rewriting history.

Shortcut: Delete Doc

shortcut_delete_doc

Permanently delete one doc and everything attached to it. Shortcut's own wording is permanent, and it requires ADMIN access to that doc, so a token whose member can read and edit the doc may still be refused here. There is no archive state for docs, so read the content out with Shortcut: Get Doc first if you might want it back.

Shortcut: Delete Epic

shortcut_delete_epic

Permanently delete one epic, with its comment thread and health history. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. If you want it reversible, set archived to true through the matching Update node instead. The epic's STORIES are not deleted: they survive with their epic_id cleared, which means they leave the epic's board silently rather than disappearing. Nothing in the API tells you afterwards which stories used to belong to it, so list them first if you need that.

Shortcut: Delete Epic Comment

shortcut_delete_epic_comment

Delete one comment from an epic. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. Deleting a comment that has replies leaves the thread in place with the parent marked deleted and its text gone.

Shortcut: Delete File

shortcut_delete_file

Permanently delete one uploaded file. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. The bytes go with it, so this is the least recoverable delete in the connector: a story or comment can be recreated from an export, an image cannot. It is removed from every story it was attached to, and this connector cannot re-upload it, because Shortcut's upload endpoint is a multipart form a canvas has no file for.

Shortcut: Delete Iteration

shortcut_delete_iteration

Permanently delete one iteration. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. An iteration has no archived state on this API, so there is no reversible alternative to reach for. The STORIES in it are not deleted: they survive with their iteration_id cleared, which also erases the record of which sprint they were worked in, so export the sprint's story list before deleting if the history matters.

Shortcut: Delete Label

shortcut_delete_label

Permanently delete one label. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. It is removed from EVERY story and epic carrying it, and nothing records that it was ever there, so a saved view or a report filtered on that label silently returns nothing afterwards. Archiving through Shortcut: Update Label retires it without that cost and is almost always the right choice.

Shortcut: Delete Linked File

shortcut_delete_linked_file

Delete one linked file. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. The DOCUMENT ITSELF is untouched, because Shortcut only ever held a URL, so this is the most recoverable delete in the connector: relink it with Shortcut: Create Linked File if the URL is still known.

Shortcut: Delete Objective

shortcut_delete_objective

Permanently delete one objective, with its key results and health history. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. If you want it reversible, set archived to true through the matching Update node instead. The objective's EPICS are not deleted: they survive with this objective removed from their objective_ids, so a quarter's worth of work quietly loses its strategic parent rather than disappearing.

Shortcut: Delete Outgoing Webhook

shortcut_delete_webhook_integration

Unregister an outgoing webhook. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. Deliveries stop immediately and silently: nothing downstream is told, so anything listening simply stops hearing from Shortcut. Recreate it with Shortcut: Create Outgoing Webhook, which needs the URL and the secret again.

Shortcut: Delete Project

shortcut_delete_project

Permanently delete one project. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. If you want it reversible, set archived to true through the matching Update node instead. Shortcut refuses to delete a project that still contains stories, so the usual sequence is to move or delete the stories first; that refusal is a useful guard rather than an obstacle, since it is the only thing standing between a misfired automation and a lost board.

Shortcut: Delete Stories in Bulk

shortcut_delete_stories_bulk

Permanently delete several stories at once. Shortcut only deletes stories that are ALREADY ARCHIVED here, which makes this the one delete on the whole API with a built-in guard: a live story is not removed by accident. The intended sequence is archive with Shortcut: Update Stories in Bulk, review, then delete. Comments, tasks and history go with the stories and there is no undelete.

Shortcut: Delete Story

shortcut_delete_story

Permanently delete one story, with its comments, tasks and history. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. If you want it reversible, set archived to true through the matching Update node instead. Deleting a story that other stories link to also removes those links, and deleting a parent story does not delete its sub-tasks: they are left unparented.

Shortcut: Delete Story Comment

shortcut_delete_story_comment

Delete one comment from a story. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. Deleting a comment that has replies leaves the thread in place with the parent marked deleted and its text gone, so the replies survive but their context does not.

Shortcut: Delete Story Link

shortcut_delete_story_link

Remove a relationship between two stories. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. Both STORIES are untouched: only the link between them goes, and it can be recreated with Shortcut: Create Story Link as long as you still know the verb and the two ids.

Shortcut: Delete Task on Story

shortcut_delete_story_task

Delete one checklist task from a story. This is a real delete, not an archive. Shortcut answers 204 No Content and exposes no undelete. A task has no archived state, so unlike a story there is no reversible alternative. Read it first if the text matters.

Shortcut: Link Doc to Epic

shortcut_link_doc_to_epic

Attach a doc to an epic. Both ids go in the URL and there is no body: the relationship IS the request. Linking a doc that is already linked is not an error, so this is safe to run repeatedly, which matters when a retried automation would otherwise duplicate the link.

Shortcut: Remove Reaction from Story Comment

shortcut_delete_story_reaction

Remove the token owner's emoji reaction from a story comment. Listed as reversible rather than destructive because re-adding the same reaction restores the state exactly. It removes only the token owner's reaction, never another member's.

Shortcut: Reply to Epic Comment

shortcut_reply_to_epic_comment

Reply to an existing epic comment, threading the new comment under it. Note the shape of this endpoint: it POSTs to the PARENT COMMENT's own URL, which is the same URL the update node PUTs to and the delete node DELETEs. Same address, three different meanings depending on the method.

Shortcut: Set Epic Health

shortcut_create_epic_health

Record a new health status on an epic. This APPENDS to the epic's health history rather than overwriting the last entry, so the trail of how a piece of work went is preserved. Set No Health to clear the indicator without deleting the history.

Shortcut: Set Objective Health

shortcut_create_objective_health

Record a new health status on an objective. This APPENDS to the objective's health history rather than overwriting the last entry, so the record of how a goal tracked over a quarter stays intact.

Shortcut: Unlink Doc from Epic

shortcut_unlink_doc_from_epic

Detach a doc from an epic. This removes the LINK only: the doc itself is untouched and still exists in the workspace, which is why this is a reversible write rather than a destructive one. Re-link it any time with Shortcut: Link Doc to Epic.

Shortcut: Update Category

shortcut_update_category

Rename, recolour or archive one category. Archiving keeps it on the objectives already carrying it while removing it from the pickers offered for new ones, which is the safe way to retire a category that is no longer used.

Shortcut: Update Custom Field

shortcut_update_custom_field

Change a custom field definition: rename it, enable or disable it for the workspace, reorder it, or edit the list of values it allows. Treat the values field carefully. It is the FINAL STATE of the value list, so read the field first with Shortcut: Get Custom Field and send back the existing entries with your additions, or you will drop the ones you left out. Disabling a field hides it from new stories without touching the values already recorded on existing ones, which is the reversible way to retire one.

Shortcut: Update Doc

shortcut_update_doc

Change a doc's title, its body, or both. Content REPLACES the whole document rather than appending, and there is no revision endpoint on this API to recover the previous text from, so read the doc first if you are rewriting rather than generating. content_format carries the same default-to-html trap as Create Doc: Shortcut's own documentation flags it as a warning.

Shortcut: Update Epic

shortcut_update_epic

Change one epic: move it through the epic workflow, retitle it, reassign it, archive it. Only the fields you fill in are sent. The list fields REPLACE rather than append, so sending one owner id leaves the epic with exactly one owner. Moving an epic through the workflow does not move its stories: an epic marked done can still hold unfinished stories, and Shortcut allows that deliberately.

Shortcut: Update Epic Comment

shortcut_update_epic_comment

Rewrite the text of one epic comment. Text is the only field this endpoint accepts, and the previous text is not recoverable through the API.

Shortcut: Update File

shortcut_update_file

Change an uploaded file's metadata: rename it, describe it, reattribute it or stamp it with an external id. The bytes are immutable, so this node cannot replace a file's contents.

Shortcut: Update Health Record

shortcut_update_health

Correct an existing health record in place, rather than appending a new one. Use this to fix a typo in a note or a status set by mistake; use Shortcut: Set Epic Health or Shortcut: Set Objective Health when the situation has genuinely changed, because those preserve the trail and this overwrites it. One endpoint serves both epic and objective health, so the id decides which one you are editing.

Shortcut: Update Iteration

shortcut_update_iteration

Rename, re-date or re-scope one iteration. Only the fields you fill in are sent. Moving the dates changes the iteration's derived status, so an iteration can go from started back to unstarted by pushing its start date forward. Stories already in the iteration stay in it whatever the dates do.

Shortcut: Update Key Result

shortcut_update_key_result

Update a key result's name or its measured values. This is the node that makes an objective self-updating: point a scheduled automation at your metric source and push the observed value in, and the progress percentage recalculates from the initial, observed and target values. Each value is an object rather than a bare number, because a key result may be numeric, a percentage or boolean.

Shortcut: Update Label

shortcut_update_label

Rename, redescribe, recolour or archive one label. Renaming updates it everywhere at once, since a label is a single record that stories and epics point at rather than a string copied onto each. Archiving hides it from pickers while leaving it on the work already carrying it.

Shortcut: Update Linked File

shortcut_update_linked_file

Change a linked file: point it at a new URL, rename it, or move it to a different story. Repointing the URL is the useful case, because a document that moved does not have to be relinked everywhere it appears.

Shortcut: Update Objective

shortcut_update_objective

Change one objective: rename it, move its state, re-categorise it, archive it, or reorder it against its siblings. Only the fields you fill in are sent. The categories list REPLACES the current set rather than adding to it.

Shortcut: Update Project

shortcut_update_project

Rename, recolour, re-home or archive one project. Only the fields you fill in are sent. Archiving a project is the reversible way to retire it and leaves its stories in place.

Shortcut: Update Stories in Bulk

shortcut_update_stories_bulk

Apply one change to many stories at once: move a batch to a workflow state, pull a set into an iteration, add an owner across a list. Only story_ids is required and every other field is optional, so send just the ones you mean to change. This node uses ADD and REMOVE lists rather than whole-value replacement for owners, followers, labels and custom fields, which is the important difference from Shortcut: Update Story: adding an owner here does not wipe the owners a story already had.

Shortcut: Update Story

shortcut_update_story

Change one story: move it between workflow states, reassign it, re-estimate it, retitle it, archive it. Only the fields you fill in are sent, so an unfilled field is left alone. The list fields here REPLACE rather than append, so sending one owner id leaves that story with exactly one owner. Use Shortcut: Update Stories in Bulk when you want add and remove semantics, even for a single story. The sub_tasks field is the same trap in a sharper form: Shortcut treats it as the final state of the parent's sub-tasks, so anything missing from the array is unlinked.

Shortcut: Update Story Comment

shortcut_update_story_comment

Rewrite the text of one story comment. Text is the only field this endpoint accepts: author, timestamps and thread position are fixed once a comment exists. The previous text is not recoverable through the API, so read it first if you need it.

Shortcut: Update Story Link

shortcut_update_story_link

Change an existing story link: swap the verb, or repoint either end. Swapping subject and object is how you reverse a relationship that was created the wrong way round, which is the common reason to reach for this node.

Shortcut: Update Task on Story

shortcut_update_story_task

Tick, retitle, reassign or reorder one checklist task on a story. Ticking is the common use: set complete to true. The owner_ids list replaces the task's current owners rather than adding to them.

Shortcut: Update Team

shortcut_update_group

Change one team: rename it, change its membership or workflows, or archive it. The member_ids and workflow_ids lists REPLACE the current sets rather than adding to them, so read the team first and send the full intended roster: sending one member id leaves the team with exactly one member. Archiving is the only way to retire a team, because this API has no delete for one.

Using the integration

Four pagination shapes on one API, and which node uses which

There is no single paginator for Shortcut and writing one would be wrong, so every node declares its own strategy. Most of them declare none: 35 of the API's 70 read endpoints return a bare JSON array with no envelope, no page parameter, no cursor and no total, which means Shortcut: List Epics, Shortcut: List Iterations, Shortcut: List Labels, Shortcut: List Docs and their siblings return everything the token can see in one response. That is the default shape here, not the exception, and it is why one wide read usually beats a loop. Exactly one path is page numbered, which is Shortcut: List Epics (Paginated): ask for page 1 first, since there is no page 0, and its next value is a page NUMBER or null on the last page. The six search nodes are different again: their next value is not an opaque cursor but the path and query string of the next page, which Shortcut asks you to follow rather than reconstruct because result ordering shifts as ranking decays and new work is created. Search is also capped at 1000 total matches across all pages, and paging past that returns a dedicated error rather than an empty page, so a walk-every-page loop against a broad query terminates in a failure. Narrow the query instead. And Shortcut: List Team Stories is the only endpoint on the API that takes limit and offset, still over a bare array with no total, so the only way to know you have reached the end is to receive fewer rows than you asked for. Leave both blank to get everything in one call.

The rate limit, and why the missing header matters more than the number

Shortcut documents 200 requests per minute and answers HTTP 429 past that, and its documentation specifies no Retry-After header on the response. The number is generous; the missing header is the trap. A retry loop written against the usual contract reads the header, gets nothing, treats it as zero and immediately hits the limit it just hit, so back-off against this API must be fixed or exponential and must never be header driven. This integration surfaces the 429 as an ordinary unsuccessful result with that fact attached rather than retrying inside the node, so a workflow can branch on it instead of a hidden retry burning the whole minute. The durable fix is shape rather than pacing. On an API where most listers return the entire collection, replace a list followed by one read per row with a single list call, and reach for the scoped listers such as Shortcut: List Epic Stories or Shortcut: List Iteration Stories rather than fanning out over ids you already have.

Two kinds of id, and the 404 that comes from mixing them

Shortcut uses integer public ids for stories, epics, iterations, objectives, labels, categories, projects, files, linked files and workflows, and UUID strings for members, teams, docs, custom fields, story templates and health records. Sending the wrong kind is a 400 or a 404 rather than a helpful message, and it is the commonest avoidable failure on this API, so every field on every node declares its type and the pickers hand you the right shape. Two id sources are worth knowing because no lister exists for them. A story task id arrives nested in the tasks array on Shortcut: Get Story, and a key result id arrives in the key result ids array on Shortcut: Get Objective, so both fields are free text with the read location named in their description rather than a picker that could never populate. The same is true of an outgoing webhook id, which Shortcut can get and delete but not list, so record the id when you register one.

Writes that replace rather than append

This is the behaviour most likely to surprise you, and it is Shortcut's design rather than the integration's. On Shortcut: Update Story the list fields REPLACE rather than append, so sending one owner id leaves that story with exactly one owner and drops the rest. The sub-tasks field is the same trap in a sharper form, because Shortcut treats it as the final state of the parent's sub-tasks and unlinks anything missing from the array. When you want add and remove semantics, use Shortcut: Update Stories in Bulk even for a single story, which is the node that exposes the additive forms. Shortcut: Update Custom Field has the same shape in a place with a longer blast radius: its values field is the final state of the allowed value list, so read the field first with Shortcut: Get Custom Field and send the existing entries back alongside your additions, or you will drop the ones you left out. And Shortcut: Create Stories in Bulk has no documented partial-success mode: one malformed element fails the whole request, so validate the array upstream rather than relying on the good elements landing.

Deletes, archiving, and the one built-in guard

18 nodes delete, 16 of them are flagged destructive, every one answers 204 No Content, and Shortcut documents no undelete for any resource. The integration states each blast radius on the node rather than behind one blanket warning, because they differ. Shortcut: Delete Epic does not delete the epic's stories: they survive with their epic id cleared, leaving the board silently, and nothing afterwards records which ones belonged to it, so list them first. Shortcut: Delete Objective leaves its epics but removes the objective from them. Shortcut: Delete Label strips the label from every story and epic carrying it, and a saved view filtered on that label then returns nothing with no trace of why. Shortcut: Delete File takes the bytes with it and this integration cannot re-upload them, because Shortcut's upload endpoint is a multipart form, which makes it the least recoverable delete here. Shortcut: Delete Doc requires admin access to that doc and Shortcut calls it permanent, and docs have no archived state, so read the content out with Shortcut: Get Doc first. Shortcut: Delete Project is the one Shortcut itself refuses while the project still holds stories. Two deletes are gentle enough to be classed as reversible writes rather than destructive, because recreating them restores the prior state exactly: Shortcut: Unlink Doc from Epic leaves the doc untouched, and Shortcut: Remove Reaction from Story Comment removes one emoji. The safe pattern everywhere else is archive, review, delete. Shortcut: Delete Stories in Bulk is the only delete on the API with a guard built in, because Shortcut removes only stories that are already archived, so pair it with Shortcut: Update Stories in Bulk and a review step in between.

What is deliberately not built, and the way around it

18 of Shortcut's 143 v3 operations are not shipped as nodes, and the reasons are worth reading rather than discovering. Eight are milestone endpoints. Shortcut renamed Milestones to Objectives and kept the old paths as aliases, its own document marks six of them deprecated with the objective equivalent named in the description, and the other two return the same records as their objective counterparts, so building both would ship two nodes writing to one place while disagreeing about what it is called. Use Shortcut: List Objectives and its siblings. File upload is out because it is a multipart form and a canvas has no local file to attach; attach documents by URL with Shortcut: Create Linked File instead. The four workspace toggles that enable or disable Iterations and Story Templates are out, because switching a product feature off for every member is an administrator's deliberate act in the web app rather than something an automation should reach by accident. Deleting a custom field definition is out because it removes that field's values from every story in the workspace with no undelete, so Shortcut: List Custom Fields, Shortcut: Get Custom Field and Shortcut: Update Custom Field are built and the delete is not; disabling a field through the update node hides it from new stories without touching recorded values, which is the reversible way to retire one. Story template creates, updates and deletes are out because a template body is a whole nested document authored in Shortcut's own editor, while Shortcut: List Story Templates and Shortcut: Get Story Template are built because Shortcut: Create Story From Template needs the id. Nothing is unreachable regardless: Shortcut: API Request calls any Shortcut v3 endpoint directly with the credential applied, including anything Shortcut ships after this integration was built. Its path is validated to start with the v3 prefix, and it is worth saying plainly that a DELETE typed into it deletes, with none of the warnings the dedicated nodes carry, so prefer a dedicated node whenever one exists.

Searching, and choosing between the two ways to do it

Shortcut: Search Stories takes the same query syntax as the web app's search box, including owner, state, label, is:blocked and date range operators, so it is the node to use when a human would type the question. Shortcut: Search Stories by Field takes structured filters in a body instead, which is the node to use when a machine is assembling them: every filter is optional and the ones you set are combined. It is a POST because the filter set is a body rather than a URL, but it reads and changes nothing. It is also the only endpoint on this API that takes a created-between window, which makes it the one place a scheduled incremental read has something to hold on to, and its response is a bare array with no pagination and no total, so a broad filter returns a broad response. Shortcut: Search Everything is shaped differently again: it returns an object with a separate envelope per entity type rather than one merged list, so a consumer walks several cursors instead of one. And Shortcut: Search Docs is the odd one out, taking a title rather than a query, understanding none of the search operators and matching titles only, with archived, created-by-me and followed-by-me filters the others do not have.

Reacting to Shortcut, and running without a person

This integration ships no Shortcut trigger node, so Shortcut workflows run on a schedule by default, which covers reporting, digests and hygiene work well. If you need to react to an event, Shortcut: Create Outgoing Webhook registers a URL for Shortcut to post its activity events to, and you can point that at Mattering's generic Incoming Webhook trigger. Two parts of that are yours rather than the integration's. Set the secret on the registration and verify the signature on every delivery, because a webhook URL is otherwise open to anyone who learns it. And note that the registration call answers 204 with no body, so the integration's own id does not come back from the create: read it afterwards with Shortcut: Get Outgoing Webhook if you will need it for Shortcut: Delete Outgoing Webhook later. Deleting a registration tells nothing downstream; deliveries simply stop.

From AI assistants over MCP, and how this sits beside Shortcut's own server

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT and Matter, the assistant built into the platform, can all drive the same surface. Shortcut also publishes its own MCP server, and you should know about it before choosing: it is remote, hosted at mcp.shortcut.com, and it authenticates with OAuth rather than the API token used here, so it is not a second route to this credential. Both of Shortcut's MCP repositories on GitHub are archived, with the README stating that all future development moved to the remote server, and Shortcut's pricing table lists MCP Server as included on every plan. For a Shortcut-aware assistant inside an editor, theirs is the direct answer. What this integration adds is everything that happens when the conversation ends: the same 126 nodes are canvas steps, so a workflow runs on a schedule or an inbound webhook with nobody present, chains Shortcut with every other connector in one workflow, holds one credential in a shared workspace store rather than in each person's local config, and flags the 16 nodes that destroy something so a reviewer or a condition can stand in front of them. The sensible split when pointing an assistant at this is by category: the 66 read nodes are low risk, and the deletes are better behind an approval step.

On the automation canvas

Shortcut nodes chain with every other node in Mattering. A form submission or an inbound alert can run Shortcut: Create Story and then Shortcut: Create Task on Story, with Shortcut: Create Story Link relating it to the work it blocks, remembering that the link reads subject verb object so reversing the two ids reverses the meaning. A scheduled workflow can read Shortcut: List Iterations and Shortcut: List Iteration Stories into an AI step and open a Mattering Productivity task for the person running the review. A metric source can push an observed value through Shortcut: Update Key Result so an objective updates itself, with Shortcut: Set Objective Health appending a status to the trail when the situation genuinely changed and Shortcut: Update Health Record reserved for correcting a typo, since it overwrites rather than appends. Shortcut: Find Stories by External Link is the node that makes a two-way sync tractable, answering which stories point at a URL in another system without a search query, though it matches the whole URL, so normalise trailing slashes and query strings before relying on it. The pickers do much of the wiring: 21 story-bearing nodes carry an optional epic field whose only job is to scope the story picker beside it, because Shortcut has no unscoped story lister and a workspace holding tens of thousands of stories would otherwise offer an unusable list. That field is never sent to Shortcut.

Troubleshooting

Test Connection fails with a 401
Shortcut tokens do not expire or rotate on their own, so a 401 here is almost never staleness. Three causes account for nearly all of them: the token was revoked in Shortcut, the member who minted it was deactivated, or the value was pasted with whitespace around it. Check the member's account first, since a deactivated member takes their tokens with them, then regenerate the token in Settings > Account > API Tokens and paste it again. If a workflow was working yesterday and is failing today with nothing changed on your side, a revoked token is the likeliest explanation.
A node fails with a 403 while other nodes work
A 403 means the token is valid and Shortcut refused the call, which is a different finding from a 401 rather than a worse one. On this API it is almost always the acting member's own role. A Shortcut token carries the permissions of the member who minted it and nothing more, so there is no scope to widen on the Mattering side and no setting that fixes it: either the member's role changes in Shortcut, or the token is reminted from a member who has the access. Run Shortcut: Get Current Member to confirm which member you are actually acting as, since a shared credential is easy to misremember. One 403 is not about roles at all: Shortcut: Delete Doc requires admin access to that specific doc, so a member who can read and edit it may still be refused.
Requests start failing partway through a run with a 429
Shortcut allows 200 requests per minute and its documentation specifies no Retry-After header on the 429, so there is nothing to read and back-off must be fixed or exponential. Do not add a tight retry: reading a missing header as zero is what turns one 429 into a minute of them. The limit is shared by everything using the credential, so count the whole workflow rather than one node. The structural fix is to stop looping: most listers on this API return the entire collection in one call, so replace a list followed by one read per row with a single wide read, and use the scoped listers such as Shortcut: List Epic Stories and Shortcut: List Iteration Stories instead of fanning out over story ids.
A node returns 404 for an id that definitely exists
Check the id KIND before anything else, because Shortcut uses two and mixing them is the commonest avoidable failure here. Stories, epics, iterations, objectives, labels, categories, projects, files, linked files and workflows use integer public ids. Members, teams, docs, custom fields, story templates and health records use UUID strings. A UUID sent where an integer belongs, or the reverse, fails without a useful message. The second cause is visibility rather than existence: the token acts as the member who minted it, so a record that member cannot see in the web app is not found here either, which reads exactly like a wrong id. Shortcut: Get Current Member tells you which identity to check against.
A story was created but landed in the wrong column
A story created without a workflow state id lands in the workspace default state rather than where you meant it, which is Shortcut's behaviour rather than a fault. Set the state at creation on Shortcut: Create Story instead of correcting it afterwards, and set the team at the same time, because the team owning a story governs which workflow its states come from. If the state id is rejected outright, it almost certainly belongs to another workflow: Shortcut scopes workflow states to one workflow and there is no global list of states, which is why the state pickers in this integration ask you to choose a workflow first. Run Shortcut: List Workflows and then Shortcut: Get Workflow to read the valid states for the board you are writing into. Epic states are different and simpler: there is exactly one epic workflow per workspace, so Shortcut: Get Epic Workflow takes no id.
An update wiped owners, labels or sub-tasks that were already on the story
The list fields on Shortcut: Update Story replace rather than append, so sending one owner id leaves the story with exactly one owner and the sub-tasks field is treated as the final state of the parent's sub-tasks, unlinking anything missing from the array. This is Shortcut's contract, not a bug, and the fix is to use Shortcut: Update Stories in Bulk even for a single story, because that is the node exposing add and remove semantics. The same shape catches people on Shortcut: Update Custom Field, whose values field is the final state of the allowed value list: read the field with Shortcut: Get Custom Field first and send the existing entries back alongside your additions.
Paging through search results ends in an error rather than an empty page
Shortcut caps search at 1000 total matches across all pages and returns a dedicated max-results error past that, rather than an empty page, so a walk-every-page loop against a broad query terminates in a failure and that is the documented behaviour. Narrow the query rather than paging further, splitting by date range, team or state until each slice fits. While you are there, check how you are following pages: the next value on the search nodes is not an opaque token but the path and query string of the next page, and Shortcut asks you to follow it rather than reconstruct it because result ordering shifts as ranking decays and new work is created. The node accepts either the whole path you copied out of a previous step or the bare token, so pasting what you see is fine.
A bulk create failed and nothing was created
That is the documented behaviour rather than a partial failure you can recover from. Shortcut: Create Stories in Bulk has no partial-success mode: one malformed element fails the whole request, so no stories land rather than the good ones landing and the bad one erroring. Validate the array upstream, and remember that each element takes exactly the same fields as Shortcut: Create Story, so a missing name or a mistyped workflow state id in element forty is enough to fail elements one through thirty-nine. The response on success is the created stories in the order they were sent, which is what a following step should key off rather than assuming the input order survived.
A list node returns an enormous response, or a picker is unusably long
This is the API's default shape rather than a misconfiguration. 35 of Shortcut's 70 read endpoints return a bare JSON array with no page parameter and no total, so Shortcut: List Epics returns every epic the token can see in one response, which is fine on most workspaces and large on a big one. For epics specifically, Shortcut: List Epics (Paginated) is the only page-numbered endpoint on the API, so use it when the size matters, asking for page 1 first since there is no page 0. For stories there is no unscoped lister at all, which is why the story pickers scope off an epic: the optional epic field beside them exists only to narrow the list and is never sent to Shortcut. If you need a whole team's stories, Shortcut: List Team Stories takes limit and offset, though it still returns a bare array with no total, so you know you have finished only by receiving fewer rows than you asked for.
A picker on a node stays empty
Start with the lister the picker reads from and run it on its own: if Shortcut: List Epics returns nothing, no epic picker will populate either, and the usual cause is the acting member's visibility rather than the picker. The next thing to check is whether a parent field is set, because several pickers are dependent by design. Workflow state pickers need a workflow chosen first, since Shortcut scopes states to one workflow. Story pickers need an epic chosen first, since there is no unscoped story lister. Comment pickers need their parent story or epic. A few fields are free text on purpose rather than broken pickers, and each names where to read the id: story task ids arrive nested on Shortcut: Get Story, key result ids arrive on Shortcut: Get Objective, and outgoing webhook ids are not listable at all because Shortcut exposes get and delete but no list for them.
Something was deleted and needs to come back
It cannot. Shortcut exposes no undelete for any resource and every delete on this API answers 204 No Content, which is why 16 of the 18 delete nodes are flagged destructive and each states its own blast radius. What survives differs: deleting an epic leaves its stories with their epic id cleared, deleting an objective leaves its epics, and deleting a label leaves the work but strips the label from every story and epic carrying it. Deleting an uploaded file is the least recoverable, because the bytes go too and this integration cannot re-upload them. Going forward, use archiving as the reversible operation: set archived to true through the matching update node, and where you do intend to delete stories, do it through Shortcut: Delete Stories in Bulk, which removes only stories that are already archived and is the one delete on the API with a guard built in.

Shortcut is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products