Developer documentation

Patent Intelligence API v1.1

Hybrid semantic search, publication lookup, and AI novelty analysis over the Indian patent corpus. Four REST endpoints, one MCP server for AI agents, one API key format, one set of 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

Hybrid semantic and text search over the Indian patent corpus. Send a plain-English description and get ranked patent records with composite, semantic, and text relevance scores, matched fields, and a coverage manifest that declares what was searched.

Request body

Field	Type	Required	Description
query	string	Yes	Plain-English search query, 2–2,000 characters.
limit	integer	No	Maximum results, 1–50. Default: 20.

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
  }'

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",
        "numberOfPages": 24,
        "numberOfClaims": 12,
        "extractionConfidence": 0.95,
        "source": {
          "name": "IP India Patent Journal",
          "document": "patent_journal_07_2023.pdf",
          "page": 142
        },
        "relevance": {
          "score": 0.87,
          "semanticScore": 0.91,
          "textScore": 0.72,
          "matchedFields": ["title", "abstract"]
        }
      }
    ],
    "coverage": {
      "corpus": "indian-patent-journal",
      "description": "Indian patent corpus sourced from IP India Patent Journal publications.",
      "jurisdiction": "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.

GET

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

Fetch a single Indian 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.

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",
    "numberOfPages": 24,
    "numberOfClaims": 12,
    "extractionConfidence": 0.95,
    "source": {
      "name": "IP India Patent Journal",
      "document": "patent_journal_07_2023.pdf",
      "page": 142
    }
  },
  "meta": { "requestId": "b2c3d4e5-f6a7-8901", "durationMs": 48 }
}

Returns 404 with error code PATENT_NOT_FOUND if the number does not match any Indian patent in the corpus.

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 semantic + text search. Same as POST /api/v1/patents/search.
get_patent	Fetch one patent by publication number. 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.

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.
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	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

Every patent record — whether from search results or a direct lookup — contains the following fields. Search results additionally include a relevance object.

Field	Type	Description
publicationNumber	string	Canonical publication number (e.g. IN202211045678A).
applicationNumber	string \| null	Raw application number as filed.
kind	string \| null	Kind code (A, B, etc.).
country	string	Two-letter country code (IN for Indian patents).
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.
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	Source corpus name.
source.document	string \| null	Original Journal PDF filename.
source.page	integer \| null	Page number in the source PDF.
relevance.score	number \| null	Composite relevance score (search only).
relevance.semanticScore	number \| null	Semantic similarity score (search only).
relevance.textScore	number \| null	Text match score (search only).
relevance.matchedFields	string[]	Fields that contributed to the match (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.