Overview

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:

API Keys

Authentication

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:

curl --user API_KEY:DUMMY_PASSWORD API_URL

For instance, if your API key is 60783dd23ef, you would execute:

curl --user 60783dd23ef:X https://docsapi.helpscout.net/v1/collections

Endpoints

All API requests are made to https://docsapi.helpscout.net/ and all requests are served over HTTPS. The current version is v1.

Formats

The API will only support JSON at this time.

Rate Limiting

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:

Header Name Description
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.

Response Envelopes

The API returns one of three envelopes depending upon the request issued:

  1. Single Item Envelope
  2. Collections Envelope
  3. Error Envelope

Single Item Envelope

All dates/times are returned in ISO8601 format and in UTC timezone.

Status: 200 OK
{
    "article": {
        "id": 1234,
        ...
        "createdAt": "2012-07-17T13:41:01Z"
    }
}

Collections Envelope

All dates/times are returned in ISO8601 format and in UTC timezone. Collections return a maximum of 50 records per page.

Status: 200 OK
{
    "page": 1,
    "pages": 24,
    "count": 1154,
    "items": [
        {
            "id": 1234,
            ...
            "createdAt": "2012-07-17T13:41:01Z"
        },
        {
            "id": 5678,
            ...
            "createdAt": "2012-07-15T08:12:15Z"
        },
        ...
    ]
}

Error Envelope

Status: 403 Forbidden
{
    "status": 403,
    "message": "The specified resource was not found: '/v1/fake'"
}