Documentation
Authentication
How to authenticate Scanna API requests with your API key, including header precedence and error responses.
Pass your API key via the x-api-key header on every request (except
/health, which is public and unmetered).
curl -H "x-api-key: YOUR_KEY" "https://api.scanna.xyz/hot"Header precedence
x-api-key is the preferred, canonical header. Authorization: Bearer YOUR_KEY
is also accepted as a fallback for SDKs and generated code that default to
Bearer auth. Both are bucketed per-key by the rate limiter.
# Equivalent — Bearer fallback
curl -H "Authorization: Bearer YOUR_KEY" "https://api.scanna.xyz/hot"Production keys are formatted as sk_live_ followed by 64 hex characters.
Errors
A missing or invalid key returns 401:
{
"error": "UNAUTHORIZED",
"message": "Valid API key required. Pass via x-api-key header (preferred) or Authorization: Bearer <key>."
}Note
If a correctly-formatted key is presented but the database is temporarily
unreachable, the API returns 503 SERVICE_UNAVAILABLE rather than a misleading
401 — so you can distinguish "bad key" from "try again shortly".
All error responses share the shape { "error": "<CODE>", "message": "<text>" }.