Authentication

One header, on every request except the self-describing index. 

Authorization: Bearer <your api key>

Your key is on your profile page, where it can also be regenerated if it leaks. A paid plan is required: without one, every endpoint except / and /v1/account answers 403 plan_required.

Why not ?key=

A key in the query string ends up in places you did not put it: web server access logs, browser history, proxy logs, and the Referer header of anything the response links to. The API therefore does not accept it, and answers 401 missing_key saying so.

The old ?export= urls on the main site do still accept ?key=, because scripts written years ago depend on it and taking it away would break them. That is the one place it lives - see the old export urls.

Checking a key works

/v1/account is the cheapest call: it spends no quota and works even on an account with no plan, so it answers both "is this key valid" and "what am I entitled to". 

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account
{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

What can go wrong

StatusCodeMeaning
401missing_keyNo Authorization: Bearer header. A key in the query string does not count.
401invalid_keyThe key does not name an account. Check for a stray newline or quote.
403plan_requiredThe key is fine; the account has no paid plan.

A 401 also carries a WWW-Authenticate: Bearer header, so http clients that handle authentication generically behave sensibly.

Next Making requests