Authentication
API keys and usage limits.
Scanning and /usage need an API key (the static issue catalog does not). There is no anonymous tier: the API identifies callers by key only and never looks at client addresses. Each key comes with its own rate limit and monthly scan allowance.
Sending a key
Authorization: Bearer <api_key>or, for clients that cannot set Authorization:
x-api-key: <api_key>curl -s -X POST https://carbonfooter.nl/api/v2/scans \
-H 'Authorization: Bearer cf_live_…' \
-H 'Content-Type: application/json' \
-d '{"url": "example.com"}'No key, no request
A request without a key, or with an unknown or revoked one, is answered with 401 UNAUTHORIZED and nothing is scanned. If you get a 401, check that the header is there and the key is still active.
Getting a key
Keys are issued by the CarbonFooter team; there is no self-service signup yet. Ask for one at [email protected]. A key is shown once, when it is issued. We store only a hash of it, so it cannot be looked up later — if you lose a key, ask for it to be revoked and replaced.
Treat a key like a password: keep it on your server, never in browser code or a public repository.
Limits
Two things are counted separately.
| Default per key | |
|---|---|
| Requests | 60 per minute |
| New scans | 1000 per calendar month (UTC) |
Limits are set per key, so yours may differ — GET /api/v2/usage tells you.
What counts as a scan
Only a new scan — one that actually runs a browser — is counted.
- A result served from cache is free. If you are out of scans you can still read every cached result.
- A scan that fails because of a fault on our side (
500,503) is not counted. - A scan that fails because of the page (
422, or a504timeout) is counted: the browser ran. - A request that is rejected before scanning — invalid, or over the request limit — costs no scan.
Rate-limit headers
Responses from /scans and /usage carry the state of your per-minute limit (a 401 does not, since there is no valid key to report on):
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute |
X-RateLimit-Remaining | Requests left in the current minute |
X-RateLimit-Reset | When the current minute ends, in Unix seconds |
When you hit a limit
| HTTP | Code | Meaning | What to do |
|---|---|---|---|
| 429 | RATE_LIMITED | Too many requests this minute | Wait for the number of seconds in Retry-After |
| 402 | LIMIT_EXCEEDED | Your key's monthly scans are used up | Wait for error.details.resetsAt, or ask for a higher allowance |
Checking your usage
curl -s https://carbonfooter.nl/api/v2/usage \
-H 'Authorization: Bearer cf_live_…'{
"version": "2.0",
"tier": "key",
"key": { "prefix": "cf_live_a1b2", "label": "Acme agency" },
"requests": { "limit": 60, "remaining": 59, "resetsAt": "2026-11-10T12:01:00.000Z" },
"scans": {
"limit": 1000,
"used": 112,
"remaining": 888,
"period": "month",
"resetsAt": "2026-12-01T00:00:00.000Z"
}
}A null limit means unlimited.