DocsSearch API

Search API

A semantic search engine that lets you search patents with natural-language sentences. Search US · KR · JP · CN · EP · PCT 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	Conditional	—	Natural-language search query (sentence form)
`image_url`	string	Conditional	null	Publicly reachable image URL. Finds patents whose drawings look visually similar
`sequence`	string	Conditional	null	Raw DNA / RNA / protein sequence. Finds patents containing similar sequences
`top_k`	integer	No	10	Number of results to return. The practical ceiling is about 100 — larger values are ignored without an error
`countries`	string[]	No	all	Subset of `["KR","US","CN","JP","EP","WO"]`
`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. Only takes effect when `doc_type` is `"application"` or `"grant"` (see below)
`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_entity_ids`	string[]	No	null	Exact applicant match. Multiple values are OR-ed
`inventor`	string	No	null	Inventor search term (prefix match)
`ipc_codes`	string[]	No	null	IPC codes. Normalized to the first 4 characters (subclass), e.g. `["H01M"]`
`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 (a filter that narrows search results — not a lookup that returns the whole family)

One of query, image_url, or sequence is required

With none of the three, the API returns 400 with query·image·sequence 중 하나가 필요합니다. They can also be combined — adding query to image_url or sequence re-ranks the visually or biologically similar hits by topic.

Only text search costs 1 search credit; using image_url or sequence costs 2 (see Authentication).

IPC code normalization

Whatever you pass, ipc_codes is truncated to the first 4 characters. "H01M10" and "H01M10/0525" therefore behave identically to "H01M", so you cannot narrow to group or subgroup level. Fewer than 4 characters returns 400 (classification code too short).

How utility models are included

include_utility_model only takes effect when doc_type is "application" or "grant". Under the default doc_type: "all", utility models are always included regardless of this flag.

With a doc_type set, turning it on adds Korean, Chinese and Japanese utility models (U) on the application side, and Korean granted utility models (Y1) on the grant side. The US and EP have no utility-model system, so nothing changes there.

Applicant matching

Filter by applicant with applicant_entity_ids, which matches only exact applicant identifiers. Matching is case-sensitive and substrings do not match, so pass the value exactly as it appears in applicants_harmonized in a search response (e.g. ["SAMSUNG ELECTRONICS CO LTD"]).

A single value does not auto-expand across native-language spellings or affiliates — list every identifier you want in the array (OR condition).

Filters apply only to what the query already found

Every filter narrows the results the query retrieved. So even a pinpoint filter like family_id will not pull in documents the query itself did not surface — if the query never reaches that document, you get 0 results. When a family ID you know exists returns nothing, broaden the query rather than the filter.

To fetch a specific document by number regardless of the query, use publication_number or POST /api/v1/patents/details.

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_entity_ids": ["SAMSUNG SDI CO LTD"],
  "filing_date_from": "2022-01-01",
  "filing_date_to": "2024-12-31",
  "ipc_codes": ["H01M"]
}'

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",
    "applicants": ["삼성에스디아이 주식회사"],
    "applicants_harmonized": ["SAMSUNG SDI CO LTD"],
    "inventors": ["HONG GILDONG", "KIM CHULSOO"],
    "inventors_harmonized": [],
    "application_number": "KR1020230012345",
    "family_id": "u:KR1020230012345A",
    "filing_date": "2023-02-10",
    "publication_date": "2024-08-15",
    "priority_date": "2022-02-10",
    "ipc_codes": ["H01M 10/0525", "H01M 4/62"],
    "kind_code": "A",
    "country": "KR",
    "legal_status": "PUBLISHED",
    "similarity_score": 0.7632,
    "rerank_score": 0.9468,
    "representative_figure": "112025002489408-pat00002.webp",
    "chunks": [
      {
        "text": "The present invention provides a solid electrolyte for suppressing lithium dendrite growth ...",
        "chunk_type": "description",
        "section_name": "Background Art 0",
        "paragraph_numbers": [3, 4],
        "claim_numbers": [],
        "similarity_score": 0.7632,
        "rerank_score": 0.9468
      }
    ],
    "family_member_count": 1
  }
]
}

Result item fields — patent_id (publication number, KIPRIS format), title, applicants (native-language applicant names), applicants_harmonized (normalized applicant names), inventors / inventors_harmonized, application_number, family_id, filing_date, publication_date, grant_date (granted publications only), priority_date, ipc_codes, kind_code, country, legal_status (GRANTED / PUBLISHED), similarity_score (0–1, higher is more similar), rerank_score (reranker — use rank order rather than absolute value), representative_figure (filename only — see drawings below), chunks (matched passages sorted by rerank_score), and family_member_count.

About response fields

Fields with no value for a given record may be omitted from the response. Do not assume every field is always present.

An image_url search adds image_score and matched_drawing to each result; a sequence search adds sequence_score and matched_seqs.

POST /api/v1/search/semantic-analytics

Runs the same vector search but returns statistics aggregation plus pagination — ideal for dashboards and landscape analysis. It accepts the countries, doc_type, kind_codes, include_utility_model, applicant_entity_ids, inventor, ipc_codes and cpc_codes filters, and uses date_range + date_type instead of the individual date fields.

publication_number, application_number and family_id are not supported here — they are ignored without an error, so use /semantic when you need to target a specific document by number.

Request parameters (differences from /semantic)

Parameter	Type	Default	Description
`min_score`	float	0.65	Similarity threshold (`best_score >= min_score`)
`max_results`	integer	10000	Max documents considered for statistics. The candidate pool itself saturates at roughly 1,000 per country (about 4,700 across KR, US, JP, CN, and EP combined), so larger values have no effect
`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,
"score_distribution": {
  "candidates_total": 658,
  "candidates_above_min_score": 651,
  "min": 0.3141,
  "p25": 0.5341,
  "median": 0.5757,
  "p75": 0.6108,
  "max": 0.7852
},
"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",
    "applicants": ["삼성전자주식회사"],
    "applicants_harmonized": ["SAMSUNG ELECTRONICS CO LTD"],
    "country": "KR",
    "legal_status": "PUBLISHED",
    "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. Responses also carry a diagnostic timing object.

Tuning min_score

The default of 0.65 is strict. With narrow filters it is common for a default call to come back with total_matched: 0, so tune it from score_distribution in the response. Lowering it toward median usually lands a workable population; raise it toward p75 when unrelated documents creep in.

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",
      "applicants": ["삼성에스디아이 주식회사"],
      "applicants_harmonized": ["SAMSUNG SDI CO LTD"],
      "inventors": ["HONG GILDONG"],
      "application_number": "KR1020230012345",
      "family_id": "u:KR1020230012345A",
      "filing_date": "2023-02-10",
      "publication_date": "2024-08-15",
      "priority_date": "2022-02-10",
      "ipc_codes": ["H01M 10/0525"],
      "kind_code": "A",
      "country": "KR",
      "legal_status": "PUBLISHED",
      "family_member_count": 1
    },
    "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.

Next: Authentication