Authentication
One key, one header
Send your key
Every /v1 request needs your API key in the X-API-Key header. There is no login, token exchange or query-string key.
curl -H "X-API-Key: $PEAR_API_KEY" \
https://api.pearatings.com/v1/account/v1/account is a good first check: it returns your tier, its limits, what it includes and how many calls you have used this month.
Keep your key safe
- The key is shown once, when you sign up or subscribe. Only a scrambled copy is stored, so it can't be shown again.
- Store it in an environment variable, not in code. Anyone with the key can spend your calls.
- Don't call the API from a web page a visitor loads: the key would be visible in their browser. Call it from your own server or script.
- Lost or leaked your key? Email pearatings@gmail.com from the address you signed up with and the old key will be turned off and replaced.
Errors
A failed request returns a JSON body with one field, detail, that says what went wrong in plain words:
{"detail": "Missing API key: send it in the X-API-Key header"}| Status | Meaning | What to do |
|---|---|---|
| 400 / 422 | A parameter is missing or not valid (an unknown division, a bad date, a season out of range). | Check the endpoint in the API Reference. |
| 401 | No key was sent, or the key is not one we issued. | Send the key in X-API-Key. |
| 403 | The key is not active (a subscription lapsed or the key was replaced), or the endpoint needs a higher tier. For a tier error the X-Pear-Required-Tier header names the tier. | Subscribe or upgrade on the pricing page. |
| 404 | Nothing matches: an unknown team, game id or player id, or a season with no data. | Check the name or id. |
| 429 | You are over your tier's per-minute or monthly limit. The Retry-After header gives the seconds to wait. | Wait, then retry. See Tiers and limits. |
| 500 | Something broke on our side. | Retry later; email if it keeps happening. |