docs: nested refs + numerical_id (Phase 1g)

content/en/api-reference/leagues.mdx

@@ -75,20 +75,23 @@ for league in result['data']:
   "data": [
     {
       "id": "nba",
+      "numerical_id": 87,
       "name": "NBA",
       "sport": "basketball",
       "event_count": 15,
       "live_count": 2
     },
     {
       "id": "ncaab",
+      "numerical_id": 88,
       "name": "NCAAB",
       "sport": "basketball",
       "event_count": 27,
       "live_count": 1
     },
     {
       "id": "wnba",
+      "numerical_id": 89,
       "name": "WNBA",
       "sport": "basketball",
       "event_count": 0,
@@ -250,11 +253,22 @@ for league in result['data']:
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | string | League identifier (lowercase, use in API filters) |
+| `numerical_id` | integer \| null | Stable integer key for the league (frozen, never reused). New (May 2026) — additive, optional. See [Entity reference IDs](/en/concepts/entity-reference-ids). |
 | `name` | string | Human-readable league name |
 | `sport` | string | Parent sport ID |
 | `event_count` | integer | Total events currently available with odds |
 | `live_count` | integer | Events currently live/in-play |
 
+### New (May 2026): `numerical_id`
+
+`numerical_id` is a frozen, dense-from-1 integer assigned per league in the SharpAPI atlas. The full registry currently spans ~1,000 leagues across all 19 sports. Use it as a compact join/index key when storing rows in your own database.
+
+- **Frozen:** never reused or remapped.
+- **Optional:** absent (or `null`) for leagues that haven't been mapped yet — slug `id` is always present.
+- **Domain-scoped:** unique across leagues only.
+
+Every odds row and opportunity leg also carries a matching `league_ref` block (`{id, label, numerical_id}`) so you don't need to second-fetch this endpoint just to label a row. See [Entity reference IDs](/en/concepts/entity-reference-ids) for the full contract.
+
 ## Common Leagues
 
 The endpoint is the canonical source of truth — call `GET /api/v1/leagues` for the complete, up-to-date list. The atlas registry catalogs **600+ leagues across 30+ sports** including UEFA continental competitions, multiple basketball circuits per country, and full tennis/golf/MMA/esports/cricket coverage. The illustrative subset below shows the highest-volume entries you'll typically filter on:

content/en/api-reference/markets.mdx

@@ -80,6 +80,7 @@ for market in result['data']:
   "data": [
     {
       "id": "moneyline",
+      "numerical_id": 878,
       "name": "Moneyline",
       "description": "Bet on which team will win the game outright",
       "hasLine": false,
@@ -90,6 +91,7 @@ for market in result['data']:
     },
     {
       "id": "point_spread",
+      "numerical_id": 880,
       "name": "Point Spread",
       "description": "Bet on the point margin between teams",
       "hasLine": true,
@@ -100,6 +102,7 @@ for market in result['data']:
     },
     {
       "id": "total_points",
+      "numerical_id": 881,
       "name": "Total Points",
       "description": "Bet on the combined score of both teams (over/under)",
       "hasLine": true,
@@ -187,6 +190,7 @@ for market in result['data']:
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | string | Unique market identifier (use in API filters) |
+| `numerical_id` | integer \| null | Stable integer key for the market type (frozen, never reused). New (May 2026) — additive, optional. See [Entity reference IDs](/en/concepts/entity-reference-ids). |
 | `name` | string | Human-readable market name |
 | `description` | string | Brief description of the market |
 | `hasLine` | boolean | Whether this market includes a line value |
@@ -195,6 +199,16 @@ for market in result['data']:
 | `selection_count` | number \| null | Number of unique selections across all events |
 | `sports` | string[] | Sport IDs that currently have this market |
 
+### New (May 2026): `numerical_id`
+
+`numerical_id` is a frozen, dense-from-1 integer assigned per market type in the SharpAPI atlas. The market catalog covers ~3,000 canonical types (core lines + period markets + player props across all sports).
+
+- **Frozen:** never reused or remapped.
+- **Optional:** absent (or `null`) for niche markets that haven't been assigned an integer yet — slug `id` is always present.
+- **Domain-scoped:** unique across markets only.
+
+Every odds row and opportunity leg also carries a matching `market_ref` block (`{id, label, numerical_id}`). See [Entity reference IDs](/en/concepts/entity-reference-ids).
+
 ## Market Types
 
 ### Core Markets

content/en/api-reference/odds.mdx

@@ -175,6 +175,8 @@ Cursors are opaque — do not parse or construct them. They encode the sort posi
 
 ### Success (200)
 
+The example below shows the flat fields only. As of May 2026, every row also carries optional nested reference blocks (`home`, `away`, `sport_ref`, `league_ref`, `market_ref`, `sportsbook_ref`) — see [Nested reference blocks](#new-may-2026-nested-reference-blocks) below.
+
 ```json
 {
   "success": true,
@@ -319,6 +321,41 @@ X-Request-Id: req_abc123def456
 | `stat_category` | string\|undefined | Stat category, e.g. `points`, `rebounds` (player prop markets only) |
 | `public_bet_pct` | number\|undefined | Public betting ticket percentage (0.0-1.0). Currently BetMGM only. |
 | `max_bet` | number\|undefined | Maximum wager amount (USD) for this market type. Currently Pinnacle only. |
+| `home` | object\|undefined | **New (May 2026).** Nested home-team reference: `{id, numerical_id, name, abbreviation}`. See [Entity reference IDs](/en/concepts/entity-reference-ids). |
+| `away` | object\|undefined | **New (May 2026).** Nested away-team reference: `{id, numerical_id, name, abbreviation}`. |
+| `sport_ref` | object\|undefined | **New (May 2026).** Nested sport reference: `{id, numerical_id, name}`. |
+| `league_ref` | object\|undefined | **New (May 2026).** Nested league reference: `{id, numerical_id, label}`. |
+| `market_ref` | object\|undefined | **New (May 2026).** Nested market reference: `{id, numerical_id, label}`. |
+| `sportsbook_ref` | object\|undefined | **New (May 2026).** Nested sportsbook reference: `{id, numerical_id, label}`. |
+
+### New (May 2026): nested reference blocks
+
+Every odds row now carries six optional **nested reference objects** that bundle each entity's slug `id`, display label, and stable `numerical_id` directly with the row. The flat string fields (`sport`, `league`, `home_team`, `away_team`, `market_type`, `sportsbook`) remain unchanged — the new blocks are purely additive.
+
+```json
+{
+  "id": "pinnacle_mlb_yankees_redsox_moneyline_NYY",
+  "sportsbook": "pinnacle",
+  "sport": "baseball",
+  "league": "mlb",
+  "home_team": "New York Yankees",
+  "away_team": "Boston Red Sox",
+  "market_type": "moneyline",
+  "selection": "New York Yankees",
+  "odds_american": -135,
+
+  "home":           { "id": "new_york_yankees", "numerical_id": 20, "name": "New York Yankees", "abbreviation": "NYY" },
+  "away":           { "id": "boston_red_sox",   "numerical_id":  5, "name": "Boston Red Sox",   "abbreviation": "BOS" },
+  "sport_ref":      { "id": "baseball", "numerical_id":   3, "name": "Baseball" },
+  "league_ref":     { "id": "mlb",      "numerical_id": 354, "label": "MLB" },
+  "market_ref":     { "id": "moneyline","numerical_id": 878, "label": "Moneyline" },
+  "sportsbook_ref": { "id": "pinnacle", "numerical_id":  28, "label": "Pinnacle" }
+}
+```
+
+**When fields are absent.** Each block is emitted only when the underlying entity is mapped in the SharpAPI atlas. Unmapped entities (long-tail leagues, niche markets, fresh sportsbook additions) omit the block, in which case the flat field on the row is the only ID you'll see. Treat every block — and every inner field, including `numerical_id` and `abbreviation` — as optional.
+
+See [Entity reference IDs](/en/concepts/entity-reference-ids) for the full semantics, the dense-from-1 / frozen / never-reused contract, and recommended use cases (storage keys, cross-feed mapping, display labels).
 
 ## Sorting
 

content/en/api-reference/opportunities-arbitrage.mdx

@@ -262,6 +262,37 @@ X-Request-Id: req_arb789xyz012
 | `external_event_id` | string\|null | Sportsbook's native event ID |
 | `selection_id` | string\|null | Sportsbook's selection/outcome ID |
 | `market_id` | string\|null | Sportsbook's market ID |
+| `home` | object\|undefined | **New (May 2026).** Nested home-team reference: `{id, numerical_id, name, abbreviation}`. See [Entity reference IDs](/en/concepts/entity-reference-ids). |
+| `away` | object\|undefined | **New (May 2026).** Nested away-team reference: `{id, numerical_id, name, abbreviation}`. |
+| `sport_ref` | object\|undefined | **New (May 2026).** Nested sport reference: `{id, numerical_id, name}`. |
+| `league_ref` | object\|undefined | **New (May 2026).** Nested league reference: `{id, numerical_id, label}`. |
+| `market_ref` | object\|undefined | **New (May 2026).** Nested market reference: `{id, numerical_id, label}`. |
+| `sportsbook_ref` | object\|undefined | **New (May 2026).** Nested sportsbook reference for this leg's book: `{id, numerical_id, label}`. |
+
+### New (May 2026): nested reference blocks on each leg
+
+Every arbitrage leg now carries six optional nested reference objects, mirroring the shape on `/odds` and `/ev`. The flat top-level fields (`sport`, `league`, `home_team`, `away_team`, `market_type`) and per-leg `sportsbook` / `selection` strings are unchanged — the new blocks are purely additive.
+
+```json
+{
+  "legs": [
+    {
+      "sportsbook": "draftkings",
+      "selection": "Los Angeles Lakers",
+      "odds_american": 145,
+
+      "home":           { "id": "los_angeles_lakers", "numerical_id": 14, "name": "Los Angeles Lakers", "abbreviation": "LAL" },
+      "away":           { "id": "boston_celtics",     "numerical_id":  3, "name": "Boston Celtics",     "abbreviation": "BOS" },
+      "sport_ref":      { "id": "basketball", "numerical_id":   1, "name": "Basketball" },
+      "league_ref":     { "id": "nba",        "numerical_id":  87, "label": "NBA" },
+      "market_ref":     { "id": "moneyline",  "numerical_id": 878, "label": "Moneyline" },
+      "sportsbook_ref": { "id": "draftkings", "numerical_id":  12, "label": "DraftKings" }
+    }
+  ]
+}
+```
+
+Each block is emitted only when the underlying entity is mapped in the atlas; treat every block (and every inner field) as **optional**. The two competitor blocks (`home`, `away`) are identical across all legs of the same opportunity — the leg differs only in `sportsbook_ref`, `selection`, and the price. See [Entity reference IDs](/en/concepts/entity-reference-ids) for the full contract.
 
 ### CSV Format
 

content/en/api-reference/opportunities-ev.mdx

@@ -317,6 +317,36 @@ X-Request-Id: req_abc123def456
 | `oldest_odds_age_seconds` | number\|null | Age of the stalest odds used in the EV calculation (seconds) |
 | `warnings` | string[] | Data quality warnings (e.g., `POTENTIALLY_STALE_ODDS`, `LIVE_STALE_ODDS`) |
 | `detected_at` | string | ISO 8601 timestamp when the +EV was first detected |
+| `home` | object\|undefined | **New (May 2026).** Nested home-team reference: `{id, numerical_id, name, abbreviation}`. See [Entity reference IDs](/en/concepts/entity-reference-ids). |
+| `away` | object\|undefined | **New (May 2026).** Nested away-team reference: `{id, numerical_id, name, abbreviation}`. |
+| `sport_ref` | object\|undefined | **New (May 2026).** Nested sport reference: `{id, numerical_id, name}`. |
+| `league_ref` | object\|undefined | **New (May 2026).** Nested league reference: `{id, numerical_id, label}`. |
+| `market_ref` | object\|undefined | **New (May 2026).** Nested market reference: `{id, numerical_id, label}`. |
+| `sportsbook_ref` | object\|undefined | **New (May 2026).** Nested sportsbook reference: `{id, numerical_id, label}`. |
+
+### New (May 2026): nested reference blocks
+
+Every +EV row now carries six optional nested reference objects that bundle each entity's slug `id`, display label, and stable `numerical_id` alongside the row's flat fields. They are emitted by the in-process EV engine and are also present on `/api/v1/stream/opportunities` SSE frames.
+
+```json
+{
+  "id": "ev_pinnacle_mlb_yankees_redsox_moneyline_NYY",
+  "sportsbook": "draftkings",
+  "sport": "baseball",
+  "league": "mlb",
+  "market": "moneyline",
+  "ev_percentage": 4.2,
+
+  "home":           { "id": "new_york_yankees", "numerical_id": 20, "name": "New York Yankees", "abbreviation": "NYY" },
+  "away":           { "id": "boston_red_sox",   "numerical_id":  5, "name": "Boston Red Sox",   "abbreviation": "BOS" },
+  "sport_ref":      { "id": "baseball", "numerical_id":   3, "name": "Baseball" },
+  "league_ref":     { "id": "mlb",      "numerical_id": 354, "label": "MLB" },
+  "market_ref":     { "id": "moneyline","numerical_id": 878, "label": "Moneyline" },
+  "sportsbook_ref": { "id": "pinnacle", "numerical_id":  28, "label": "Pinnacle" }
+}
+```
+
+Each block is emitted only when the underlying entity is mapped in the SharpAPI atlas — treat every block (and every inner field) as **optional**. See [Entity reference IDs](/en/concepts/entity-reference-ids) for the full contract, the dense-from-1 / frozen / never-reused guarantees, and recommended use.
 
 ### Meta Summary Fields
 

content/en/api-reference/opportunities-middles.mdx

@@ -245,6 +245,36 @@ X-Request-Id: req_mid456abc789
 | `stake_percent` | number | Recommended stake allocation (% of total) |
 | `odds_age_seconds` | number\|null | Age of this side's odds at detection time |
 | `deep_link` | string\|null | Direct link to place this bet at the sportsbook |
+| `home` | object\|undefined | **New (May 2026).** Nested home-team reference: `{id, numerical_id, name, abbreviation}`. See [Entity reference IDs](/en/concepts/entity-reference-ids). |
+| `away` | object\|undefined | **New (May 2026).** Nested away-team reference: `{id, numerical_id, name, abbreviation}`. |
+| `sport_ref` | object\|undefined | **New (May 2026).** Nested sport reference: `{id, numerical_id, name}`. |
+| `league_ref` | object\|undefined | **New (May 2026).** Nested league reference: `{id, numerical_id, label}`. |
+| `market_ref` | object\|undefined | **New (May 2026).** Nested market reference: `{id, numerical_id, label}`. |
+| `sportsbook_ref` | object\|undefined | **New (May 2026).** Nested sportsbook reference for this side's book: `{id, numerical_id, label}`. |
+
+### New (May 2026): nested reference blocks on each side
+
+`side1` and `side2` each gain six optional nested reference objects, mirroring the shape on `/odds`, `/ev`, and `/arbitrage`. The flat top-level fields (`sport`, `league`, `home_team`, `away_team`, `market_type`) and per-side `book` / `selection` strings are unchanged — the new blocks are purely additive.
+
+```json
+{
+  "side1": {
+    "book": "draftkings",
+    "selection": "Kansas City Chiefs",
+    "line": -2.5,
+    "odds": { "american": -110, "decimal": 1.909, "probability": 0.524, "fair_probability": 0.524 },
+
+    "home":           { "id": "kansas_city_chiefs", "numerical_id": 11, "name": "Kansas City Chiefs", "abbreviation": "KC"  },
+    "away":           { "id": "buffalo_bills",      "numerical_id":  4, "name": "Buffalo Bills",      "abbreviation": "BUF" },
+    "sport_ref":      { "id": "football",   "numerical_id":   2, "name": "Football" },
+    "league_ref":     { "id": "nfl",        "numerical_id":  90, "label": "NFL" },
+    "market_ref":     { "id": "point_spread","numerical_id": 880, "label": "Point Spread" },
+    "sportsbook_ref": { "id": "draftkings", "numerical_id":  12, "label": "DraftKings" }
+  }
+}
+```
+
+Each block is emitted only when the underlying entity is mapped in the atlas; treat every block (and every inner field) as **optional**. The two competitor blocks (`home`, `away`) are identical across both sides of the same middle — the sides differ only in `sportsbook_ref`, `selection`, `line`, and the price. See [Entity reference IDs](/en/concepts/entity-reference-ids) for the full contract.
 
 ### Warning Flags
 

content/en/api-reference/sports.mdx

@@ -66,27 +66,31 @@ for sport in result['data']:
   "data": [
     {
       "id": "basketball",
+      "numerical_id": 1,
       "name": "Basketball",
       "leagues": ["nba", "ncaab", "wnba"],
       "event_count": 42,
       "live_count": 3
     },
     {
       "id": "football",
+      "numerical_id": 2,
       "name": "Football",
       "leagues": ["nfl", "ncaaf"],
       "event_count": 28,
       "live_count": 1
     },
     {
       "id": "hockey",
+      "numerical_id": 4,
       "name": "Hockey",
       "leagues": ["nhl"],
       "event_count": 15,
       "live_count": 2
     },
     {
       "id": "baseball",
+      "numerical_id": 3,
       "name": "Baseball",
       "leagues": ["mlb"],
       "event_count": 0,
@@ -141,11 +145,22 @@ for sport in result['data']:
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | string | Sport identifier (lowercase, use in API filters) |
+| `numerical_id` | integer \| null | Stable integer key for the sport (frozen, never reused). New (May 2026) — additive, optional. See [Entity reference IDs](/en/concepts/entity-reference-ids). |
 | `name` | string | Human-readable sport name |
 | `leagues` | string[] | League IDs within this sport |
 | `event_count` | integer | Total events currently available with odds |
 | `live_count` | integer | Events currently live/in-play |
 
+### New (May 2026): `numerical_id`
+
+`numerical_id` is a frozen, dense-from-1 integer assigned per sport in the SharpAPI atlas. Use it as a compact storage key when you don't need the human-readable slug.
+
+- **Frozen:** never reused or remapped once assigned.
+- **Optional:** absent (or `null`) for sports that haven't been mapped yet — the slug `id` is always present.
+- **Domain-scoped:** unique across sports only; pair with the entity domain to disambiguate.
+
+See [Entity reference IDs](/en/concepts/entity-reference-ids) for the full semantics, plus the matching `sport_ref` block emitted on every odds row and opportunity leg.
+
 ## Available Sports
 
 | ID | Display Name | Popular Leagues |

content/en/api-reference/sportsbooks.mdx

@@ -70,6 +70,7 @@ for book in result['data']:
   "data": [
     {
       "id": "draftkings",
+      "numerical_id": 12,
       "name": "draftkings",
       "display_name": "DraftKings",
       "has_live_odds": true,
@@ -83,6 +84,7 @@ for book in result['data']:
     },
     {
       "id": "fanduel",
+      "numerical_id": 14,
       "name": "fanduel",
       "display_name": "FanDuel",
       "has_live_odds": true,
@@ -161,6 +163,7 @@ for book in result['data']:
     },
     {
       "id": "pinnacle",
+      "numerical_id": 28,
       "name": "pinnacle",
       "display_name": "Pinnacle",
       "has_live_odds": true,
@@ -310,6 +313,7 @@ for book in result['data']:
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | string | Unique identifier (use in API filters) |
+| `numerical_id` | integer \| null | Stable integer key for the sportsbook (frozen, never reused). New (May 2026) — additive, optional. See [Entity reference IDs](/en/concepts/entity-reference-ids). |
 | `name` | string | Internal name (same as `id`) |
 | `display_name` | string | Human-readable name |
 | `has_live_odds` | boolean | Supports live/in-play odds |
@@ -325,6 +329,16 @@ for book in result['data']:
 The `event_count` may be 0 and `last_update` may be `null` if a sportsbook is temporarily unavailable or experiencing data delays.
 </Callout>
 
+### New (May 2026): `numerical_id`
+
+`numerical_id` is a frozen, dense-from-1 integer assigned per sportsbook in the SharpAPI atlas. It's stable across rebrands and slug renames — `pinnacle` is `numerical_id: 28` regardless of any future display-name changes.
+
+- **Frozen:** never reused or remapped.
+- **Optional:** absent (or `null`) for sportsbooks not yet mapped (e.g. brand-new books in the catalog before assignment); slug `id` is always present.
+- **Domain-scoped:** unique across sportsbooks only.
+
+Every odds row and opportunity leg also carries a matching `sportsbook_ref` block (`{id, label, numerical_id}`). See [Entity reference IDs](/en/concepts/entity-reference-ids).
+
 ## Book Access by Tier
 
 The `requires_tier` field indicates the minimum subscription tier needed to access a sportsbook's odds data through the API.