API · v1 · private preview

The API serves the same substrate the map renders.

Every figure you can see on a CategoryRank page is reachable as JSON. Sha-pinned. Replayable. Honest about what is live today and what ships next.

11 live·10 fixture-locked·21 total·substrate week 2026-W23

Quick start

Get a key, hit one endpoint, see the same data the magazine renders.

01 · Get a key

Pro and Enterprise are in private preview. Email api@categoryrank.ai with the brand or category you want to track.

02 · Base URL

All endpoints sit under:

https://api.categoryrank.ai

03 · Authorize

Bearer token header on every request:

Authorization: Bearer $KEY

First call · validate your key

curl https://api.categoryrank.ai/v1/auth/me \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

Response envelope

Every successful response carries the same shape.

Endpoint-specific payload sits under data. Provenance and tier context sit under meta. If meta.status is fixture, the contract is locked but the substrate ships on the date in ships_when.

{
  "data": { /* endpoint payload */ },
  "meta": {
    "status": "live" | "fixture",
    "substrate_week": "2026-W23",
    "substrate_sha256": "e42a7b3179821eb4...",
    "tier": "pro",
    "rate_limit": { "remaining": 1487, "reset_at": "..." }
  }
}

Errors contract

Errors are JSON, never silent.

Four error categories: auth, tier, scope, substrate. We never return 200 with an empty body to hide insufficient data — if data isn’t there, we say why.

HTTP 403
{
  "error": {
    "category": "tier",
    "code": "tier_upgrade_required",
    "message": "Endpoint requires Pro tier.",
    "your_tier": "free",
    "required_tier": "pro"
  }
}

Endpoints

Grouped by the magazine surface each one powers.

Click through the magazine link on any group to see what the endpoint renders as. The substrate is the same; the JSON is just the wire format.

Authentication

Validate keys, inspect scopes, check rate limits.

GET/v1/auth/melive·Free

Validate your API key. First call any integrator makes.

ReturnsKey id, scopes, rate limit, tier (founding-5 / per-slug / ai-alpha / sandbox), and issued/expiry timestamps.

Show example

Request

curl https://api.categoryrank.ai/v1/auth/me \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

Brand Families (FAE layer)

Makers × series on one normalized compare axis per aisle — the "which one?" chooser as JSON. Licensed white-label surface; weekly refresh, sha-pinned for re-ship detection.

See it rendered →

GET/v1/familieslive·

Which aisles YOUR key can read (wallet-scoped). Build nav from this — never hardcode, never assume other aisles.

Returnswallet_slugs + per entitled aisle: kim_slug, week, layer_sha16, counts, compare_axis (incl. axis_ready + bins), endpoint templates. Deep FAE fields are NOT here — open a series.

Show example

Request

curl 'https://api.categoryrank.ai/v1/families' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/families/microcontrollers?bin=ultra_lowlive·

The aisle board: every maker’s series on ONE normalized compare axis. The "which one?" chooser as an API call.

Returnscompare_axis from layer _meta (id e.g. device_class|topology|power_class, axis_ready, bins). brands[] with brand_slug + series[] carrying aisle-native bin. ?bin=wtb or ?bin=buck filters. Connectivity LISTS live on the series endpoint.

Show example

Request

curl 'https://api.categoryrank.ai/v1/families/connectors?bin=wtb' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/families/microcontrollers/renesaslive·

One maker’s series cut, with the start_with shortlist an FAE would name first.

Returnsbrand_domain, brand_slug, known_for[{id,label}], compare_axis, start_with[] series keys, series[] summary rows. Use brand_slug in paths — do not invent from domain.

Show example

Request

curl 'https://api.categoryrank.ai/v1/families/microcontrollers/renesas' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/families/microcontrollers/renesas/ra4live·

THE full FAE payload — connectivity, eval boards, RTOS, docs, ADE, OEM program, siblings, peers. Call this for every series page.

Returnspositioning, product_groups, eval_boards[], rtos_middleware[], connectivity[] (evidence URLs), fae.{application,docs,ecosystem,has_ade}, oem_program, resources, sibling_series, peers[].

Show example

Request

curl 'https://api.categoryrank.ai/v1/families/microcontrollers/renesas/ra4' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

The category map

The L1 directory and per-category ranks. Mirrors /categories and /categories/[slug].

See it rendered →

GET/v1/ontology/categories?version=v5.2.0live·Free

253 Kim slugs with metadata. The discovery primitive.

ReturnsPer slug: slug_id, canonical_name, level, parent_id, is_leaf, ontology_scope (v4_baseline / v5_new). Paginated.

Show example

Request

curl 'https://api.categoryrank.ai/v1/ontology/categories?version=v5.2.0&page=1&page_size=100' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/category/{slug}/rank?brand={domain}&week=2026-W19live·Free

Where a brand ranks in a category, for one week.

Returnsrank, rank_total, n_claims, n_vantages, closest_frame (OEM/DIST/AGG/SEARCH), verdict, verdict_band, top_search_keywords.

Show example

Request

curl 'https://api.categoryrank.ai/v1/category/op-amps/rank?brand=ti.com&week=2026-W19' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/category/{slug}/leaderboard?week=2026-W19&limit=10live·Free

Top-N brands ranked within a category by n_claims.

ReturnsOrdered list: rank, brand_domain, n_claims, n_vantages, closest_frame, slug_max_cosine, convergence_score, verdict.

Show example

Request

curl 'https://api.categoryrank.ai/v1/category/op-amps/leaderboard?week=2026-W19&limit=10' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/categories/attribution?week=2026-W19live·Free

Bulk per-slug attribution: whose vocabulary AI is closest to.

ReturnsPer slug: verdict, closest_frame, verdict_band, n_claims, n_vantages, slug_max_cosine, convergence_score, top_search_keywords.

Show example

Request

curl 'https://api.categoryrank.ai/v1/categories/attribution?week=2026-W19' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/ai-alpha?limit=25&min_volume=100&min_n_keywords=5live·Pro

Where AI shops next. Underpriced L3 vocabulary, weekly.

ReturnsLeaderboard of 253 Kim slugs ranked by pct_underpriced_l3 — the fraction of L3+ AI-discovered keywords with bid_high < $2.50 (or null / no-bid).

Show example

Request

curl 'https://api.categoryrank.ai/v1/ai-alpha?week=2026-W19&limit=25&min_volume=100&min_n_keywords=5' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

In design

GET/v1/category/{slug}/vantagesPro · expected tier

5-vantage vocabulary divergence for a category — top terms per vantage (AI / OEM / Buyer / Distributor / Aggregator) plus the 10-cosine pairwise distance matrix. Powers the divergence panel on /categories/[slug].

Brand pages

Role-aware peer-set ranks for manufacturer / distributor / aggregator / EDA brands. Mirrors /categories/brands/[brand].

See it rendered →

GET/v1/brand/{domain}/categories?week=2026-W19live·Free

Every category AI puts a brand in, with verdict.

ReturnsPer category for this brand: kim_slug, canonical_name, rank, closest_frame, verdict, n_claims, n_vantages.

Show example

Request

curl 'https://api.categoryrank.ai/v1/brand/ti.com/categories?week=2026-W19' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/brand/{domain}/hqfixture · ships Live W20·Pro

Brand HQ country with multi-source consensus. The trust endpoint.

Returnshq_country, hq_country_label, downstream_safe flag, plus a `provenance.consensus` block: n_sources_agreeing, consensus_strength, source list.

Show example

Request

curl 'https://api.categoryrank.ai/v1/brand/murata.com/hq' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

In design

GET/v1/brand/{domain}/peer-set/rankPro · expected tier

Role-aware peer-set ranks for a brand. Returns ranks against the brand’s OWN archetype (distributor vs distributor, aggregator vs aggregator), not against manufacturers. Powers the L4 rank table on /categories/brands/[brand].

GET/v1/brand/{domain}/below-floorPro · expected tier

Below-floor substrate forensics for a brand: every category where the brand has measurable AI mentions but doesn’t clear the Core publication floor, with distance-to-floor per threshold.

GET/v1/brand/{domain}/language-fitPro · expected tier

Per-brand × per-category Language Fit matrix — cosine distance between this brand’s self-vocabulary (OEM-self vantage) and AI’s category description. One row per category the brand is observed in.

Demand signal

Per-category buyer-side demand attribution. Companion to the rank board.

See it rendered →

GET/v1/category/{slug}/demand-pullfixture · ships Live W20·Pro

Which downstream domains pull this category (AI / auto / etc).

Returnsdemand_pull_tier (high / medium / low), demand_domains (ai, auto, industrial, …), chatgpt_family_codes.

Show example

Request

curl 'https://api.categoryrank.ai/v1/category/ceramic-capacitors/demand-pull' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

Geographic substrate

Where the parts are made. Foundry concentration, chokepoint exposure, SEC 10-K disclosed dependencies. Paid tier.

See it rendered →

GET/v1/category/{slug}/supply-chain?week=2026-W19fixture · ships Live W21 (dedup’d substrate)·Enterprise

Atoms × bits blend: foundry overlay + chokepoint exposure + SEC 10-K supplier dependence.

Returnsfoundry, chokepoints[], sec_evidence[] (each with filing_url, ticker, filing_date, tier_1_defensible). Honest caveats included. Returns supply_chain: null with no_data_reason when below the defensibility floor.

Show example

Request

curl 'https://api.categoryrank.ai/v1/category/microcontrollers/supply-chain?week=2026-W19' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/brand/{domain}/supply-chain-exposure?week=2026-W19fixture · ships Live W21·Enterprise

Per-brand exposure across cleared categories.

ReturnsCounts of categories with chokepoint exposure, top exposed countries, brand cohort coverage flags.

Show example

Request

curl 'https://api.categoryrank.ai/v1/brand/broadcom.com/supply-chain-exposure?week=2026-W19' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/chokepoints?week=2026-W19fixture · ships Live W21·Enterprise

The 8 geographic chokepoints with country adjacency weights.

ReturnsPer chokepoint: name, countries, weight; country adjacency matrix used downstream by category/{slug}/supply-chain.

Show example

Request

curl 'https://api.categoryrank.ai/v1/chokepoints?week=2026-W19' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

GET/v1/brand/{domain}/sites?week=2026-W19fixture · ships Live W20·Enterprise

Validated manufacturing/facility sites for a brand.

ReturnsPer site: city, country, type, source_url, validated_at. Brands without coverage return sites: [] with status: PENDING_MANUAL_VALIDATION.

Show example

Request

curl 'https://api.categoryrank.ai/v1/brand/molex.com/sites?week=2026-W19' \
  -H "Authorization: Bearer $CATEGORYRANK_API_KEY"

In design

GET/v1/distributor/{domain}/ontology-eventsEnterprise · expected tier

Distributor ontology-shift events — when a distributor restructures their L1 taxonomy, what they removed, what they added, and the share-of-rail impact. Powers the Octopart-style ontology-shift narrative.

Automation

Webhooks for rank changes, ontology shifts, and substrate updates. Custom tier.

Replayability

Every response is sha-pinned.

meta.substrate_sha256 identifies the exact substrate snapshot used to compute the response. Pass ?as_of=2026-W21 on any read endpoint to request a historical snapshot; if we still have it, the response carries that week’s sha and the same payload it produced when fresh. When the substrate is re-shipped (Tapes regenerates an artifact), the sha changes, and the rank changes with it. No silent in-place rewrites.

Coverage discipline

We never ship contaminated metrics quietly.

When a distributor restructures its taxonomy mid-week or a substrate capture lands with partial inventory, affected endpoints set meta.coverage_metric below 1.0 and the response payload either suppresses contaminated rails or returns no_data_reason. If the figure can’t be defended, we don’t ship the figure.

Scope

What the API answers, and what it doesn’t.

Will answer

Where a brand ranks against its peer set in any category
How AI’s vocabulary for a category differs from OEM / distributor / aggregator / buyer language
What category mentions a brand has below the publication floor and how close to clearing
Geographic substrate per category (foundry concentration, country-fill)
Sha-pinned historical comparisons for sustained-consensus categories

Will not answer

Which LLM picked which brand (per-model picks are not exposed)
Raw cosine distances or centroid embeddings
Predictions of next-week rank — we observe, we don’t forecast
The full raw mention dump (aggregates only)
Categories below sustained-consensus floor (those are forensics-tier)

Access

Free is read-only on public surfaces. Paid unlocks the substrate.

The free tier carries the same public surfaces the magazine renders \u2014 enough to evaluate the product without an account. Pro and Enterprise unlock below-floor forensics, full Language Fit, full vantage matrix, and 21 weeks of trend history. Custom adds cohorts, webhooks, and bulk JSONL.

See pricing →Email api@categoryrank.ai