Shorthand provides developers access to Shorthand stories through the use of the Shorthand API. The Shorthand API is an easy way to access and download stories into an external CMS. This API is the same API which powers our Wordpress and Drupal plugins.

To discuss setting up this option for your Shorthand workspace, please contact us for details.

Some technical detail:

Security:

The Shorthand API requires TLS1.2 support, please ensure that your client code supports this protocol.

Authentication:
Authentication is done at a team level, stories are gathered across the entire team. Authentication is token based, requiring a TOKEN in the Authorization: Token HTTP header. Only stories that are marked 'ready for publishing' or ’published’ will be available.
To generate an API token, click on the dropdown arrow on the right-hand workspace dropdown menu and choose ”EDIT SETTINGS” under your organization’s workspace.

https://cdn.elev.io/file/uploads/p9jpW4cYPyd717Yrl8GDNdjJSSFuIbXFNYXBroJVATQ/N8AlTrANfkxQI57d43lZRQc7O01pJWtyvyzUFZ9X1Xw/menu2-Djw.jpg


At the bottom of the resulting page is a section labelled API Tokens. Click "ADD A NEW API TOKEN", choose a team, and click "ADD TOKEN".

https://cdn.elev.io/file/uploads/p9jpW4cYPyd717Yrl8GDNdjJSSFuIbXFNYXBroJVATQ/w34CTrGxHgh8Nhzj7TelQaPa0celNZcW9Ck3Jt35-7s/api-token-Wi0.gif

API Signature:
Authorization: Token [TOKEN]
https://api.shorthand.com/[ENDPOINT]

Endpoints:

GET v2/token-info/

Returns an object of the teams profile.
GET v2/stories/

Returns a list of stories that exist for the current user.
GET v2/stories/[STORY_ID]/

Returns a ZIP archive of the story.
GET v2/stories/[STORY_ID]/settings

Returns settings for that story
POST v2/stories/[STORY_ID]/settings

Send an updated JSON nested dict of the 
GET response to update settings.  
Note that you can send just the keys
you wish to update.  

e.g.
{ "meta" : { "title" : "My new title" }}

Notes:
Protocol must be https
content-type header must be application/json

ZIP file:
The ZIP file contains all information related to the story, including all assets, CSS and JS files. For more information about the ZIP file see here.

Auditing:
Note that when the API is used to publish a story, the user who created the token will be registered as the user who last published the story.  Take this into account when creating API tokens - it may be worthwhile creating an API user account to ensure valid reporting.

v1 Legacy:
If your account has both v1 and v2 stories, the v2 API will list all stories from both.  Please note that to get a ZIP of a v1 story, you should continue to use the v1 API.  v1 and v2 stories are significantly different, so we keep these APIs separate to ensure there is no confusion.