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.

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

Retrieve ONE patent's full record by its publication identifier (e.g. WO2021098789A1, EP3823456A1): abstract, inventors, classifications with CPC descriptions, family members, legal/priority/application dates, patent + NPL citations, graph-enriched citation counts, and resolved_assignees whose rows carry the full resolution chain (mention_id / direct_id / ultimate_id, with organization_id kept as the mention_id alias). Any of those ids is directly reusable as the company_id filter on patents.search / patents.aggregate / patents.yoy-growth - this closes the assignee -> portfolio chain. Responses use implicit 2xx (no success flag). Requires a Pro workspace (returns HTTP 402 otherwise).

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

Fast pre-computed aggregate patent counts (patent_agg_* tables), grouped by year, CPC code and/or company - group_by accepts a comma-separated subset of 'year','cpc','company'. IMPORTANT: country and legal_status are NOT supported here (HTTP 400) - use patents.search for those. The year range defaults to the current year and the two preceding calendar years; pass publication_date_from/to to widen it. Company filters accept an exact raw assignee string, 'organizations/<key>', 'ror:<id>' or 'lei:<id>'; unresolved company values and unknown CPC prefixes return HTTP 400 naming the value (never silently dropped). meta.total_buckets is the number of buckets returned, not the number of groups. Requires a Pro workspace (returns HTTP 402 otherwise). Use patents.search for listings and patents.yoy-growth for growth deltas.

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

Year-over-year patent growth by CPC code or company (dimension is required). Returns one row per group with oldCount (year_start), newCount (year_end), absolute change and percent change, sorted by growth or percent; percent is a fraction (0.35 = +35%). min_old_count (default 50) hides small groups - narrow with cpc_code / company_id or lower it. Defaults compare 2024 against 2025; pass year_start/year_end for other windows. Company filters accept an exact raw assignee string, 'organizations/<key>', 'ror:<id>' or 'lei:<id>'; unresolved company values and unknown CPC prefixes return HTTP 400 naming the value (never silently dropped). Requires a Pro workspace (returns HTTP 402 otherwise). Use patents.aggregate for plain counts.

curl -H "x-api-key: YOUR_API_KEY" \
  "https://app.caelrith.com/api/v1/patents/yoy-growth?dimension=cpc"