Get started
Authentication and headers
How to send the API key, and the headers the API reads and returns.
The API key
Section titled “The API key”Send the key in the Authorization header of every request to /v1/analysis:
Authorization: Bearer <api_key>Content-Type: application/json- Only in the header. Never in the URL or the body: URLs end up in logs and browser histories.
- Only on your servers. A key in a browser, a mobile app or a public repository can be read by anyone. If a key may have been exposed, contact us and we replace it.
- A missing, malformed or unknown key returns
401 INVALID_API_KEY, with the headerWWW-Authenticate: Bearer. - A key whose plan does not include an endpoint returns
403 TIER_NOT_ENTITLED. GET /healthneeds no key.
Content-Type must be application/json; parameters such as charset=utf-8 are fine. Anything else returns 415 UNSUPPORTED_MEDIA_TYPE, and the body is not read.
Your own request id
Section titled “Your own request id”You may send an X-Request-Id header to follow a call through your systems and ours. The API uses your value when it is exactly one header of 1 to 128 characters from A–Z a–z 0–9 . _ ~ -. Any other value is ignored and replaced by a generated UUID; it never fails the request.
Headers on every response
Section titled “Headers on every response”Every response carries these, errors included:
| Header | What it holds |
|---|---|
X-Request-Id |
The request’s identifier: your own, if it was valid, otherwise a generated UUID. The same value is result_id in a successful response and part of instance in an error. Quote it if you contact us. |
RateLimit-Limit |
Requests allowed per window for your key. |
RateLimit-Remaining |
Requests left in the current window. |
RateLimit-Reset |
Seconds until the window ends. Windows start on every full UTC hour. |
Some responses carry one more:
| Header | When | What it holds |
|---|---|---|
WWW-Authenticate |
401 | Always Bearer. |
Retry-After |
429 | Seconds to wait before sending the request again. |
Allow |
405 | The methods the path accepts. |
Header names are case-insensitive.