Endpoints

Every patent search you can run inside Patalyze is also a request you can send. The Data API has four endpoints, all under the base URL https://data.patalyze.com. Patents and classifications each get a search endpoint (POST a JSON query) and a fetch endpoint (GET by id).

POST /patents: Search patents by boolean filters and semantic similarity.
GET /patents/{publication_number}: Fetch one patent's full stored record.
POST /classifications: Search the CPC/IPC scheme by symbol, text, or meaning.
GET /classifications/{symbol}: Fetch one classification with its ancestor hierarchy.

Every request needs a bearer token. See the Data API overview for keys, credits, and rate limits. The same four endpoints back the Global Patents MCP tools, so this page doubles as their field and operator reference.

Search patents#

Runs boolean and semantic search over the patent corpus. The JSON body is a list of filters, plus optional paging, sorting, and family de-duplication.

POST/patents

{
  "filters": [
    { "field": "Claims", "operator": "similar to", "value": "lithium-ion battery" },
    { "field": "Territory", "operator": "is any of", "value": ["US", "EP"] },
    { "field": "Priority date", "operator": "after", "value": "2018-01-01" },
    { "field": "Status", "operator": "is", "value": "In-force" }
  ],
  "sort": [{ "field": "publication_date", "order": "desc" }],
  "deduplication": "family",
  "limit": 20
}

Example code#

const res = await fetch("https://data.patalyze.com/patents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PATALYZE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    filters: [
      { field: "Claims", operator: "similar to", value: "lithium-ion battery" },
      { field: "Territory", operator: "is any of", value: ["US", "EP"] },
      { field: "Priority date", operator: "after", value: "2018-01-01" },
      { field: "Status", operator: "is", value: "In-force" },
    ],
    sort: [{ field: "publication_date", order: "desc" }],
    deduplication: "family",
    limit: 20,
  }),
});

const data = await res.json();
console.log(data.total);

import os import requests res = requests.post( "https://data.patalyze.com/patents", headers={"Authorization": f"Bearer {os.environ['PATALYZE_API_KEY']}"}, json={ "filters": [ {"field": "Claims", "operator": "similar to", "value": "lithium-ion battery"}, {"field": "Territory", "operator": "is any of", "value": ["US", "EP"]}, {"field": "Priority date", "operator": "after", "value": "2018-01-01"}, {"field": "Status", "operator": "is", "value": "In-force"}, ], "sort": [{"field": "publication_date", "order": "desc"}], "deduplication": "family", "limit": 20, }, ) data = res.json() print(data["total"])

use serde_json::json; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let api_key = std::env::var("PATALYZE_API_KEY")?; let res = reqwest::Client::new() .post("https://data.patalyze.com/patents") .bearer_auth(api_key) .json(&json!({ "filters": [ { "field": "Claims", "operator": "similar to", "value": "lithium-ion battery" }, { "field": "Territory", "operator": "is any of", "value": ["US", "EP"] }, { "field": "Priority date", "operator": "after", "value": "2018-01-01" }, { "field": "Status", "operator": "is", "value": "In-force" } ], "sort": [{ "field": "publication_date", "order": "desc" }], "deduplication": "family", "limit": 20 })) .send() .await?; let data: serde_json::Value = res.json().await?; println!("{}", data["total"]); Ok(()) }

Example response#

Results come back as an array of patents with the total match count and the paging window you requested.

{
  "results": [
    {
      "publication_number": "US11735790B2",
      "country": "US",
      "kind": "B2",
      "publication_date": "2023-08-22",
      "status": "In-force",
      "title": "Solid-state electrolyte for lithium batteries",
      "abstract": "A solid-state electrolyte for lithium-metal cells that suppresses dendrite growth.",
      "assignees": ["SolidPower Inc."],
      "inventors": ["Jane Doe"],
      "cpc": ["H01M10/0562", "H01M10/052"],
      "earliest_priority_date": "2022-01-15",
      "family": [
        { "publication_number": "EP4123456A1", "country": "EP", "kind": "A1", "status": "Filed" }
      ]
    }
  ],
  "total": 1542,
  "offset": 0,
  "limit": 20
}

Body parameters#

filtersFilter[]required

The filters to apply. An empty array matches the whole corpus (subject to the territory default below).

limitnumber

Results per page, 1 to 100. Defaults to 10.

offsetnumber

Number of results to skip, 0 to 10000. Defaults to 0.

sort{ field, order }[]

Sort order, for example publication_date with desc. Omit to sort by relevance.

deduplicationstring

Set to family to return one representative result per patent family. Omit to return every publication.

Filter object#

combination"And" | "Or"

How this filter joins the others. Optional; defaults to And. See Combining filters below.

fieldstringrequired

One of Text, Claims, Territory, Classifications, Assignees, Inventors, Priority date, Status, Number, or Kind code.

operatorstringrequired

The comparison to apply. Valid operators depend on the field, see below. Operator strings must match exactly.

valuestring | string[] | number[]

The value(s) to compare against. Single-value operators (is, after, before, contains, ...) take a bare string; multi-value operators (is any of, contains all of, ...) take an array. Use YYYY-MM-DD for dates; for between pass two dates [from, to].

Filter fields and operators#

Operator spelling is exact and matches the field

Text takes contains and does not contain, while Claims and Classifications take contain and do not contain. Sending contains to Claims returns 400 with a message listing the operators that field accepts.

Texttitle + abstract

contains, does not contain, contains any of, contains all of, does not contain any of, does not contain all of, similar to.

Claimsclaim text

contain, do not contain, contain any of, contain all of, do not contain any of, do not contain all of, similar to.

ClassificationsCPC/IPC codes

contain, do not contain, contain any of, contain all of, do not contain any of, do not contain all of. Codes match by prefix, so H01M10 matches its sub-groups.

Assigneesowner names

contain, do not contain, contain any of, do not contain any of.

Inventorsinventor names

contain, do not contain, contain any of, do not contain any of.

Territorycountry codes

is, is not, is any of, is not any of. Values are two-letter codes such as US or EP.

Priority dateYYYY-MM-DD

before, after, between. Compares the earliest priority date.

Statuslegal status

is, is not, is any of, is not any of. Accepts the groups In-force (also In-force - Challenged), Pending (Filed, Examination, Intention to grant, and Intention to reject), and Dead (Withdrawn, Abandoned, Rejected, Expired, Lapsed, and Revoked), which expand to their underlying statuses. You can also pass a specific status directly, such as Filed or Lapsed, to match only that status.

Numberpublication / application

is, is not, is any of, is not any of. Digit-only terms match application numbers; terms with letters match publication numbers.

Kind codeA1, B2, ...

is, is not, is any of, is not any of.

Text and claim searches take a trailing * wildcard: electrolyte* also matches electrolytes. Classification codes already match by prefix, so they need no wildcard.

Combining filters#

Each filter's combination controls how it joins the others. It defaults to And, so you only set it to broaden a query with Or.

And makes a positive filter required: every result must match it.
Or makes a positive filter optional: a result that matches any Or filter is included.
A negative operator (such as does not contain or is not) always excludes its matches, regardless of combination.

Territory defaults to US and EP

If you do not include a Territory filter, results are limited to US and EP publications. Add a Territory filter to widen or change the jurisdictions.

Semantic search#

Use the similar to operator on Text or Claims to rank results by meaning rather than exact keywords. Pass a short description as the value:

{ "field": "Claims", "operator": "similar to", "value": "lithium-ion battery" }

The first similar to filter drives the ranking; the rest narrow the candidate set. Mix it freely with the boolean filters above.

Response fields#

To fetch the complete stored record for a single patent, see Fetch patent.

Fetch patent#

Returns the complete stored record for one patent, including claims, description, legal events, and family members. This is the full document behind the trimmed records returned by search.

GET/patents/US11735790B2

publication_number

Example code#

const res = await fetch(
  "https://data.patalyze.com/patents/US11735790B2",
  { headers: { Authorization: `Bearer ${process.env.PATALYZE_API_KEY}` } },
);
const patent = await res.json();
console.log(patent.title);

Example response#

The example below is abridged. A live response also carries the claims and the other fields described in the tables that follow. An unknown publication number returns 404 Not Found.

{
  "publication_number": "US11735790B2",
  "country": "US",
  "kind": "B2",
  "status": "In-force",
  "publication_date": "2023-08-22",
  "title": "Solid-state electrolyte for lithium batteries",
  "abstract": "A solid-state electrolyte composition for lithium-ion cells ...",
  "assignees": ["SolidPower Inc."],
  "inventors": ["Jane Doe"],
  "cpc": ["H01M10/0562", "H01M10/052"],
  "earliest_priority_date": "2022-01-15",
  "family": [
    { "publication_number": "EP4123456A1", "country": "EP", "kind": "A1", "status": "Filed" }
  ]
}

Response fields#

publication_numberstring

The publication number, for example US11735790B2.

countrystring

Two-letter publication country code.

kindstring

Kind code, for example B2.

statusstring

Current legal status.

publication_dateYYYY-MM-DD

Date the publication was issued.

titlestring

Patent title.

abstractstring

Abstract text.

assigneesstring[]

Current owners.

inventorsstring[]

Named inventors.

cpcstring[]

CPC classification symbols; IPC codes are included the same way in ipc.

earliest_priority_dateYYYY-MM-DD

Earliest priority date across the family.

claimsobject[]

One entry per claim, each with number and text. Dependent claims also carry depends_on, the claim numbers they build on; independent claims omit it. Parsed element phrases appear in elements once available.

familyobject[]

Family members, each with publication_number, country, kind, and status.

The full stored record also carries application_number, application_date, grant_date, applicants, priorities, citations, language, and legal_events.

Search classifications#

Searches the CPC/IPC scheme. One mode picks how the query is matched: by exact symbol, by text, or by meaning.

POST/classifications

{
  "mode": "text",
  "query": "solid electrolyte",
  "limit": 10
}

Example code#

const res = await fetch("https://data.patalyze.com/classifications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PATALYZE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ mode: "text", query: "solid electrolyte", limit: 10 }),
});

const data = await res.json();
console.log(data.total);

Example response#

The response mirrors patent search: a results array of classifications plus total, offset, and limit.

{
  "results": [
    {
      "symbol": "H01M10/0562",
      "title": "Solid materials for use as electrolytes",
      "depth": 0,
      "score": 0.91
    }
  ],
  "total": 12,
  "offset": 0,
  "limit": 10
}

Body parameters#

Response fields#

resultsClassification[]

The page of matching classifications. Each has a symbol, title, and depth, with optional parent, notes, statement, glossary, and synonyms. Each result also carries a score: 1.0 for an exact symbol lookup, and a ranking score for text and embedding search.

totalnumber

Total number of matches.

offsetnumber

The offset that produced this page.

limitnumber

The page size that produced this page.

Fetch classification#

Returns the full record for a single classification, such as H01M10, including its ancestor hierarchy up to the top-level section.

GET/classifications/H01M10

symbol

Example code#

const res = await fetch(
  "https://data.patalyze.com/classifications/H01M10",
  { headers: { Authorization: `Bearer ${process.env.PATALYZE_API_KEY}` } },
);
const classification = await res.json();
console.log(classification);

Example response#

The response is the classification record, with a parents array listing its ancestors from the top-level section down to the immediate parent. An unknown symbol returns 404 Not Found.

{
  "symbol": "H01M10",
  "title": "Secondary cells; Manufacture thereof",
  "depth": 1,
  "parent": "H01M",
  "parents": [
    { "symbol": "H", "title": "Electricity", "depth": 4 },
    { "symbol": "H01", "title": "Basic electric elements", "depth": 3 },
    { "symbol": "H01M", "title": "Processes or means for the direct conversion of chemical energy into electrical energy", "depth": 2 }
  ],
  "notes": "",
  "statement": "",
  "glossary": "",
  "synonyms": "",
  "definition": null,
  "images": []
}

Response fields#

symbolstring

The classification code, for example H01M10.

titlestring

Human-readable title.

depthnumber

How deep in the hierarchy: 4 = section, 3 = class, 2 = subclass, 1 = group, 0 = subgroup. A higher number is broader.

parentstring | null

The immediate parent symbol. null for a top-level section.

parentsobject[]

The ancestor chain from the top-level section down to the immediate parent, each with symbol, title, and depth.

notesstring

Explanatory notes. Empty when not set.

statementstring

Scope statement. Empty when not set.

glossarystring

Glossary of terms. Empty when not set.

synonymsstring

Synonyms. Empty when not set.

definitionstring | null

The full CPC definition text. null when the classification has none.

imagesstring[]

Image references from the definition. Empty when there are none.