Patent Search

patents

Paginated, filterable listing of patent publications using direct indexed filters (company/assignee, CPC classification prefix, publication date range, country, legal status) - no graph traversal. include_total is declared required so every call computes the exact meta.total the agent quotes; never quote a page length as a total. Company filters accept an exact raw assignee string, 'organizations/<key>', 'ror:<id>' or 'lei:<id>' and resolve to the company's full graph id cluster (raw mentions + ROR/LEI entities); an unresolved company value or unknown CPC prefix returns HTTP 400 naming the value - the filter is never silently dropped, so an empty result always means the portfolio is truly empty. Requires a Pro workspace (returns HTTP 402 otherwise). Use patents.aggregate for counts, patents.yoy-growth for trends, and patents.details with a row's patent_id for the full enriched record.

When to use it

list a company's patents (via company_id or company_name)
patents under a CPC classification prefix (e.g. A61K for pharma)
recent patent publications for an assignee

Getting started

Base URL

https://app.caelrith.com/api/v1/tools

Authentication

Include your API key in the x-api-key header.

Parameters

Query parameters

Parameter	Type	Required	Description
company_id	string	No	Organization to filter on. Accepts an exact raw assignee string (as it appears in a patent's assignees array), 'organizations/<key>', 'ror:<id>', 'lei:<id>', or a bare ROR/LEI id. Takes precedence over company_name. Unresolved values return HTTP 400 (never silently ignored).
company_name	string	No	Resolved organization name, used as a fallback when company_id is not provided; the server resolves it to an organization.
cpc_code	string	No	CPC classification code or prefix (e.g. 'A61K'). Combined with include_descendants to expand the prefix.
include_descendants	string	No	When true (default), a cpc_code prefix expands to every code starting with it; set false for exact-code matches only. Allowed values: true, false
publication_date_from	string	No	YYYY-MM-DD; matches patents published on or after this date.
publication_date_to	string	No	YYYY-MM-DD; matches patents published on or before this date.
country	string	No	Country code (case-insensitive; the server uppercases it).
legal_status	string	No	Legal status filter (case-insensitive).
page	integer	No	Page number (default 1). Range: 1 to ∞
limit	integer	No	Results per page (1-100, default 20). Range: 1 to 100
sort	string	No	Sort field (default publication_date). Allowed values: publication_date, title
order	string	No	Sort direction (default desc). Allowed values: asc, desc
include_total	string	No	Must be true. Computes the exact result count (meta.total) which the agent must quote as the total; a page length must never be presented as a total. Allowed values: true, false

Example request

curl -H "x-api-key: YOUR_API_KEY" \
  "https://app.caelrith.com/api/v1/patents"

Response envelope

Successful responses wrap the payload in a success flag.

{
  "success": true,
  "data": { /* payload */ },
  "meta": { /* pagination, totals */ }
}

Response shape

List responsePATENTS

Payload: data — Patents

Exact total: meta.total

Pagination: server-side via page and limit

Common row fields

Field	Description
patent_id	Patent ID
title	Title
publication_date	Published
country	Country
assignees	Assignees
legal_status	—

Empty results: No matching rows (HTTP 200)

meta.total is always present because include_total is client-required - quote it as the exact result count. Unresolved company values (exact raw assignee string, organizations/<key>, ror:<id>, lei:<id>) and unknown CPC prefixes are rejected with HTTP 400 naming the value - the filter is never silently dropped, so an empty data array means the filters resolved and the portfolio is truly empty. meta.filters.company_id_resolved / company_cluster_size echo the resolved company anchor and the number of graph ids the filter spanned (raw mentions + ROR/LEI entities; null / 0 when no company filter was given); meta.filters.cpc_codes_matched echoes the expanded code count (null when no CPC filter).

Catalog version 0.0.0-generated · generated from the API source