Skip to content

Get started

Authentication and headers

How to send the API key, and the headers the API reads and returns.

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 header WWW-Authenticate: Bearer.
  • A key whose plan does not include an endpoint returns 403 TIER_NOT_ENTITLED.
  • GET /health needs 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.

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.

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.