Programmatic access to how AI hears electronics categories — which channel shaped AI's vocabulary (OEM, distributor, aggregator, or buyer-search), where each brand ranks, and the geographic substrate underneath. Weekly, sha-pinned, replayable.
AI is the X-axis. Other channels are reference frames.
Across 253 electronics-component categories, we measure how AI's category vocabulary aligns with four reference frames — OEM page language, distributor parametric trees, aggregator Q&A, and buyer-side search keywords. Per brand, per category, per week. Brand × Category × Model × Time.
We don't predict. We observe what AI is doing and which channel shaped it. Anyone can compute embedding distances; only CategoryRank has the cohort substrate to attribute AI's vocabulary to a specific reference frame across 99 brands × 174 cohort-stable categories × 21 weeks.
Every section of /api-docs maps to one or more endpoints below. The same data renders on this site for non-technical stakeholders; the API contract is the source of truth.
/v1/brand/{domain}/categories and /v1/category/{slug}/leaderboard tell you who AI mentions most for a given category. Rank function: n_claims (count of ecosystem-category-claim observations). Zero LLM judgment in the rank loop.
/v1/brand/{domain}/category/{slug}/drift returns up to 21 weeks of cohort-stable history for v4-baseline slugs, or up to 8 weeks for v5-new slugs. Each row carries ontology_scope and weeks_available so you know what you’re getting.
/v1/category/{slug}/supply-chain returns the geographic substrate for a category: foundry concentration, chokepoint exposure, SEC 10-K supplier-dependence quotes (filing URL + ticker + filing_date on every quote). Hard discipline — never silent zeros. Returns supply_chain: null with no_data_reason when below the defensibility floor.
Pro and Enterprise customers get an API key issued manually within 24 hours of signup. Free-trial keys self-serve at /pricing. Every call carries Authorization: Bearer cr_live_… and gets a per-key rate limit + scope check at the edge.
curl https://api.categoryrank.ai/v1/auth/me \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
Every /v1/* response carries the same three top-level keys. Request metadata in meta, domain payload in data, lineage in provenance (with optional consensus sub-block for multi-source-validated fields).
{
"meta": {
"api_version": "v1",
"endpoint": "/v1/category/{slug}/rank",
"status": "live",
"data_freshness": "2026-W20",
"customer_scope": "founding",
"slug": "op-amps",
"request_id": "req_01H9X3GQR4M2VJ8K"
},
"data": {
"kim_slug": "op-amps",
"rank": 1,
"n_claims": 10,
"closest_frame": "OEM",
"verdict": "ANCHORED_TO_OEM"
},
"provenance": {
"sources": ["llm_prior", "ontology", "geographic_substrate"],
"model_set": ["gpt-4o", "claude", "qwen-32b"],
"method": "category_alignment_v1",
"artifact_shas": [
{ "name": "tapes_brand_slug_weekly_rank_2026-W19.json", "sha16": "199e3e78a6410bbc" }
],
"consensus": {
"field": "hq_country",
"value": "JP",
"n_sources_agreeing": 3,
"consensus_strength": 0.91,
"downstream_safe": true
}
}
}api_version, endpoint, status (live | fixture-locked), data_freshness, customer_scope, slug/domain, request_id.
The domain payload. Shape varies per endpoint; documented per-endpoint below.
sources, model_set, method, artifact_shas[] (lineage). Optional consensus sub-block when a field passes multi-source validation.
Every endpoint ships behind the same auth, scope, rate limit, and envelope contract. Status badges are honest: live endpoints serve substrate data today; fixture-locked endpoints serve schema-valid fixtures while the live backing artifact ships on the date shown.
Validate your key. Inspect scopes. Every customer’s first call.
/v1/auth/melive nowscope auth:readValidate your API key. First call any integrator makes.
Key id, scopes, rate limit, tier (founding-5 / per-slug / ai-alpha / sandbox), and issued/expiry timestamps.
curl https://api.categoryrank.ai/v1/auth/me \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
The 253 Kim slug catalog. Discovery primitive for everything else.
/v1/ontology/categories?version=v5.2.0live nowscope ontology:read253 Kim slugs with metadata. The discovery primitive.
Per slug: slug_id, canonical_name, level, parent_id, is_leaf, ontology_scope (v4_baseline / v5_new). Paginated.
curl 'https://api.categoryrank.ai/v1/ontology/categories?version=v5.2.0&page=1&page_size=100' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
Brand × category × week. No LLM judgment in the rank loop.
/v1/category/{slug}/rank?brand={domain}&week=2026-W19live nowscope category:readWhere a brand ranks in a category, for one week.
rank, rank_total, n_claims, n_vantages, closest_frame (OEM/DIST/AGG/SEARCH), verdict, verdict_band, top_search_keywords.
curl 'https://api.categoryrank.ai/v1/category/op-amps/rank?brand=ti.com&week=2026-W19' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
/v1/category/{slug}/leaderboard?week=2026-W19&limit=10live nowscope category:readTop-N brands ranked within a category by n_claims.
Ordered list: rank, brand_domain, n_claims, n_vantages, closest_frame, slug_max_cosine, convergence_score, verdict.
curl 'https://api.categoryrank.ai/v1/category/op-amps/leaderboard?week=2026-W19&limit=10' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
/v1/brand/{domain}/categories?week=2026-W19live nowscope brand:readEvery category AI puts a brand in, with verdict.
Per category for this brand: kim_slug, canonical_name, rank, closest_frame, verdict, n_claims, n_vantages.
curl 'https://api.categoryrank.ai/v1/brand/ti.com/categories?week=2026-W19' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
Whose vocabulary AI’s category language is closest to: OEM, distributor, aggregator, or buyer-search.
/v1/categories/attribution?week=2026-W19live nowscope category:readBulk per-slug attribution: whose vocabulary AI is closest to.
Per slug: verdict, closest_frame, verdict_band, n_claims, n_vantages, slug_max_cosine, convergence_score, top_search_keywords.
curl 'https://api.categoryrank.ai/v1/categories/attribution?week=2026-W19' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
/v1/category/{slug}/demand-pullfixture · Live W20scope category:readWhich downstream domains pull this category (AI / auto / etc).
demand_pull_tier (high / medium / low), demand_domains (ai, auto, industrial, …), chatgpt_family_codes.
curl 'https://api.categoryrank.ai/v1/category/ceramic-capacitors/demand-pull' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
/v1/brand/{domain}/hqfixture · Live W20scope brand:readBrand HQ country with multi-source consensus. The trust endpoint.
hq_country, hq_country_label, downstream_safe flag, plus a `provenance.consensus` block: n_sources_agreeing, consensus_strength, source list.
curl 'https://api.categoryrank.ai/v1/brand/murata.com/hq' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
Week-over-week movement. Up to 21 weeks of cohort-stable history.
/v1/brand/{domain}/category/{slug}/drift?weeks=12fixture · Live W21scope brand:readWeek-over-week rank and anchoring drift for a brand × slug.
Per-week history of rank, n_claims, closest_frame. Carries ontology_scope and weeks_available (21 for v4_baseline, 8 for v5_new).
curl 'https://api.categoryrank.ai/v1/brand/ti.com/category/op-amps/drift?weeks=12' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
Where AI shops next. Underpriced L3 vocabulary, weekly.
/v1/ai-alpha?limit=25&min_volume=100&min_n_keywords=5live nowscope category:readWhere AI shops next. Underpriced L3 vocabulary, weekly.
Leaderboard 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).
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"
// fixture pending
The geographic substrate joined to the vocabulary substrate. Foundry, chokepoints, SEC 10-K supplier dependence.
/v1/category/{slug}/supply-chain?week=2026-W19fixture · Live W21 (dedup’d substrate)scope supply-chain:readAtoms × bits blend: foundry overlay + chokepoint exposure + SEC 10-K supplier dependence.
foundry, 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.
curl 'https://api.categoryrank.ai/v1/category/microcontrollers/supply-chain?week=2026-W19' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
/v1/brand/{domain}/supply-chain-exposure?week=2026-W19fixture · Live W21scope brand:readPer-brand exposure across cleared categories.
Counts of categories with chokepoint exposure, top exposed countries, brand cohort coverage flags.
curl 'https://api.categoryrank.ai/v1/brand/broadcom.com/supply-chain-exposure?week=2026-W19' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
/v1/chokepoints?week=2026-W19fixture · Live W21scope supply-chain:readThe 8 geographic chokepoints with country adjacency weights.
Per chokepoint: name, countries, weight; country adjacency matrix used downstream by category/{slug}/supply-chain.
curl 'https://api.categoryrank.ai/v1/chokepoints?week=2026-W19' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
/v1/brand/{domain}/sites?week=2026-W19fixture · Live W20scope brand:readValidated manufacturing/facility sites for a brand.
Per site: city, country, type, source_url, validated_at. Brands without coverage return sites: [] with status: PENDING_MANUAL_VALIDATION.
curl 'https://api.categoryrank.ai/v1/brand/molex.com/sites?week=2026-W19' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
Subscribe to rank_change and supply_chain_alert events.
/v1/webhooks/subscribefixture · Live W22scope webhook:writeSubscribe to events (rank_change, supply_chain_alert).
Webhook id (cr_wh_…), url, events[], status.
curl -X POST 'https://api.categoryrank.ai/v1/webhooks/subscribe' \
-H "Authorization: Bearer $CATEGORYRANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://your.app/webhook","events":["rank_change","supply_chain_alert"]}'// fixture pending
/v1/webhooksfixture · Live W22scope webhook:writeList your active webhook subscriptions.
Array of { id, url, events, status, created_at, last_delivered_at }.
curl 'https://api.categoryrank.ai/v1/webhooks' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
/v1/webhooks/{id}fixture · Live W22scope webhook:writeDelete a webhook subscription.
Confirmation with deleted_id and deleted_at.
curl -X DELETE 'https://api.categoryrank.ai/v1/webhooks/cr_wh_01ARZ3NDEKTSV4RRFFQ69G5FAV' \ -H "Authorization: Bearer $CATEGORYRANK_API_KEY"
// fixture pending
Blocked-because-consensus, blocked-because-below-defensibility-floor, and blocked-because-out-of-scope are first-class conditions — each with its own error code, an explainable blocked_reason, and a 422 status (not a 500). Customers can integrate against the codes; nothing leaks as a server error.
{
"error": {
"code": "FIELD_NOT_DOWNSTREAM_SAFE",
"message": "This field is blocked because consensus validation failed.",
"blocked_reason": "Insufficient independent agreement across source tapes.",
"request_id": "req_01H9X3GQR4M2VJ8K",
"docs_url": "https://www.categoryrank.ai/api-docs#errors"
}
}UNAUTHORIZEDMissing or invalid Authorization header.
SCOPE_REQUIREDAPI key lacks the scope needed for this endpoint.
SLUG_NOT_IN_CONTRACTPer-slug customer: this slug isn't in your allowed_slugs list.
RATE_LIMIT_EXCEEDEDRate limit hit. See X-RateLimit-* response headers.
FIELD_NOT_DOWNSTREAM_SAFEA field failed multi-source consensus validation. blocked_reason explains.
BELOW_DEFENSIBILITY_FLOORNot enough cohort coverage to serve this slug honestly. supply_chain: null with no_data_reason.
Every numeric in every API response is reproducible byte-for-byte from a sha-pinned source artifact in three hops. No LLM judgment in the verification loop. Customer CTO never trusts our math without a verification path.
GET response → response.provenance.artifact_shas[i].sha16 → resolve at /shared/exports/<artifact_path> → match shasum -a 256 prefix → read source data → confirm n_claims / verdict / etc.
Three hops, all sha-pinned. Every customer-visible field has a documented derivation path back to a source artifact. We don't promise the data is right; we let you check.
Every response carries a terms_of_use block. SEC quotes ship with filing_url, filing_date, ticker, and a tier_1_defensible flag. Customers can cite our work by pointing at any sha-pinned artifact + URL.
"terms_of_use": {
"citation_required": true,
"machine_readable_use": "permitted_with_attribution",
"llm_training_use": "prohibited_without_separate_license",
"source_attribution": "CategoryRank.ai · sha-pinned from public sources",
"license_url": "https://categoryrank.ai/api/terms"
}Honest framing. If a customer needs one of these, we'd rather say so up front.
We don’t tell you which part to buy. We tell you whose vocabulary AI uses for the category that part belongs to.
Weekly cadence, cohort-stable since W52 2025.
Programmatic only. The CategoryRank UI is a reference viewer that renders the same API payloads; the API contract is the source of truth.
We don’t position against Resilinc / Everstream / Interos / Z2Data. We’re the bits side joined to atoms — geographic substrate, not atoms-only.
All claims are observational at the reporting week. Drift surfaces movement; doesn’t forecast direction.
Rich descriptions (Qwen-validated 80–100 word analyst prose) per (brand, slug); cross-link top_keywords into /v1/category/{slug}/demand-pull.
Per-(brand, slug) attribution validated against held-out cohort vocabulary (Validation 1, 2026-06-13 deadline).
Lead-lag empirical claim (Validation 5): lane disruption at week N predicts cosine-OEM shift at weeks N+4..N+8 in >50% of brand's cohort-stable slugs.
Post-substrate-row-inflation rebuild: tightens brand-level metrics from row-counts to distinct-site counts.
Tier matrix locked 2026-05-15. Free trial is self-serve. Pro and Enterprise are manual onboarding for the first cohort — we issue keys and walk you through the API within 24 hours.