Overview and Authentication (v2 JSON API)

Updated on

The ScreenSteps v2 JSON API is designed to allow you to:

  • Extract content from your ScreenSteps site for backup purposes
  • Extract content from your ScreenSteps site for publishing to other systems
  • Create and update content in your ScreenSteps account

Important: If you are using the API to pull the HTML from your ScreenSteps site and display it in your own website then you will need to update the image permission settings for your site to get non-expiring image URLs.

See: Why are the links to my images broken?

Security and authentication

All API requests must be done over SSL. Authentication is done using basic authentication with:

  • A ScreenSteps user's login name and password, or
  • A ScreenSteps user's login name (admin or contributor user only, will not work with API access users) and an API token

You can locate the a user's login on the User Profile screen.

See: How to create an API Token

API tokens are account wide and are not tied to an individual user on your account. 

If you want to limit the access of an integration to your content then you should use a username/password combination for a user who has the permissions you want.

For example, if you only want an integration to have access to a single site on your account then you should create an API Access, Contributor, or Reader user, assign them to the site and use their username/password for the integration.

Basic authentication

Use the following format:

{login}:{api_token or password}
curl -u [email protected]:st_lOXL-sHouKuTan3i-LtOgg
Click to copy
Rate Limiting

ScreenSteps will impose a rate limit of 300 requests/minute. If you exceed this limit you will receive a 429 response. The JSON body will a retry_in value that will tell you how many seconds you need to wait to retry your request.

Request format

You must set an Accept: application/json header on all requests.

Response format

All responses will be in JSON format.

Will unpublished content be returned by the API?

If you are using the search API then no unpublished articles will be returned.

If you are listing the contents of a site, manual, or chapter then it depends on the type of user that you are authenticating with. For api and reader users unpublished content is not returned. For admin and contributor users unpublished content is returned.


Travis Thelen

How do I make an authenticated request to the v2 API? For example the site search call.

Trevor DeVore

@Travis - All authentication is done using Basic access authentication. The "Security and authentication" section of this article explains the format to use with Basic access authentication and provides an example of making the call with curl.

Add your comment

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Previous Article How to Publish/Push an Entire Manual to Zendesk
Next Article Example requests and responses (v2 JSON API)
Still Need Help? Contact Us