DocsSearch API

Search API

Semantic patent search using natural language queries. Search across patents from KR, US, JP, CN, and EP.

POST /search

Search patents using natural language. Supports multi-language queries (Korean, English, Japanese, Chinese).

Request Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Natural language search query
`top_k`	integer	No	10	Number of results to return (1–100)
`filters`	object	No	null	Search filters (see below)
`rerank`	boolean	No	false	Enable cross-encoder reranking

Filter Options

Pass a filters object to narrow search results:

Filter	Type	Example	Description
`country_codes`	string[]	`["KR","US"]`	Country codes
`kind_codes`	string[]	`["A1","B2"]`	Document kind codes
`applicants`	string[]	`["Samsung"]`	Applicant names (partial match)
`ipc_codes`	string[]	`["H01L21"]`	IPC codes (prefix match)
`publication_year_min`	integer	`2020`	Min publication year
`publication_year_max`	integer	`2025`	Max publication year
`filing_date_min`	string	`"2023-01-01"`	Min filing date (YYYY-MM-DD)
`filing_date_max`	string	`"2025-12-31"`	Max filing date (YYYY-MM-DD)

Request Example

cURL — Search with filters

curl -X POST https://api.findip.ai/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "lithium ion battery cathode material",
    "top_k": 20,
    "filters": {
      "country_codes": ["US", "KR"],
      "publication_year_min": 2022,
      "publication_year_max": 2025,
      "ipc_codes": ["H01M"]
    }
  }'

Response

200 OK

{
  "results": [
    {
      "publication_id": "US12261291B2",
      "publication_number": "US12261291B2",
      "application_number": "17123456",
      "country_code": "US",
      "kind_code": "B2",
      "score": 0.0317,
      "invention_title": "Positive electrode active material for lithium ion secondary battery",
      "abstract": null,
      "filing_date": "2022-01-15",
      "publication_date": "2025-03-25",
      "ipc_codes": ["H01M 4/525", "H01M 4/36"],
      "applicants": ["COMPANY NAME"],
      "matched_paragraphs": [
        {
          "section": "description",
          "section_name": null,
          "claim_num": null,
          "text": "Examples of materials that have been mainly proposed..."
        }
      ]
    }
  ],
  "total": 20,
  "query_time_ms": 1829
}

Response Fields

Field	Type	Description
`results`	array	List of matching patents
`results[].publication_id`	string	Unique publication identifier
`results[].score`	number	Relevance score (RRF fusion)
`results[].invention_title`	string	Title of the invention
`results[].matched_paragraphs`	array	Matched text paragraphs from the patent
`results[].ipc_codes`	string[]	IPC classification codes
`results[].applicants`	string[]	Patent applicant names
`total`	integer	Number of results returned
`query_time_ms`	integer	Query execution time in milliseconds

GET /documents/{publication_id}

Retrieve full details of a patent document including abstract, claims, description, and figures. This endpoint uses Smart Resolution — it automatically resolves ambiguous IDs and returns candidates when multiple matches are found.

Path & Query Parameters

Parameter	Type	Required	Description
`publication_id`	string (path)	Yes	Document ID (e.g., KR102021000001A, US12261291B2)
`year`	integer (query)	No	Publication year (optimizes partition pruning)
`sections`	string (query)	No	Sections to include: abstract, claims, description
`include_figures`	boolean (query)	No	Include figure info (default: true)

Response Scenarios

200 OK — Document found

Returns full document with abstract, claims, description, and figures.

300 Multiple Choices — Ambiguous ID

When the input ID matches multiple documents (e.g., just a number without country code), returns a list of candidates. The client should let the user pick one.

404 Not Found

No matching document found.

GET /figures/{publication_id}/{filename}

Retrieve patent figure images. Figure filenames are provided in the document detail response.

Query Parameters

Parameter	Default	Description
`size`	full	Image size: thumb (200px), medium (800px), full
`format`	original	Output format: original, png, jpg

Usage flow

# 1. Get document detail (includes figure URLs)
curl https://api.findip.ai/documents/KR1020240000001A \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response includes:
# "figures": [
#   {"filename": "pat00001.jpg", "url": "/figures/KR1020240000001A/pat00001.jpg"}
# ]

# 2. Fetch the figure image
curl https://api.findip.ai/figures/KR1020240000001A/pat00001.jpg \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o figure.jpg

POST /trends

Analyze patent trends for a technology area using natural language. Returns statistics grouped by year, IPC code, applicant, and country.

Request

curl -X POST https://api.findip.ai/trends \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "electric vehicle autonomous driving",
    "country_codes": ["KR", "US"],
    "year_min": 2020,
    "year_max": 2025,
    "top_k": 1000,
    "include": ["by_year", "by_ipc", "by_applicant", "by_country"]
  }'

Request Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Technology area to analyze
`country_codes`	string[]	No	All	Country filter
`year_min`	integer	No	2020	Start year
`year_max`	integer	No	Current year	End year
`top_k`	integer	No	1000	Number of patents to analyze (max 5000)
`include`	string[]	No	All	Stats to include: by_year, by_ipc, by_applicant, by_country, samples

POST /stats

Query patent statistics using SQL-based filters. Unlike /trends, this endpoint does not require a natural language query — it aggregates directly from the database.

Request

curl -X POST https://api.findip.ai/stats \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_codes": ["KR", "US"],
    "year_min": 2020,
    "year_max": 2025,
    "ipc_codes": ["H01M"],
    "group_by": ["year", "ipc"],
    "limit": 10
  }'

Request Parameters

Parameter	Type	Required	Description
`country_codes`	string[]	No	Country filter
`year_min / year_max`	integer	No	Year range filter
`ipc_codes`	string[]	No	IPC code filter (prefix match)
`applicants`	string[]	No	Applicant filter (LIKE match)
`group_by`	string[]	Yes	Grouping: year, ipc, applicant, country
`limit`	integer	No	Top N per group (default: 10)

Core Concepts Next: Authentication