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.
Only certain plans have acccess to the API, 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, so please ensure that your client code supports this protocol.
Authentication
Authentication is carried out at a team level, and 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.
API Token
You can access the API token page from either the story editor or the dashboard:
Story editor - select your circular account avatar at the top right corner of the page, then select API Tokens
Dashboard - select Settings on the bottom left corner of the dashboard, then select API Tokens from the Workspace Settings section
Accessing the API Tokens page from the dashboard
Generate a token
When generating a token, it can be set to apply to either all stories in the workspace, or only to stories created under a specific team. You can use both workspace and team tokens, if necessary.
When using a team token, note that the user that generated the token will need to be assigned as a collaborator of a story in order for the story to be accessible via the API. Because of this limitation, we generally recommend using a workspace token when possible, particularly if the user that generated the token is not a story editor or collaborator.
To generate a workspace token, select the 'GENERATE' button on the right side.
To generate a team token, select the "ADD A NEW TEAM API TOKEN" button, choose a team from the drop-down menu, and select "ADD TOKEN". You can generate multiple team tokens.
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 auditing or reporting.
API Signature
Authorization: Token [TOKEN]
https://api.shorthand.com/[ENDPOINT]
Endpoints
GET v2/token-info/
Returns an object of the teams profile.
GET v2/publish-configurations/
Returns a list of publish configurations that are available to the provided token; Team tokens will only be able to see configurations that are active for that team.
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]/?without_assets=true
Returns a ZIP archive of the story without media assets; Used primarily for externally hosting assets.
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
POST v2/stories/[STORY_ID]/publish
Request a story, or part of a story, be published to a provided publish configuration.
Options:
config: publish configuration ID
publishSubset: "all", "without_assets", "assets_only"
url: (optional) Subfolder/url appended to URL base.
Options in JSON format:
{
"config" : "BhItcjJDU",
"publishSubset": "all"
"url": ""
}
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.