DocsSearch API

Search API

A semantic search engine that lets you search patents with natural-language sentences. Search US · KR · JP · CN · EP patents in a single call.

Search guide

For LLM natural-language search techniques and detailed search-combination guides, see the Search Guide in the left sidebar.

Authentication

All endpoints except the public coverage / health checks require the X-API-Key header. See Authentication for details.

POST /api/v1/search/semantic

Search patents with natural language. The query is embedded into a vector, matched with k-NN, then reranked. Multilingual queries are supported (Korean, English, Japanese, Chinese).

Request parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Natural-language search query (sentence form)
`top_k`	integer	No	10	Number of results to return (1–100 recommended)
`countries`	string[]	No	all 5	Subset of `["KR","US","CN","JP","EP"]`
`doc_type`	enum	No	`"all"`	`"all"` (application + grant, deduplicated) / `"application"` / `"grant"`
`kind_codes`	string[]	No	null	Specific kind codes (e.g. `["B1","B2"]`). Takes priority over `doc_type`
`include_utility_model`	boolean	No	false	Include utility models
`filing_date_from` / `_to`	string	No	null	Filing-date range (`YYYY-MM-DD`)
`publication_date_from` / `_to`	string	No	null	Publication-date range
`grant_date_from` / `_to`	string	No	null	Grant-date range (matches grant publications only)
`priority_date_from` / `_to`	string	No	null	Priority-date range
`applicant`	string	No	null	Applicant search term. Case-insensitive, accepts native-language input
`applicant_match`	enum	No	`"contains"`	`"contains"` / `"prefix"` / `"exact"`
`inventor`	string	No	null	Inventor search term (prefix match)
`ipc_codes`	string[]	No	null	IPC code prefixes (e.g. `["H01M10"]`)
`cpc_codes`	string[]	No	null	CPC code prefixes
`publication_number`	string	No	null	Exact publication number (KIPRIS format)
`application_number`	string	No	null	Exact application number
`family_id`	string	No	null	Exact family ID

Applicant matching

Applicant input is case-insensitive and accepts native-language names ("삼성전자", "华为", "ソニー", "APPLE"). A single input does not auto-expand across all five jurisdictions — search English and native names separately if you need cross-country coverage.

Request example

cURL — Semantic search with filters

curl -X POST https://api.findip.ai/api/v1/search/semantic \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "query": "solid electrolyte that suppresses lithium dendrite growth in all-solid-state batteries",
  "top_k": 20,
  "countries": ["KR", "US", "JP"],
  "doc_type": "application",
  "applicant": "SAMSUNG",
  "applicant_match": "prefix",
  "filing_date_from": "2022-01-01",
  "filing_date_to": "2024-12-31",
  "ipc_codes": ["H01M10"]
}'

Response

The response returns total (= results.length) and an array of result items.

200 OK

{
"total": 20,
"results": [
  {
    "patent_id": "KR1020230012345A",
    "title": "Secondary battery comprising a solid electrolyte",
    "applicant": "SAMSUNG SDI CO., LTD.",
    "filing_date": "2023-02-10",
    "publication_date": "2024-08-15",
    "ipc_codes": ["H01M10/0525", "H01M4/62"],
    "kind_code": "A",
    "country": "KR",
    "similarity_score": 0.8712,
    "rerank_score": 0.9345,
    "representative_figure": "fig_0001.webp",
    "chunks": [
      {
        "text": "The present invention provides a solid electrolyte for suppressing lithium dendrite growth ...",
        "chunk_type": "description",
        "section_name": "Detailed Description 3",
        "paragraph_numbers": [42, 43],
        "claim_numbers": [],
        "similarity_score": 0.8712,
        "rerank_score": 0.9345
      }
    ]
  }
]
}

Result item fields — patent_id (publication number, KIPRIS format), title, applicant, filing_date, publication_date, ipc_codes, kind_code, country, similarity_score (0–1, higher is more similar), rerank_score (BGE reranker — use rank order rather than absolute value), representative_figure (filename only — see drawings below), and chunks (matched passages sorted by rerank_score).

POST /api/v1/search/semantic-analytics

Runs the same vector search but returns statistics aggregation plus pagination — ideal for dashboards and landscape analysis. Accepts all /semantic filter fields. Use date_range + date_type instead of the individual date fields.

Request parameters (differences from /semantic)

Parameter	Type	Default	Description
`min_score`	float	0.5	Similarity threshold (`best_score >= min_score`)
`max_results`	integer	10000	Max documents considered for statistics
`date_range`	object	null	`{"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}`
`date_type`	enum	`"filing"`	`"filing"` / `"publication"` / `"grant"` / `"priority"`
`stats_group_by`	string[]	`["year","country"]`	Aggregation axes: `"year"`, `"country"`, `"applicant"`, `"ipc"`
`page`	integer	1	1-based page number
`page_size`	integer	20	Page size (1–100)

Request example

cURL — Search with statistics

curl -X POST https://api.findip.ai/api/v1/search/semantic-analytics \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "query": "5G beamforming antenna array",
  "min_score": 0.6,
  "max_results": 5000,
  "countries": ["KR", "US"],
  "date_range": {"from": "2020-01-01", "to": "2024-12-31"},
  "date_type": "filing",
  "stats_group_by": ["year", "country", "applicant", "ipc"],
  "page": 1,
  "page_size": 20
}'

Response

200 OK

{
"query": "5G beamforming antenna array",
"total_matched": 412,
"min_score_used": 0.6,
"page": 1,
"page_size": 20,
"total_pages": 21,
"stats": {
  "by_year": { "2020": 142, "2021": 180 },
  "by_country": { "KR": 230, "US": 182 },
  "top_applicants": [{ "name": "SAMSUNG ELECTRONICS CO., LTD.", "count": 58 }],
  "top_ipc": [{ "code": "H01Q", "count": 96 }]
},
"results": [
  {
    "patent_id": "KR1020210099999A",
    "title": "Beamforming antenna array for 5G base stations",
    "applicant": "SAMSUNG ELECTRONICS CO., LTD.",
    "country": "KR",
    "kind_code": "A",
    "filing_date": "2021-03-04",
    "publication_date": "2022-09-10",
    "ipc_codes": ["H01Q3/26"],
    "similarity_score": 0.7321,
    "chunk_text": "An antenna array configured for adaptive beamforming ..."
  }
]
}

The stats object contains by_year, by_country, top_applicants (max 20), and top_ipc (max 20), depending on the stats_group_by axes requested.

POST /api/v1/patents/details

Fetch full document details (markdown body + metadata) for one or more patents. Drawings are referenced inside the markdown body — assemble image URLs with the drawings rule below.

Request parameters

Parameter	Type	Required	Description
`patent_ids`	string[]	Yes	1–200 publication numbers (KIPRIS format)
`sections`	string	No	Comma-separated subset of `title,abstract,claims,description`. Omit for the full markdown

Request example

cURL — Document details

curl -X POST https://api.findip.ai/api/v1/patents/details \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "patent_ids": ["KR1020230012345A", "US20230123456A1"],
  "sections": "title,abstract,claims"
}'

Response

200 OK

{
"patents": [
  {
    "patent_id": "KR1020230012345A",
    "metadata": {
      "title": "Secondary battery comprising a solid electrolyte",
      "applicant": "SAMSUNG SDI CO., LTD.",
      "filing_date": "2023-02-10",
      "publication_date": "2024-08-15",
      "ipc_codes": ["H01M10/0525"],
      "kind_code": "A",
      "country": "KR"
    },
    "content": "# Title\n\n## Abstract\n\n...",
    "representative_figure": "fig_0001.webp"
  },
  {
    "patent_id": "US99999999B2",
    "error": "not_found"
  }
]
}

Each entry is returned per requested ID. If a patent cannot be found, that entry contains {"patent_id": "...", "error": "not_found"} instead of metadata — the overall response is still 200 OK.

GET /api/v1/drawings/{publication_id}/{filename}

Fetch a patent drawing image. No authentication required. The server returns a 302 redirect to a short-lived presigned URL; browsers and fetch follow it automatically, so the URL works directly in an <img src="...">.

The representative_figure field in search and detail responses returns the filename only. Assemble the image URL like this:

URL assembly

patent_id              = "KR1020240116067A"
representative_figure  = "pat00012.webp"

→ https://api.findip.ai/api/v1/drawings/KR1020240116067A/pat00012.webp

Allowed extensions: .webp, .jpg, .jpeg, .png (others return 400). Because presigned URLs change on every request, caching at the patent_id/filename key on the front end is recommended.

GET /api/v1/stats/coverage

Returns public coverage statistics (patent counts per country, date ranges, etc.). No authentication required. Cached for one hour. Returns 503 if the coverage document is unavailable.

Trends & Portfolio Next: Authentication