Authentication

The API has three tiers. Anonymous (no key) requests are treated as free tier.

Tier	Daily limit	Lookback	Who gets it
free	20 / day	7 days	Default for all users, including anonymous requests
pro	100 / day	7 days	Active paid Pro subscription, OR founding members within their first year
dev	500 / day	90 days	Active paid Developer subscription, OR the global archive key

All tiers get every endpoint. The only differences between tiers are the daily request cap and the lookback window. Free and Pro both top out at 7 days of history; only Dev reaches 90 days.

A request without a key is fine. You only need a key when:

You want a stable per-user daily quota instead of the shared per-IP rate limit, OR
You need history beyond 7 days (Dev tier required), OR
You want to see your usage on the account page

Getting a key

Sign up at https://divergence.news/auth/signup.
Open https://divergence.news/account.
Click "Generate API key", optionally label it ("My laptop", "CI bot").
Copy the key once. The full key is shown only at creation time; only the prefix (e.g. dv_api_AbCd...) is retained.

The key format is dv_api_ followed by 43 url-safe base64 chars. Treat it as a secret. Keys can be revoked at any time from the account page.

Sending the key

Use any of these (in order of preference):

curl -H "X-API-Key: dv_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://divergence.news/api/v2/events?limit=10"

curl -H "Authorization: Bearer dv_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://divergence.news/api/v2/events?limit=10"

curl "https://divergence.news/api/v2/events?limit=10&token=dv_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Prefer the header forms; the query-string form leaks the key into server logs and browser history.

Error responses

Status	Code	When
401	`invalid_api_key`	The key was supplied but does not match any active key. No silent downgrade to anonymous.
401	`archive_token_required`	The request reaches data older than your tier's lookback window (7 days for free/pro, 90 for dev).
429	`daily_limit_exceeded`	You hit your tier's daily cap. Resets at UTC midnight.
429	`rate_limited`	Per-minute burst limit. See rate-limits.

MCP tokens

Dev-tier subscribers can also generate dv_mcp_<token> keys for the MCP server (Claude Desktop and other MCP clients). They are managed from the same account page and obey the same per-tier daily limits.