# PatentRef > PatentRef is a hosted, PatentsView-compatible US patent data API. It answers the PatentSearch v1 grammar (same endpoint paths, same q/f/s/o parameters, same response shape, same error codes as the USPTO PatentSearch API that PatentsView paused on 2026-03-20) from PatentRef's own snapshot of USPTO PatentsView bulk data. Existing PatentsView clients work by changing the base URL and adding a key: the base URL becomes https://patentref.io, and every data request sends a PatentRef key in the X-Api-Key header (a PatentsView key does not work here). Version 1.21.0 (info.version in the OpenAPI file); what changed, newest first: https://patentref.io/changes.txt. Base URL: https://patentref.io/api/v1/ (always HTTPS). Every data request needs an API key in the header X-Api-Key; the build facts (/api/v1/meta/), health, status, the home page (/), the docs (/docs/), the error index (/docs/errors/), the demo (/try/) and these files need none. A Free key allows 1,000 requests a month and 45 a minute; a keyed request to a data path counts when it is answered below 500 other than 403 and 429 (so 400 and 404 count; /api/v1/meta/, the record pages and these files never count). Get one at https://patentref.io/api/v1/meta/signup/ (email sign-up, then POST /api/v1/meta/keys/ with the Supabase access token and {"terms_version": "beta-2"} once the terms at https://patentref.io/docs/legal/terms are read and accepted; the key is shown once). Every response carries the header X-Data-Version, one value per data build. Nothing PatentRef returns is a legal conclusion: expiry and maintenance-fee status come as record facts with their basis and an as-of date, from the lapse group of /api/v1/patent/ and from /api/v1/lapse/status// (below). ## Start here - [Docs](https://patentref.io/docs/): the same facts as pages for a person: a quick start, the grammar, one page per endpoint with its fields and an example, the Lapse fields, the claim trees, the claim counts, the known differences from upstream, moving from PatentsView, and the contract examples. - [Try it](https://patentref.io/try/): four fixed requests (one patent by its number, an assignee's grants in one year, a patent's claims, its expiry and fee status), each shown as curl and answered without a key, for a person in a browser: 20 runs an hour from one address, and nothing but these four. - [Full guide for agents](https://patentref.io/llms-full.txt): the grammar, every endpoint, errors, paging, limits and worked examples in one file. - [OpenAPI 3.1](https://patentref.io/openapi.json): generated from the upstream endpoint contract plus PatentRef's own paths; every path, parameter, response schema and error form. q, f, s and o are JSON parameters with schemas (the Query grammar, each endpoint's field names and sortable fields, the Options object), and every record field names its search kind (x-patentref-kind; links take the kind of the id behind them, and the lapse group's fields are f-only). - [Changes](https://patentref.io/changes.txt): what changed in answers and documents, by version, with the rule for the version number. - [Build facts](https://patentref.io/api/v1/meta/): data_version, as-of date, when the build went into service, the table delta of the build, the data sets it lacks (deferred), attribution. - [Status](https://patentref.io/api/v1/meta/status/): uptime, request and latency figures, refresh state; JSON twin at status.json. - [Free key](https://patentref.io/api/v1/meta/signup/): sign up and mint a key; GET /api/v1/meta/usage/ with the key shows this month's count. - [Snapshot](https://patentref.io/docs/snapshot.html): the data behind the API as three SQLite files on public object storage, with a Zenodo DOI (10.5281/zenodo.23250455, which resolves to the newest version), the SHA-256 of each file and how to check them. - [Error codes](https://patentref.io/docs/errors/): every X-Status-Reason-Code and problem details code (ERR_Q, ERR_KEY, ERR_ES, ERR_NOT_IMPLEMENTED, ERR_AUTH, ERR_SIGNUP_LIMIT, ERR_TERMS, THROTTLED, NOT_FOUND) with what to do. ## Quick facts - Query: GET /api/v1/patent/?q={"patent_id":"10905426"} with X-Api-Key. q is one JSON object with exactly one top-level key; a plain key means equality; operators are _eq, _neq, _gt, _gte, _lt, _lte, _begins, _contains, _text_all, _text_any, _text_phrase, _and, _or, _not. f picks fields, s sorts, o pages (size up to 1000, after as the cursor; offset is rejected). _text_phrase matches the words in order on tokens: case and punctuation such as hyphens are ignored, with no stemming. Raw JSON in a GET query string works as written above, except that a space must be %20, a + is read as a space, and &, # and % must be percent-encoded; percent-encoding every value always works. A GET request line may be 4,094 bytes and a POST body 64,000 bytes (413 above that); list routes answer with or without the trailing slash, a detail route without it answers 301. A number field takes "2021" as 2021. Inventor, assignee and location country codes are ISO two-letter codes in capitals (GB, not UK). /api/v1/patent/otherreference/, upstream's path before its release 2.2.0, answers as /api/v1/patent/other_reference/ does. - Response: {"error": false, "count": n, "total_hits": N, "": [...]}. total_hits is exact. - Errors: the upstream body {"error": true} with the headers X-Status-Reason and X-Status-Reason-Code. Send Accept: application/problem+json to receive the same facts as an RFC 9457 problem details object. - Expiry and maintenance fees (PatentRef additions, keyed): add "lapse" to f on /api/v1/patent/ for expiry_status, expiry_date_estimated, expiry_basis, reinstatement_possible, fee_status, lapse_date, reinstated_date, as_of and more (f only, not in q or s); GET /api/v1/lapse/status// returns one verdict record (status, basis, reinstatement_possible with its basis: 37 CFR 1.378 for a fee lapse, 35 USC 154 when the term has ended; as_of, data_version, a permalink, one plain sentence that gives the term end as computed from the record's dates, next_steps); GET /api/v1/lapse/similar?text=...&n=20 returns the nearest patents by title and abstract. - Claim trees (PatentRef addition, keyed): GET /api/v1/structure/claims// returns the patent's claims as the long-text file prints them, each with its number, category (read from the preamble's words), dependency and its basis, preamble, transition, elements, term mentions (each "the" or "said" phrase with the earlier mention it was matched to) and claim citations, every part with start and end offsets into the claim text (text[start:end] is the part), plus flags that note what the parser saw in the text and the data; built on request by a deterministic parser (no language model), with structure_version, data_version and text_data_version; 404 NOT_FOUND for a patent not in the data or without claim text. Page: https://patentref.io/docs/structure.html. - Patent briefs (PatentRef addition, keyed): GET /api/v1/structure/brief//?max_tokens=2000 returns one patent in a fixed order, cut to fit max_tokens (300 to 32000, default 2000) with tokens counted by a stated proxy (the answer's UTF-8 bytes divided by 3, rounded up) and never over the budget: its identity and dates, its status record with its basis, each independent claim as its elements with start and end offsets into the claim text, each dependent claim on one line, and the claim term keys; truncated and omitted say what the budget left out. Every claim and element carries its anchor on the record page (https://patentref.io/p/#, the same for the same data). Built on request from the claim tree (no language model). Page: https://patentref.io/docs/structure.html#brief. - Claim counts (PatentRef addition, keyed): GET /api/v1/structure/counts// returns counts in the spirit of the USPTO Patent Claims Research Dataset (which stops at 2014) for any grant the long-text file holds: claims, independent and dependent claims, claims whose text names another claim (the USPTO dataset's rule for a dependent claim), words (in all, of the first claim, and the least, mean and most of the independent and of the dependent claims), characters, elements of the independent claims, the longest chain of dependencies, the USPTO dataset's "consisting", "or" and "selected from" counts, and the same per claim; counted on request from the claim tree (no language model, nothing stored), with counts_version, structure_version, data_version and text_data_version. Each field names the USPTO variable it follows; on 1,000 random grants of 1976 to 2014 the claims of a patent agreed with the USPTO files for 99.8 percent of patents. Page: https://patentref.io/docs/claim-counts.html. - Nearest patents by claim terms (PatentRef addition, keyed, experimental): GET /api/v1/lapse/similar?text=...&n=20&mode=structured ranks patents by the share of the text's term keys (the noun phrases the claim tree's parser reads in it, weighed by rarity) that their claims introduce, each neighbor with score (0 to 1) and shared_terms (the key, exact or partial, the claim's number and the mention's start and end in that claim's text); candidates come from the title and abstract index, the claims are parsed on request by the same deterministic parser (no language model, nothing stored). Experimental: the ranking is weakest where the shared terms are common short claim words, where near-identical patents tie, and where a text yields fewer than 3 term keys, as many chemistry abstracts do. Without mode, or with mode=text, the answer is the title and abstract one, unchanged. Page: https://patentref.io/docs/lapse.html. - Triage table (PatentRef addition, keyed): POST /api/v1/structure/triage/ with {"patents": [up to 500 numbers, or pasted text]} or {"search": "words that must all be in one claim", "limit": 1 to 500}, plus "components" (up to 12; without them the table picks up to 6 terms its patents share), returns one row per patent: its expiry and fee status, basis and reinstatement_possible (the values of /api/v1/lapse/status//), for each component its position in the claims (every_independent, some_independent, only_dependent or absent) with the first mention, the terms its own claims introduce by position, and each independent claim as a list of its parts; every quote with claim, claim_id, start and end in the claim text; output=csv gives the export. Built on request by the claim tree's deterministic parser (no language model, nothing stored); one table at a time per key; a table stops after 20 s and then says complete false. The page https://patentref.io/triage/ draws it and keeps have and lacks marks in the browser only (an example without a key: https://patentref.io/triage/example/). Docs: https://patentref.io/docs/structure.html#triage. - Rules (PatentRef additions, keyed): GET /api/v1/rules/ lists the offices (US, EP, CN, JP, KR, AU, PCT), the tools and the act vocabulary; /api/v1/rules/rep_required/, /fee_schedule/ (as_of=YYYY-MM-DD), /route_windows/, /pph_routes/ (from_office, to_office), /ai_use_statement_required/, /grace_period/ and /changelog/ answer rows, each with its official source URL and a verbatim quote, plus rules_version and as_of. They take an office, never an application number or a priority date, and compute no date for an application. - Assignee names as printed (PatentRef additions): assignee_organization and the assignee's individual names are PatentsView's disambiguated names, one label for a whole cluster of spellings, which can differ from the grant (US 6859933 is printed "Samsung Electronics, Co., Ltd."; its cluster label is "SAMSUNG DISPLAY CO., LTD."). Name assignees.raw_assignee_organization (and assignees.raw_assignee_individual_name_first, assignees.raw_assignee_individual_name_last) in f on /api/v1/patent/, or raw_assignee_organization on /api/v1/assignee/, for the names as printed, beside the disambiguated ones (f only, not in q or s; null in a data version built before them). - Long text: /api/v1/g_claim/, /g_brf_sum_text/, /g_detail_desc_text/ and /g_draw_desc_text/ serve the claims, brief summaries and drawing descriptions of patents granted 1976 to 2025-12-30 and the detailed descriptions of those granted 2005 to 2025-12-30 (long-text build 20261006.4; patents granted after 2025-12-30 have no long text yet); search them with _text_all, _text_any or _text_phrase. Their answers carry X-Text-Data-Version, the version of the long-text file (cache long text under it). - Not served: pre-grant publication endpoints (deferred) and the dead NBER routes answer 501 (X-Status-Reason-Code ERR_NOT_IMPLEMENTED), as does any endpoint whose data set the build in service does not carry (today /cpc_class/, /cpc_subclass/, /uspc_mainclass/ and /wipo/; the same classifications come with each patent in its cpc_current, cpc_at_issue, uspc_at_issue and wipo groups). GET /api/v1/meta/ lists them under deferred. - Data: PatentsView and USPTO bulk data under CC BY 4.0; granted patents 1976 to the current release; refreshed weekly from USPTO releases. License register: https://patentref.io/LICENSES.md. ## Optional - [Original PatentSearch API documentation](https://search.patentsview.org/docs/): the upstream grammar PatentRef reproduces; the base URL there no longer answers. - [Source of the API server](https://github.com/PatentsView/PatentSearch-API): the USPTO's GPL-3.0 code PatentRef forked and pointed at SQLite. - [PatentRef's fork and its change list](https://github.com/Nietzsche247/PatentSearch-API/blob/sqlite-backend/CHANGES_LAPSE.md): every difference from upstream, with its reason.