PatentRef

Data version 20261027.2, as of 2026-10-27: the build these pages were checked against. API version 1.21.0.

Keys, limits and errors

Get a key

  1. Open https://patentref.io/api/v1/meta/signup/ in a browser, enter an email and a password, tick the box that accepts the Terms of Service, the Privacy Policy and the Acceptable Use Policy, confirm the email. Sign-in is Supabase Auth; PatentRef never stores the password.
  2. Sign in on the same page. The page mints the key, or an agent does it directly: POST https://patentref.io/api/v1/meta/keys/ with the header Authorization: Bearer <Supabase access token> and the JSON body {"terms_version": "beta-2"} (the same as {"action": "create", "terms_version": "beta-2"}), sent once the Terms of Service, the Privacy Policy and the Acceptable Use Policy (https://patentref.io/docs/legal/terms, /docs/legal/privacy, /docs/legal/acceptable-use) are read and accepted. Without it the answer is 403 ERR_TERMS with {"error": true, "terms_version", "terms": {"terms", "privacy", "acceptable_use"}, "how"}, unless the account accepted that version at sign-up or with its last key; keys minted before keep working. The response is 201 with {"error": false, "created": true, "api_key": "...", "prefix": "...", "plan": "free", "monthly_limit", "per_minute_limit", "created_at", "rotated_from", "terms_version", "note"}. The key value is shown exactly once. The same POST once a key exists answers 200 with that key's record and api_key null. POST {"action": "rotate"} revokes the active key and mints a new one (201), with the terms as for a first key; the month's count stays with the account. GET /api/v1/meta/keys/ with the token lists the account's keys, newest first, as prefixes ({"error", "email", "keys": [{"prefix", "plan", "revoked", "created_at", "rotated_from", "terms_version"}]}). A new account's first key is refused for disposable email domains (403 ERR_AUTH) and capped at 20 a day per email domain (429 ERR_SIGNUP_LIMIT). An optional "source" in the body (the campaign code of the sign-up link, its utm_source: 1 to 32 letters, digits and hyphens) adds one to that ISO week's count for the code when the request creates a key; nothing is stored with the key or the account, the answer does not change, and a code outside the rule is ignored. The sign-up page sends it by itself when its address carries utm_source.
  3. Use the key on every data request: X-Api-Key: <key>. GET https://patentref.io/api/v1/meta/usage/ with the key (or with the bearer token instead, for the account) returns {"error": false, "plan", "key_prefix", "month", "count", "monthly_limit", "remaining", "per_minute_limit", "resets_at"}: plan is "free" for a Free key (monthly_limit 1000); an operator key has plan, monthly_limit and remaining null, which means no monthly limit. key_prefix is the first 8 characters of the key, never the key. Without a key it answers 403 {"error": true} with X-Status-Reason-Code ERR_KEY.

Free plan: 1,000 requests a month, 45 a minute (a fixed UTC clock minute). What counts toward the month: a request to a data path under /api/v1/ (outside /api/v1/meta/) that carried X-Api-Key and was answered below 500 other than 403 and 429. So 200, 400 and 404 answers count; 403, 429 and 5xx answers (the 501 of a deferred endpoint too) do not, and neither do the /api/v1/meta/ endpoints (usage, keys, health, status), the record pages /p/<patent_id> or the files at the site root. Keys minted from an account count per account, so rotating a key keeps the count. Over 45 in a minute the API answers 429 with Retry-After and the body {"detail": "Request was throttled. Expected available in N seconds."} until the minute turns. Over the month the same 429 until the first of the next month (UTC). Without a key, or with a revoked one, every data endpoint answers 403 with {"detail": "You do not have permission to perform this action."}, exactly as upstream did (the account endpoints under /meta/ add X-Status-Reason-Code ERR_KEY).

Errors

Every error keeps the upstream form: the body {"error": true} (a 403 without a key, a 429 and a detail 404 carry DRF's {"detail": "..."} instead) and, on 400, 500 and 501 (and on the 404 of a v that never existed on /lapse/status/ and the 404 of /structure/claims/, /structure/brief/ and /structure/counts/), two headers:

Every code, with what to do, is at https://patentref.io/docs/errors/ (one page each at /docs/errors/<CODE>). The problem details "code" member uses the header value when there is one, and otherwise ERR_KEY (403), THROTTLED (429) or NOT_FOUND (404).

Content negotiation (RFC 9457): send Accept: application/problem+json and any error comes back as a problem details object with Content-Type: application/problem+json and the two headers unchanged:

{"type": "https://patentref.io/docs/errors/ERR_Q", "title": "Bad Request", "status": 400, "instance": "/api/v1/patent/", "detail": "Invalid field: nope", "code": "ERR_Q", "data_version": "20261006.4"}

Without that Accept value the bodies are byte for byte what upstream returned, so clients that branch on error: true keep working.

Status codes: 200 ok; 301 a detail route without its trailing slash (the grammar page); 400 bad query (ERR_Q), or a GET request line over 4,094 bytes (an HTML page from the web server in front of the API, no code header); 401 bad bearer token (account endpoints, ERR_AUTH); 403 no key (no code header on data endpoints; problem details code ERR_KEY), or a key mint without the terms accepted (ERR_TERMS); 404 unknown detail key (problem details code NOT_FOUND); 413 a request body over 64,000 bytes (from the web server in front of the API: an empty body, no code header, with or without a key); 429 throttled (Retry-After; problem details code THROTTLED); 500 search error or timeout (ERR_ES); 501 data set not in this snapshot (ERR_NOT_IMPLEMENTED); 503 health check failing.

Good citizenship

Stay under 45 requests a minute per key; back off on 429 for the Retry-After seconds. Page with o.after and size 1000 rather than many small pages. Ask for the fields you need in f (the default is three fields). Cache by X-Data-Version. One account, one key, rotated when leaked.