Your API Key
Each User has a Docs API key, which is separate from any help desk API keys. You can view or regenerate your key from your User Profile, on the API Keys tab:
This is an HTTPS-only API. Authentication is based on API Keys. Each API Key is associated with a Help Scout user. Results returned from various responses are based upon the role of the user to which the API key is tied.
The API Key is passed via HTTP Basic Authentication and goes in the username field. A dummy password, such as X, goes in the password field.
To try the API via curl on the command-line, the general form used would be:
For instance, if your API key is 60783dd23ef, you would execute:
All API requests are made to https://docsapi.helpscout.net/ and all requests are served over HTTPS. The current version is v1.
The API will only support JSON at this time.
Each account is allowed to make a limited number of requests per 10 minute period. This limit is based on the number of Docs Sites the account has:
|Number of Sites||Rate Limit|
|1||2000 requests every 10 mins|
|2||3000 requests every 10 mins|
|3 or more||4000 requests every 10 mins|
Headers are returned with every API response to detail the current rate limiting status:
|X-RateLimit-Limit||The maximum number of requests the account is permitted to make per 10 minute period|
|X-RateLimit-Remaining||The number of requests remaining in the current rate limit window|
|X-RateLimit-Reset||The number of seconds until the current rate limit window expires|
Response code 429 is returned when the limit has been reached.
Note: Usage of the Help Scout Docs administration interface generates requests to Docs API. These requests also count towards the rate limit.
The API returns one of three envelopes depending upon the request issued:
- Single Item Envelope
- Collections Envelope
- Error Envelope
Single Item Envelope
All dates/times are returned in ISO8601 format and in UTC timezone.
All dates/times are returned in ISO8601 format and in UTC timezone. Collections return a maximum of 50 records per page.