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

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.

Now we also understand the API requires technical knowledge and resources, we've gathered together some of our Tips, Tricks, and Workarounds using the API.

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, navigate to the Advanced Search page and use the Search Operator, has:attachments which would show you all 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.

• Using the API, you then would use:
  • The List Linked Files Endpoint: https://developer.shortcut.com/api/rest/v3#List-Linked-Files
  • The List Files Endpoint: https://developer.shortcut.com/api/rest/v3#List-Files
    • 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 would open a browser page of the image or copy & paste that thumbnail-URL into the browser address bar which would 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, here are the differences in Attachments:
    • “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.
    • “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.
    • Files that are dragged and dropped into text (description or comment), which the API doesn’t actually 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 24, 2024 20:34