Overview

Your API Key

Each User has a Docs API key. To generate, view, or regenerate the API key, click the "person" icon on the top right of your account, next to the search, then click Your Profile.

Your Profile

Next, click the Authentication link in the menu on the left and select API Keys tab

API Keys

Note: If you don't see an API key in your profile, that's because you haven't been granted the "Docs: Create new, edit settings & Collections" permission by the Account Owner or an Administrator.

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.

Correlation ID Response Header

All responses from the API contain a Correlation-Id header. This header contains a value (a UUID) which is used by Help Scout to trace interactions between our various APIs. In the case of an error and you're contacting the Help Scout team then include one or more of these IDs and developers will be able to assist quicker.

For instance if you wanted to print all headers on a curl request to access the Correlation-Id you would do the following:

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

You would see console output like the following:

  HTTP/1.1 200 OK
  Correlation-Id: 08d7aa72-4afb-4c2a-b027-45dacee1e1a0

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: 404 Not Found
{
    "code": 404,
    "error": "Resource not found"
}
↑Back to top
© Help Scout 2024