Developer documentation

Patent Intelligence API v1.3

Search patents by technical query, title, parties, classification, or date range. Choose the fields your application receives, paginate structured results, or run AI novelty analysis. Indian patents by default, with worldwide publications where enabled. Four REST endpoints and an MCP server share the same API keys and quotas.

Product overview OpenAPI 3.1 spec Request API access

Base URL

https://patentnest.ai

Authentication

All requests authenticate with a bearer token in the Authorization header. API keys use the pn_live_ prefix and are provisioned per client. Do not embed keys in browser or mobile client code — this is a server-to-server API.

Header

Authorization: Bearer pn_live_your_key

A missing, invalid, revoked, or expired key returns 401 with error code INVALID_API_KEY or API_KEY_REVOKED. A suspended client returns 403 with CLIENT_SUSPENDED.

POST

/api/v1/patents/search

Search with a technical query, structured filters, or both. Indian patents are searched by default; add jurisdictions to search other patent offices (see Worldwide coverage). Use hybrid for a ranked semantic and text shortlist, or structuredfor individual publications with pagination and date/title sorting. Every response includes a coverage manifest. Existing query-only requests keep their hybrid behavior.

Request body

Field	Type	Required	Description
query	string	Or filters	Plain-English search query, 2–2,000 characters. Optional when filters are supplied.
limit	integer	No	Maximum results, 1–50. Default: 20.
jurisdictions	string[]	No	Patent offices to search: 1–20 two-letter codes such as `US`, `EP`, `WO`, `CN`, `IN`, or `["*"]` for every office. Default: `["IN"]`.
mode	string	No	hybrid (default with query) or structured (default without query). Structured returns individual publications and supports pagination and sorting without embeddings.
filters	object	No	title, abstract, publicationNumber, applicationNumber; applicants, inventors and classifications arrays; filingDateFrom/To, publicationDateFrom/To, grantDateFrom/To.
fields	string[]	No	Choose top-level response fields from the patent record schema below. Omit for all fields. publicationNumber and source are always returned.
offset	integer	No	Structured mode only: 0–10,000, default 0. Continue with pagination.nextOffset; results can change as the corpus is updated.
sort	string	No	Hybrid: relevance. Structured: publicationDateDesc (default), filingDateDesc, grantDateDesc or titleAsc. Missing dates sort last; publicationNumber breaks ties.

Supply query or at least one filter. When mode is omitted, a query selects hybrid search; filters without a query select structured search. Set mode: "structured" explicitly when sending a query with pagination.

Hybrid search request

curl -X POST "https://patentnest.ai/api/v1/patents/search" \
  -H "Authorization: Bearer pn_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "battery thermal management for electric vehicles",
    "limit": 10
  }'

Example response (abbreviated)

{
  "data": {
    "query": "battery thermal management for electric vehicles",
    "count": 10,
    "results": [
      {
        "publicationNumber": "IN202211045678A",
        "applicationNumber": "202211045678",
        "kind": "A",
        "country": "IN",
        "title": "THERMAL MANAGEMENT SYSTEM FOR ELECTRIC VEHICLE BATTERY PACK",
        "abstract": "A battery thermal management system comprising...",
        "applicants": [
          { "name": "XYZ Technologies Pvt Ltd", "address": "Bengaluru, India", "sequence": 1 }
        ],
        "inventors": ["Rajesh Kumar", "Priya Sharma"],
        "classifications": ["H01M10/613", "H01M10/6568"],
        "filingDate": "2022-08-15",
        "publicationDate": "2023-02-17",
        "grantDate": null,
        "numberOfPages": 24,
        "numberOfClaims": 12,
        "extractionConfidence": 0.95,
        "source": {
          "name": "IP India Patent Journal",
          "document": "patent_journal_07_2023.pdf",
          "page": 142,
          "license": null,
          "attribution": null
        },
        "relevance": {
          "score": 0.87,
          "semanticScore": 0.91,
          "textScore": 0.72,
          "matchedFields": ["title", "abstract"],
          "matchedViaFamilyMember": null
        }
      }
    ],
    "coverage": {
      "corpus": "indian-patent-journal",
      "description": "Indian patent corpus sourced from IP India Patent Journal publications.",
      "jurisdiction": "IN",
      "jurisdictions": ["IN"],
      "documents": 163420,
      "semanticCoveragePercent": 99.4,
      "searchMode": "hybrid-semantic-text",
      "embeddingModel": "text-embedding-3-small"
    }
  },
  "meta": { "requestId": "a1b2c3d4-e5f6-7890", "durationMs": 1240 }
}

The coverage object appears in every search response. It tells you exactly what was searched — corpus, jurisdiction, document count, semantic coverage percentage, and the embedding model. When coverage changes, your integration sees it without polling.

Filters and date ranges

Put search criteria inside filters. All supplied filters combine with AND; values within an array combine with OR. The same filters work in hybrid and structured mode. Text values must contain 1–300 characters after trimming; arrays accept 1–20 values.

Filter	Type	Matches
title	string	Case-insensitive literal substring of the patent title.
abstract	string	Case-insensitive literal substring of the abstract.
publicationNumber	string	Part or all of a publication identifier; case and separators are ignored.
applicationNumber	string	Part or all of an application identifier; case and separators are ignored.
applicants	string[]	Any supplied name as a case-insensitive substring of an applicant name.
inventors	string[]	Any supplied name as a case-insensitive substring of an inventor name.
classifications	string[]	Any IPC/CPC prefix, such as H01M. Spaces and separators are ignored.
filingDateFrom / filingDateTo	YYYY-MM-DD	Inclusive start and end of the filing-date range. Either bound can be omitted.
publicationDateFrom / publicationDateTo	YYYY-MM-DD	Inclusive start and end of the publication-date range. Either bound can be omitted.
grantDateFrom / grantDateTo	YYYY-MM-DD	Inclusive range for explicitly recorded IP India grant dates. Missing grant dates do not match.

Filter by title and filing dates; choose returned fields

curl -X POST "https://patentnest.ai/api/v1/patents/search" \
  -H "Authorization: Bearer pn_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "structured",
    "filters": {
      "title": "battery",
      "filingDateFrom": "2020-01-01",
      "filingDateTo": "2025-12-31",
      "classifications": ["H01M"]
    },
    "fields": ["title", "filingDate", "publicationDate", "grantDate", "applicants"],
    "sort": "filingDateDesc",
    "limit": 25,
    "offset": 0
  }'

Use identical From and To dates for an exact date. Dates must be real calendar dates; the From date must be on or before the To date. Missing dates do not match a range. Unknown filters, empty searches, and invalid or reversed dates return 400 INVALID_REQUEST. Text filters treat % and _ as literal characters.

The grant date, sometimes called the sanction date, is grantDate. It is returned only when explicitly recorded in stored IP India metadata; otherwise it is null. Publication dates and grant kind codes do not supply a grant date. Grant-date filters therefore cover only records with that information.

Search by recorded grant date

{
  "mode": "structured",
  "filters": {
    "title": "battery",
    "grantDateFrom": "2024-01-01",
    "grantDateTo": "2024-12-31"
  },
  "fields": ["title", "filingDate", "grantDate"],
  "sort": "grantDateDesc",
  "limit": 25
}

Choose response fields

Omit fields to receive the full public record. To request specific fields, send a nonempty array of top-level names from the patent record reference. For example, ["title", "filingDate", "grantDate"] returns those values alongside publicationNumber and source, which are always included for identity and attribution.

Selected search result (illustrative)

{
  "publicationNumber": "IN202211045678A",
  "title": "THERMAL MANAGEMENT SYSTEM FOR ELECTRIC VEHICLE BATTERY PACK",
  "filingDate": "2022-08-15",
  "grantDate": null,
  "source": {
    "name": "IP India Patent Journal",
    "document": "patent_journal_07_2023.pdf",
    "page": 142,
    "license": null,
    "attribution": null
  }
}

Select whole objects with source or relevance; names such as source.name are not accepted as field selectors. Relevance is available only for hybrid search results. Unknown field names return 400 INVALID_REQUEST. Field selection changes the patent records, while search coverage, pagination and response metadata retain their normal shape.

Selected fields on a direct lookup

curl "https://patentnest.ai/api/v1/patents/IN202211045678A?fields=title,filingDate,grantDate" \
  -H "Authorization: Bearer pn_live_your_key"

Pagination and sorting

Set mode: "structured" to retrieve individual publications without family deduplication or an embedding service. An optional query matches a literal substring in title or abstract. limit accepts 1–50 records per page (default 20); offset accepts 0–10,000 (default 0).

Structured sorting accepts publicationDateDesc (default), filingDateDesc, grantDateDesc, or titleAsc. Missing dates sort last, with publication number breaking ties. Hybrid search returns a ranked shortlist with sort: "relevance" and offset: 0; it has no pagination object.

Structured response pagination (abbreviated)

{
  "data": {
    "query": "",
    "mode": "structured",
    "count": 25,
    "results": [
      {
        "publicationNumber": "IN202211045678A",
        "title": "THERMAL MANAGEMENT SYSTEM FOR ELECTRIC VEHICLE BATTERY PACK",
        "filingDate": "2022-08-15",
        "publicationDate": "2023-02-17",
        "grantDate": null,
        "applicants": [{ "name": "XYZ Technologies Pvt Ltd", "address": "Bengaluru, India", "sequence": 1 }],
        "source": {
          "name": "IP India Patent Journal",
          "document": "patent_journal_07_2023.pdf",
          "page": 142,
          "license": null,
          "attribution": null
        }
      }
    ],
    "coverage": {
      "corpus": "indian-patent-journal",
      "jurisdictions": ["IN"],
      "searchMode": "structured",
      "embeddingModel": null
    },
    "pagination": {
      "offset": 0,
      "limit": 25,
      "hasMore": true,
      "nextOffset": 25
    }
  },
  "meta": { "requestId": "a1b2c3d4-e5f6-7890", "durationMs": 120 }
}

For the next request, keep the same filters, fields, limit and sort, and set offset to pagination.nextOffset. Stop when it is null: either the results have ended or the 10,000 offset cap has been reached. hasMore can still be true at that cap; narrow the filters to retrieve a smaller result set. count is the number on this page, not a total match count. New imports can shift results between pages.

A broad structured search that exceeds the time budget returns 503 PATENT_SEARCH_UNAVAILABLE. Narrow the filters before retrying. Grant-date filters and sorting depend on recorded metadata, so combining them with a title, classification, or filing-date constraint can help keep the search selective.

Worldwide coverage

Send jurisdictions to search beyond India. Worldwide records come from Google Patents Public Data and cover publications from 2000 onward across the major offices, including US, EP, WO, CN, JP, and KR. Any request that includes IN (or *) also searches the IP India journal corpus, so the newest Indian publications are never missed.

Example request

curl -X POST "https://patentnest.ai/api/v1/patents/search" \
  -H "Authorization: Bearer pn_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "battery thermal management for electric vehicles",
    "limit": 10,
    "jurisdictions": ["CN", "EP"]
  }'

Example response (abbreviated)

{
  "data": {
    "query": "battery thermal management for electric vehicles",
    "count": 10,
    "results": [
      {
        "publicationNumber": "CN-114123456-B",
        "kind": "B",
        "country": "CN",
        "familyId": "71234567",
        "title": "Thermal management system for a power battery pack",
        "abstract": "The invention discloses a liquid-cooling plate arrangement...",
        "publicationDate": "2023-06-02",
        "source": {
          "name": "Google Patents Public Data",
          "document": null,
          "page": null,
          "license": "CC-BY-4.0",
          "attribution": "Contains data from Google Patents Public Data by IFI CLAIMS Patent Services and Google, used under CC BY 4.0."
        },
        "relevance": {
          "score": 0.84,
          "semanticScore": 0.88,
          "textScore": null,
          "matchedFields": ["semantic"],
          "matchedViaFamilyMember": "US-11234567-B2"
        }
      }
    ],
    "coverage": {
      "corpus": "worldwide",
      "jurisdiction": null,
      "jurisdictions": ["CN", "EP"],
      "searchMode": "hybrid-semantic-text",
      "sources": [
        {
          "corpus": "google-patents-public-data",
          "jurisdiction": "*",
          "semanticUnit": "patent-family",
          "license": "CC-BY-4.0",
          "attribution": "Contains data from Google Patents Public Data by IFI CLAIMS Patent Services and Google, used under CC BY 4.0."
        }
      ],
      "limitations": ["Worldwide records cover publications from 2000 onward..."]
    }
  },
  "meta": { "requestId": "e5f6a7b8-c9d0-1234", "durationMs": 4210 }
}

Hybrid search groups worldwide results by patent family. You get one record per family, from an office you asked for. When the match was made on a family member from another office, relevance.matchedViaFamilyMember names that publication. Structured search returns individual publications without family deduplication.

What worldwide records contain. Outside the United States, records carry the title and an English abstract (machine-translated where the original is not English). Claims are available for US publications only, so feature mapping against other offices works from the title and abstract. Worldwide data refreshes quarterly, so the newest publications can lag by up to three months.

Attribution. Worldwide records are licensed CC BY 4.0. When you display or redistribute them, reproduce the record's source.attribution text.

If worldwide coverage is not enabled for the API, requests for other jurisdictions return 403 with JURISDICTION_NOT_AVAILABLE.

GET

/api/v1/patents/{'{publicationNumber}'}

Fetch a single patent record by publication number. Case and separators are normalized automatically — IN/2028/2005/A, in20282005a, and IN-2028-2005-A all resolve to the same document. A number without a kind code, such as US10123456, resolves to its granted publication when there is one. Worldwide publication numbers resolve where worldwide coverage is enabled.

Select lookup fields with ?fields=title,filingDate,grantDate. Identity (publicationNumber) and source attribution remain included. MCPget_patent accepts the same selection as a fields array.

Example request

curl "https://patentnest.ai/api/v1/patents/IN202211045678A" \
  -H "Authorization: Bearer pn_live_your_key"

Example response (abbreviated)

{
  "data": {
    "publicationNumber": "IN202211045678A",
    "applicationNumber": "202211045678",
    "kind": "A",
    "country": "IN",
    "title": "THERMAL MANAGEMENT SYSTEM FOR ELECTRIC VEHICLE BATTERY PACK",
    "abstract": "A battery thermal management system comprising...",
    "applicants": [
      { "name": "XYZ Technologies Pvt Ltd", "address": "Bengaluru, India", "sequence": 1 }
    ],
    "inventors": ["Rajesh Kumar", "Priya Sharma"],
    "classifications": ["H01M10/613", "H01M10/6568"],
    "filingDate": "2022-08-15",
    "publicationDate": "2023-02-17",
    "grantDate": null,
    "numberOfPages": 24,
    "numberOfClaims": 12,
    "extractionConfidence": 0.95,
    "source": {
      "name": "IP India Patent Journal",
      "document": "patent_journal_07_2023.pdf",
      "page": 142,
      "license": null,
      "attribution": null
    }
  },
  "meta": { "requestId": "b2c3d4e5-f6a7-8901", "durationMs": 48 }
}

Returns 404 with error code PATENT_NOT_FOUND if the number does not match any patent you have access to.

POST

/api/v1/analysis/features

AI analysis of a plain-English invention disclosure. Runs the same normalization stage as the PatentNest novelty pipeline and returns atomic technical features with per-feature detail, novelty-focus candidates, a search query built for patent retrieval, CPC/IPC classification hints, and confidence values.

This endpoint performs a full LLM analysis and typically responds in 10–30 seconds. Plan client timeouts accordingly. It draws on a separate daily analysis budget (see Rate limits).

Request body

Field	Type	Required	Description
title	string	No	Invention title, up to 300 characters.
description	string	Yes	Plain-English disclosure, 40–20,000 characters.

Example request

curl -X POST "https://patentnest.ai/api/v1/analysis/features" \
  -H "Authorization: Bearer pn_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Solar-powered cold-chain container",
    "description": "A shipping container with phase-change thermal storage panels charged by roof-mounted photovoltaic cells. A controller predicts door-opening events from a delivery schedule and pre-cools the buffer zone before each stop to hold the payload temperature within two degrees."
  }'

Example response (abbreviated)

{
  "data": {
    "features": [
      "phase-change thermal storage panels in a shipping container",
      "roof-mounted photovoltaic cells charging thermal storage",
      "controller that predicts door-opening events from delivery schedule",
      "pre-cooling of a buffer zone before each scheduled stop",
      "maintaining payload temperature within two-degree tolerance"
    ],
    "featureDetails": [
      {
        "feature": "phase-change thermal storage panels in a shipping container",
        "featureType": "core_technical",
        "disclosureSupport": "Directly stated: 'phase-change thermal storage panels'",
        "technicalRole": "Primary energy storage mechanism for cold-chain maintenance",
        "sourceExcerpt": "A shipping container with phase-change thermal storage panels",
        "confidence": 0.95
      }
    ],
    "noveltyFocus": [
      "controller that predicts door-opening events from delivery schedule",
      "pre-cooling of a buffer zone before each scheduled stop"
    ],
    "suggestedSearchQuery": "solar powered cold chain container phase change thermal storage photovoltaic predictive pre-cooling delivery schedule",
    "inventionTypes": ["apparatus", "system"],
    "classificationHints": {
      "cpc": ["F25D11/003", "B65D88/748", "H02S40/44"],
      "ipc": ["F25D11/00", "B65D88/74", "H02S40/44"]
    },
    "confidence": 0.88,
    "warnings": []
  },
  "meta": { "requestId": "c3d4e5f6-a7b8-9012", "durationMs": 14320 }
}

Feature types: core_technical (the technical mechanism), novelty_candidate (most likely to distinguish over prior art), implementation (how it is built), generic_weak (too broad to be distinctive). Use feature type and confidence to decide which features are worth mapping against prior art.

Suggested search query: retrieval-optimized phrasing built from the disclosure. Use it as the query parameter in the search endpoint. You can also use your own query — the suggestion is a strong starting point, not mandatory.

POST

/api/v1/analysis/feature-mapping

Element-wise novelty evidence. Each submitted feature is classified as present, partial, absent, or unknown against one patent record, with a verbatim quote and the field it came from (title, abstract, or claims).

Typical flow: extract features → search with the suggested query → map features against shortlisted publication numbers. This is the endpoint that produces the actual evidence for a novelty assessment.

Request body

Field	Type	Required	Description
features	string[]	Yes	1–12 features, each 3–300 characters.
publicationNumber	string	Yes	Publication number of the patent to map against.

Example request

curl -X POST "https://patentnest.ai/api/v1/analysis/feature-mapping" \
  -H "Authorization: Bearer pn_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "features": [
      "phase-change thermal storage panels in a shipping container",
      "roof-mounted photovoltaic cells charging thermal storage",
      "controller that predicts door-opening events from delivery schedule"
    ],
    "publicationNumber": "IN202211045678A"
  }'

Example response (abbreviated)

{
  "data": {
    "publicationNumber": "IN202211045678A",
    "title": "THERMAL MANAGEMENT SYSTEM FOR ELECTRIC VEHICLE BATTERY PACK",
    "coverage": { "present": 1, "partial": 1, "absent": 1, "unknown": 0 },
    "featureFindings": [
      {
        "feature": "phase-change thermal storage panels in a shipping container",
        "status": "present",
        "evidence": {
          "quote": "a phase-change material encapsulated within thermally conductive panels arranged along the interior walls of the container",
          "field": "claims"
        },
        "confidence": 0.92,
        "reason": "Claim 1 describes phase-change thermal storage panels within a container structure."
      },
      {
        "feature": "roof-mounted photovoltaic cells charging thermal storage",
        "status": "partial",
        "evidence": {
          "quote": "an external energy source connected to the thermal regulation circuit",
          "field": "abstract"
        },
        "confidence": 0.65,
        "reason": "The patent mentions an external energy source but does not specify photovoltaic cells or roof mounting."
      },
      {
        "feature": "controller that predicts door-opening events from delivery schedule",
        "status": "absent",
        "evidence": null,
        "confidence": 0.88,
        "reason": "No mention of predictive control, door-opening events, or delivery schedule integration."
      }
    ],
    "evidenceBasis": { "title": true, "abstract": true, "claims": true },
    "qualityFlags": {
      "lowEvidence": false,
      "ambiguousAbstracts": false,
      "languageMismatch": false
    }
  },
  "meta": { "requestId": "d4e5f6a7-b8c9-0123", "durationMs": 18540 }
}

Evidence statuses: present means the feature is disclosed with a direct, attributable quote. partial means some elements match but others are missing or differ. absent means no evidence for the feature was found. unknown means the available text is insufficient to make a determination — treat it as an absence of evidence, not evidence of absence.

Quality flags: lowEvidence fires when fewer than two text fields were available. ambiguousAbstracts flags when the abstract is too vague to support reliable mapping. languageMismatch flags when the patent text and features appear to be in different languages.

MCP server for AI agents

POST /api/v1/mcp is a Model Context Protocol endpoint (streamable HTTP transport, JSON responses) exposing the same four operations as tools: search_patents, get_patent, extract_invention_features, and map_features_to_patent. Tool calls use the same bearer API keys and count against the same quotas as REST requests.

Compatible with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client. Add this to your MCP configuration:

MCP configuration (Claude Desktop / Claude Code)

{
  "mcpServers": {
    "patentnest": {
      "type": "http",
      "url": "https://patentnest.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer pn_live_your_key"
      }
    }
  }
}

The server supports protocol versions 2025-06-18, 2025-03-26, and 2024-11-05. Sessions are stateless. tools/list returns the tool definitions with full JSON Schema input specifications.

Available tools

Tool	Description
search_patents	Hybrid or structured search with filters, selected fields, and structured pagination/sorting. Same arguments as POST /api/v1/patents/search.
get_patent	Fetch one patent by publication number; optional fields array selects returned fields. Same as GET /api/v1/patents/{publicationNumber}.
extract_invention_features	AI feature extraction from a disclosure. Same as POST /api/v1/analysis/features.
map_features_to_patent	Element-wise evidence mapping. Same as POST /api/v1/analysis/feature-mapping.

MCP filtered-search tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_patents",
    "arguments": {
      "mode": "structured",
      "filters": {
        "title": "battery",
        "filingDateFrom": "2020-01-01",
        "filingDateTo": "2025-12-31"
      },
      "fields": ["title", "filingDate", "grantDate"],
      "sort": "filingDateDesc",
      "limit": 25,
      "offset": 0
    }
  }
}

Suggested agent workflow: call extract_invention_features on a disclosure, use the suggestedSearchQuery with search_patents, then call map_features_to_patent against shortlisted publication numbers. All quotes are verbatim from the patent record; treat unknown statuses as insufficient evidence, not as proof of novelty.

Rate limits and quotas

Every response includes rate-limit headers. Exceeding any limit returns 429 with a Retry-After header (seconds).

Header	Description
RateLimit-Limit	Per-minute request limit.
RateLimit-Remaining	Requests remaining in the current minute.
RateLimit-Reset	Unix timestamp when the minute window resets.
X-RateLimit-Daily-Limit	Daily request limit.
X-RateLimit-Daily-Remaining	Requests remaining today (UTC).
X-RateLimit-Monthly-Limit	Monthly request limit.
X-RateLimit-Monthly-Remaining	Requests remaining this month (UTC).
X-RateLimit-Analysis-Limit	Daily AI analysis credit limit (analysis endpoints only).
X-RateLimit-Analysis-Remaining	Analysis credits remaining today.
X-Request-ID	Unique request identifier. Include in support requests.

The two /api/v1/analysis endpoints draw on a separate daily analysis budget. An analysis credit is charged only when a validated request reaches the model, so requests rejected with 400 or 404 never cost a credit. When the analysis budget is exhausted, these endpoints return 429 with error code ANALYSIS_QUOTA_EXCEEDED; search and lookup remain available.

Default limits are per client. Contact us if you need higher throughput — limits are configurable per client.

Error responses

All errors return a JSON body with a stable code, a human-readable message, and a requestId. Use the code for programmatic handling; the message may change between versions.

Error response format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "query must contain between 2 and 2,000 characters.",
    "requestId": "a1b2c3d4-e5f6-7890"
  }
}

HTTP	Code	Description
400	INVALID_REQUEST	Missing or invalid request parameters.
401	INVALID_API_KEY	Missing, malformed, or unrecognized API key.
401	API_KEY_REVOKED	The API key has been revoked.
401	API_KEY_EXPIRED	The API key has expired.
403	CLIENT_SUSPENDED	The API client account is suspended.
403	JURISDICTION_NOT_AVAILABLE	The requested jurisdictions are not enabled for this API.
404	PATENT_NOT_FOUND	No patent matched the publication number.
404	UNKNOWN_TOOL	MCP tool name not recognized.
413	PAYLOAD_TOO_LARGE	Request body exceeds 256 KB.
429	RATE_LIMIT_EXCEEDED	Per-minute request limit exceeded.
429	DAILY_LIMIT_EXCEEDED	Daily request limit exceeded.
429	MONTHLY_LIMIT_EXCEEDED	Monthly request limit exceeded.
429	ANALYSIS_QUOTA_EXCEEDED	Daily AI analysis credit limit exceeded.
503	SERVICE_UNAVAILABLE	The patent API is not currently enabled.
503	SEMANTIC_SEARCH_UNAVAILABLE	Vector search or embedding service is down.
503	PATENT_SEARCH_UNAVAILABLE	Structured search failed or exceeded its time budget. Retry with narrower filters.
503	CORPUS_NOT_READY	Embedding coverage below minimum threshold.
503	ANALYSIS_UNAVAILABLE	AI analysis endpoints are not enabled.
500	INTERNAL_ERROR	Unexpected server error. Include requestId in support requests.

Patent record fields

The full public record includes the fields below. Use fields to request a subset. publicationNumber and source remain included. Hybrid results additionally contain relevance; structured results and direct lookups do not. Dates and other unavailable values can be null.

Field	Type	Description
publicationNumber	string	Canonical publication number (e.g. IN202211045678A, US-10123456-B2).
applicationNumber	string \| null	Raw application number as filed.
kind	string \| null	Kind code (A, B, etc.).
country	string	Two-letter patent office code (IN, US, EP, WO, ...).
familyId	string \| null	DOCDB patent family identifier, where known.
title	string	Full patent title.
abstract	string \| null	Patent abstract text.
applicants	object[]	Array of { name, address, sequence }.
inventors	string[]	Inventor names as published.
classifications	string[]	IPC and CPC classification codes.
filingDate	string \| null	ISO 8601 date (YYYY-MM-DD), where available.
grantDate	string \| null	Explicit grant date from stored IP India metadata (YYYY-MM-DD). Null when unavailable.
publicationDate	string \| null	ISO 8601 publication date.
numberOfPages	integer \| null	Page count of the patent document.
numberOfClaims	integer \| null	Number of claims.
extractionConfidence	number \| null	Machine extraction confidence score (0–1).
source.name	string	IP India Patent Journal, or Google Patents Public Data.
source.document	string \| null	Original Journal PDF filename (IP India records).
source.page	integer \| null	Page number in the source PDF (IP India records).
source.license	string \| null	Licence of the record data (CC-BY-4.0 for worldwide records).
source.attribution	string \| null	Attribution to reproduce when displaying the record.
relevance.score	number \| null	Composite relevance score (hybrid search only).
relevance.semanticScore	number \| null	Semantic similarity score (hybrid search only).
relevance.textScore	number \| null	Text match score (hybrid search only).
relevance.matchedFields	string[]	Fields that contributed to the match (hybrid search only).
relevance.matchedViaFamilyMember	string \| null	Family member the match was made on, when not this record (hybrid search only).

Confidentiality

Submitted invention disclosures are processed to produce the API response and are not retained or used to train models. Request logs store request metadata (endpoint, status code, duration, query hashes) — never the disclosure text. Request bodies are capped at 256 KB.

API keys should be treated as secrets. Rotate keys if compromised — contact us or use the admin panel to revoke and reissue.

Quick start

Request API access — we'll provision a client and send your key.
Call POST /api/v1/analysis/features with your invention disclosure.
Use the suggestedSearchQuery to call POST /api/v1/patents/search.
Call POST /api/v1/analysis/feature-mapping for each shortlisted patent.
Read the evidence: status, verbatim quote, source field, confidence.

The OpenAPI 3.1 spec can be imported into Postman, Swagger UI, or any code generator to scaffold client code automatically.