You’ll need an account ( sign up free ) and a site you control. The five-minute path:

1. Add the site under /sites and pick a verification method.
2. Drop the verification file (or DNS TXT) into your origin.
3. Click Verify.
4. Mint an API key under /api-keys.
5. POST URLs as they change.

Two methods are supported. File serves a small text file at a well-known path; DNS adds a TXT record. Pick whichever your stack makes easy.

# File method — example token shown in the dashboard
GET https://example.com/.well-known/betterindexnow.txt
→ 200  <token>

# DNS method
TYPE  NAME                            VALUE
TXT   _bin.example.com                <token>

We re-check verified sites every 24 hours. If the token is missing for 7 days the site is automatically marked unverified.

Single-URL submission is a small JSON POST. The engine list is optional — if omitted, the URL is fanned out to every engine you’ve enabled for the site.

curl -X POST https://api.betterindexnow.com/v1/sites/42/submissions \
  -H "Authorization: Bearer $BIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/blog/new-post"}'

Successful response:

HTTP/1.1 202 Accepted
{
  "ok": true,
  "ids": [9182, 9183, 9184],
  "engines": ["bing", "yandex", "seznam"],
  "already_queued": 0
}

Up to 50,000 URLs in a single request. Send text/csv with one URL per row. A header row containing url is accepted and skipped.

curl -X POST https://api.betterindexnow.com/v1/sites/42/submissions/bulk \
  -H "Authorization: Bearer $BIN_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @urls.csv

Per-row errors are returned in the response so you can fix and retry just the bad rows.

Subscribe to events under /webhooks. Each delivery is signed with HMAC-SHA256; the signature lives in the X-BIN-Signature header.

# Pseudocode — verify a delivery
expected = hmac_sha256(secret, body)
if expected != request.header["X-BIN-Signature"]:
    return 401

We retry failed deliveries with exponential backoff up to 24 hours, then mark the subscription stale and email you.

We return RFC 7807 problem documents on every non-2xx response. Inspect type, title, and detail:

HTTP/1.1 402 Payment Required
{
  "type": "quota_exceeded",
  "title": "Monthly URL quota exceeded",
  "detail": "Plan starter allows 25,000 URLs / month; usage is at 27,500.",
  "status": 402
}

Quotas reset on the first of each month UTC. We allow a 10% soft buffer before mutating endpoints start returning HTTP 402; reads continue working so you can audit and upgrade.

Per-IP rate limit is 60 req/sec on read endpoints, 10 req/sec on mutating endpoints. Bulk endpoints don’t count individual rows against the per-second limit.