Getting Started
Authentication
API keys and authorization
API keys
All endpoints (except /v1/health and webhooks) require a Bearer token.
curl -H "Authorization: Bearer rw_..." \
https://api.rewind.rest/v1/listening/recentA key is rw_ followed by 64 hex characters.
Key types
| Key type | Access |
|---|---|
| Read | All GET endpoints |
| Admin | All endpoints including sync triggers, data management, and key management |
Read keys are safe to use in client-side applications. Admin keys should only be used server-side.
Scope is recorded server-side, not encoded in the key, so a read key and an admin key look identical. Label them when you create them; you cannot tell them apart later from the key alone.
Rate limiting
Each API key carries its own limit over a 60-second sliding window, 60 requests per minute by default. Read X-RateLimit-Limit for the value applied to your key. Every response carries the current state in headers, and exceeding the limit returns 429 Too Many Requests.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per window |
X-RateLimit-Remaining | Requests left in the current window |
X-RateLimit-Reset | Unix timestamp (seconds) when the window resets |
Retry-After | Seconds to wait before retrying, sent only on 429 |
Unauthorized responses
If your key is missing or invalid:
{
"error": "Unauthorized",
"status": 401
}