Upgrade to the Shortcut API v3 for more stability and support

We are moving the Shortcut API out of Beta to v3!

By migrating to the Shortcut API v3, organizations can now take advantage of @-mention parsing in comments and additional enhancements coming soon, such as:

• Export API to gain more control of your data
• Ability to link Shortcut Stories to external tickets

Older versions deprecate on March 2nd, 2020

We are encouraging teams using v1, v2, and Beta to migrate their custom workflows to v3 as soon as possible. Older versions will deprecate on March 2nd, 2020, and any systems that use these older versions will no longer work.

Streamlining older versions allows us to modernize and implement updates to the API more quickly going forward. The latest update ensures that the API is continually maintained with the latest technologies that reflect the changing needs of Shortcut users.

Recommended migration steps to Shortcut API v3

We recommend these migration steps to Shortcut API v3:

1. Communicate: Share this news with your organization. There may be folks in your organization using older versions of the API, that you may not know about. Sharing this blog post in your organization's various communication channels would be a great way to do so. We will also be emailing Shortcut users who we are still seeing using older versions of the API, as we approach the March 2nd deadline.
2. Identify: Find all systems, applications, scripts, etc. that may be using the API. You can search for the text string api.clubhouse.io to quickly find code that is using the API. If you have source-controlled your implementations with GitHub, you can use their search. If you are using Linux or a Linux-like system, consider using the grep command.
3. Update: Update each API call. In most circumstances, this will simply be changing v1, v2, or beta to v3 in the URL string. In certain circumstances, you may need to rework your logic or even use a different endpoint.
   
   Migrating from Beta to v3
   Using the Beta: https://api.clubhouse.io/api/beta/search/stories
   To upgrade to v3 replace with: https://api.clubhouse.io/api/v3/search/stories
   And you're all set!
   
   Migrating from v2 to v3
   Using v2: https://api.clubhouse.io/api/v2/search/stories
   To upgrade to v3 replace with: https://api.clubhouse.io/api/v3/search/stories
   
   Migrating from v1 to v3
   If you are currently using v1 and upgrading to v3 we will be reaching out to provide more specific guidance and communication around the migration.
   
   (Important: You do not have to create a new API token. Existing API tokens will continue to work.)
   
4. Test and Deploy: Ensure your changes reflect your desired outcomes. Encourage business owners of your API applications to help validate work.

Want some ideas on how to use the Shortcut API? Check out this webinar to learn from the Shortcut team and learn how Francesco Crippa, VP of Engineering at Rollbar, is using the Shortcut API to build a Cycle Time Report.

If you have any questions about the migration please leave a comment below or reach out to our support team at [email protected]