Authentication & rate limits

How Havoptic API keys work, the anonymous, Developer, Pro and Team tiers, and how to read the RateLimit-Policy, RateLimit and Retry-After headers.

Every read endpoint works without a key. A key raises your limits, gives you a daily usage view, and is required for webhooks.

API keys

Sign in with GitHub on the API keys dashboard and create a key. It looks like hv_live_ followed by 32 letters and digits and is shown once; Havoptic stores only its SHA-256 hash. You can hold up to 5 active keys and revoke any of them at any time.

Send it on requests to api.havoptic.com:

curl -H "Authorization: Bearer $HAVOPTIC_API_KEY" "https://api.havoptic.com/v1/changes?kind=breaking"

# Also accepted:
curl -H "X-Api-Key: $HAVOPTIC_API_KEY" "https://api.havoptic.com/v1/changes?kind=breaking"

Tiers

Per-minute limits are a fixed 60-second window per caller. Daily quotas reset at 00:00 UTC. The tier that served a request is echoed in the Havoptic-Tier response header.

Rate-limit headers

api.havoptic.com sends the IETF RateLimit headers:

HTTP/2 200
Havoptic-Tier: developer
RateLimit-Policy: "developer-minute";q=120;w=60, "developer-day";q=10000;w=86400
RateLimit: "developer-day";r=9874;t=41230

• RateLimit-Policy lists each policy: q is the quota, w the window in seconds.
• RateLimit reports the daily quota: r requests remaining, t seconds until reset. The per-minute window is advertised as a policy only.
• Over the limit you get 429 rate_limited with Retry-After in seconds.

Staying under the limits

• Data refreshes hourly. Responses are cached for about 5 minutes (Cache-Control: public, max-age=300); polling faster returns the same body.
• Use If-None-Match with the last ETag (see Pagination & caching).
• Prefer webhooks over polling for new releases.
• The SDK retries 429s for you with new Havoptic({ retry: true }), honoring Retry-After.

Developer docs · API reference · OpenAPI · Havoptic