Quickstart

From zero to a headline in a minute

Everything on this page works on the free plan: 1,000 requests a month, no card.

1. Get a key

Create an account — you land in the dashboard with one key. The secret is shown once: it is stored hashed, so nobody, including us, can read it again. Create a second key for a second environment instead of sharing one, and give each key a name you will recognise in the usage breakdown.

2. Make a request

Send the key in the X-API-Key header (the Authorization: Bearer header works too). Keep it in your environment, never in a URL, a browser bundle or a log line.

export EB_API_KEY="eb_live_..."

curl -s "https://api.everythingblog.in/v1/feed?limit=3" \
  -H "X-API-Key: $EB_API_KEY"

Every metered response carries your standing: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix seconds), X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset (Unix seconds). Read them instead of guessing when to slow down.

3. Handle the two "no" answers

A throttled request and an exhausted allowance are different problems with different fixes, and the API separates them so your client does not have to guess.

# 429 means "come back later" and always carries Retry-After (seconds).
# 402 means the plan's allowance is spent: retrying will not help.
resp = requests.get("https://api.everythingblog.in/v1/feed", headers=headers, timeout=10)

if resp.status_code == 429:
    time.sleep(int(resp.headers.get("Retry-After", "5")))
if resp.status_code == 402:
    reset = resp.headers.get("X-Quota-Reset")  # ISO date the allowance resets
    raise SystemExit(f"quota exhausted until {reset}")
StatusCodeWhat it meansWhat to do
429rate_limitedToo many requests this minute.Sleep for Retry-After, then retry.
402quota_exceededThe month's included allowance is spent.Wait for X-Quota-Reset, or upgrade.
402spend_cap_reachedYour own spend cap is reached.Raise the cap, or wait for the reset.
403plan_requiredYour plan does not include this endpoint.Upgrade, or read X-Required-Feature.
401invalid_api_keyThe key is unknown, revoked or expired.Issue a new key in the dashboard.

4. Page through the feed

The feed is cursor-paginated: pass the next_cursor from the previous response as cursor. Cursors stay valid because they point at a position, not a page number, so new stories arriving while you page cannot duplicate or skip an item.

5. Rotate a key without downtime

Rotating returns a new secret and invalidates the old one immediately. Deploy the new secret first, then rotate — or rotate first and accept a moment of 401s, which is the honest trade-off of a key that cannot be read back.

# Create a key (the secret is in the response and nowhere else):
curl -s -X POST "https://api.everythingblog.in/v1/me/keys" \
  -H "X-API-Key: $EB_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"production"}'

# Rotate: returns a new secret and stops the old one immediately.
curl -s -X POST "https://api.everythingblog.in/v1/me/keys/<key-id>/rotate" -H "X-API-Key: $EB_API_KEY"

# Revoke.
curl -s -X DELETE "https://api.everythingblog.in/v1/me/keys/<key-id>" -H "X-API-Key: $EB_API_KEY"

Next