While the Shortcut tool is chock-full of functionality yet remains streamlined, we understand that not everything can be done using the UI. This is where the Shortcut Rest API comes in.

As you might know, the Shortcut REST API provides a greater amount of control over your workspace’s Shortcut data than what is possible using the Shortcut web app. You can use this API to build custom integrations, automate even more of your workspace’s workflow, or gather specific data to be used for archive purposes, custom reporting, and analytics.

We understand the API may require some prerequisite technical knowledge and resources, though. As we've seen users write in with similar requests that make good use cases for the API, we've gathered together some of our Tips, Tricks, and Workarounds.

If you have any questions about anything related to our API or this documentation, please let us know - we’re happy to help!

Obtaining Data not available in a CSV Export:

We've seen examples of users who are seeking to do an export of Workspace data, but certain data, unfortunately, is not included in that CSV Export

Method 1:

Users can perform a full Workspace export via the Organization and Workspace dashboard in the UI. While associated comments (i.e. Story or Epic) and attachments are not included, as a suggestion, active users of a Workspace can use the API search endpoint, which will include attachments (as a URL), branches, commits, PRs, and Story comments.

Entering a query like the one seen below, or a more specific query using the value found in our Help Center article on Search Operators, in your GET request body, which will return all Stories across the Workspace:

{
"page_size": 25,
"query": "is:story"
}

The results will be paginated; the maximum per response is 25 Stories.

Method 2:
Granulate the results by starting in the UI, navigating to the Advanced Search page, and using the Search Operator for has:attachments which would show you all the Stories with attachments. You can also do the same for those Stories that have comments using the has:comment Search Operators. Each of those respective results can then be exported as a CSV file for reference. Attachment URLs are not included in the CSV file.

• For attachments:
  • The List Linked Files Endpoint: https://developer.shortcut.com/api/rest/v3#List-Linked-Files
    • “linked_files” are the Dropbox/Google Drive/Box “attachments” in the UI. We only keep the URL, and we don’t have direct access to the bytes. They’re just a link to the original source.
  • The List Files Endpoint: https://developer.shortcut.com/api/rest/v3#List-Files
    • “files” are actual file uploads attached directly to the Story (UploadedFile type in the API docs). It should be possible to download those simply by GET-ing the UploadedFile.url with the necessary API token.
  • Note:
    • The Responses for both of these options will also have the associated Story ID
    • When you receive the response in the client you are using, you may be able to "CMD+Click" the thumbnail URL link, which will open a browser page of the image. Alternatively, you can copy & paste that thumbnail URL into the browser address bar to open the image in the browser. From there, right-clicking on the image and utilizing the browser's "Save the Image as" functionality, you should be able to save that image to your computer.
  • As a reference, Files that are dragged and dropped into text (description or comment), which the API doesn’t know about, are only in the markdown text. You need to parse the description and look for URLs that look like file uploads. Retrieving them should be the same; just follow the link.
    • Please note that dragged-and-dropped file uploads create an UploadedFile record, but not a reference to it from the Story
• For Story comments:
  • Use the List Story Comments Endpoint: https://developer.shortcut.com/api/rest/v3#List-Story-Comment
    • This is done per Story but can be written into a script if you have the technical resources available.

Updated July 17, 2025 15:22