Skip to content

docs(odds): document full selection_type enum + undocumented /odds fields#243

Open
paperclip-resolver[bot] wants to merge 1 commit into
mainfrom
paperclip/SHA-3434
Open

docs(odds): document full selection_type enum + undocumented /odds fields#243
paperclip-resolver[bot] wants to merge 1 commit into
mainfrom
paperclip/SHA-3434

Conversation

@paperclip-resolver
Copy link
Copy Markdown
Contributor

Fixes SHA-3434 (parent: SHA-3428 — rogervtay 6-category bug report; customer Crisp session_c8594804).

Summary

Reconciles the published /odds schema with what the Go API actually emits.

E1 — selection_type enum. Docs previously listed only home, away, over, under. Real wire values also include yes, no, even, odd, draw, other, plus compound forms emitted by multi-axis markets (home_over, away_under, home_yes, home_draw, home_r1, …). Added a ### Selection types section in all four locales and a 23-value enum in openapi.json. Both make clear that long-tail forms (correct_score "2_1", set_betting, winning_margin shapes, etc.) pass through verbatim and should be treated as opaque, not rejected.

E2 — undocumented /odds row fields. Per-field audit against sharp-api-go/main.go:603–664 (the Odds response struct) and a live /api/v1/odds Polymarket sample:

Field Decision Notes
event_uuid stable Canonical atlas event UUID.
team_side stable Raw side hint; lets clients get the team axis on compound selection_type without parsing.
is_alternate_line stable Stable on /opportunities/ev today; rolling out to /odds rows via SHA-3431 (B1 fix). Documented now so the customer + SDKs can wire to it.
wire_received_at stable Pipeline-arrival stamp. Differentiated from last_seen_at and odds_changed_at.
external_event_id stable Sportsbook's own event ID.
deep_link stable Resolver URL; state= query param documented for state-routed books.
market_id, selection_id stable Native sportsbook IDs.
volume, volume_24h, open_interest stable, exchange-only Betfair / Novig / ProphetX / Polymarket.
home_pitcher, away_pitcher stable, MLB-only Already in struct; previously undocumented.
polymarket_resolution stable, Polymarket-only UMA optimistic-oracle terminal status with the 5-value enum.

No field was filtered from the response — every flagged field is genuinely useful and stable enough to document.

Files

  • content/{en,es,de,pt-BR}/api-reference/odds.mdx — schema table + ### Selection types subsection
  • public/openapi.jsonOdds schema: selection_type.enum, 12 new properties

Verification

  • pnpm typecheck clean
  • pnpm build (Nextra, 4 locales, 223 pages) — green
  • pnpm check-links — 340/340 internal links resolve; 1 unrelated external (github.com/Mlaz-code/api-adapters, pre-existing)
  • Live sample probe against /api/v1/odds (Polymarket + Pinnacle rows on OVH) confirms all 9 E2 fields are emitted as documented

Test plan

  • Vercel preview build green
  • Spot-check anchor links: #selection-types, #tipos-de-selección, #selektionstypen, #tipos-de-seleção
  • Confirm openapi.json renders correctly in Scalar / the openapi.mdx preview page

…elds

Reconcile the published /odds schema with what the Go API actually
emits. Customer rogervtay (Pro tier, Crisp session_c8594804) flagged
this in the SHA-3428 6-category bug report; tracking issue SHA-3434.

E1 — selection_type previously listed only `home`, `away`, `over`,
`under`. Real wire values also include `yes`, `no`, `even`, `odd`,
`draw`, `other` plus compound forms emitted by multi-axis markets
(team × O/U, team × BTTS, double-chance, MMA round/method, etc.).
Added a `### Selection types` subsection in all four locales and a
23-value `enum` on the openapi.json `Odds` schema; both make clear
that long-tail compounds (correct_score "2_1", set_betting, etc.)
also pass through and should be treated as opaque rather than rejected.

E2 — added schema rows + openapi properties for all nine fields the
customer reported as undocumented but emitted: `event_uuid`, `team_side`,
`market_id`, `selection_id`, `external_event_id`, `wire_received_at`,
`deep_link`, `volume`, `volume_24h`, `open_interest`, `is_alternate_line`
(documented as stable per the SHA-3431 B1 fix wiring), `home_pitcher`,
`away_pitcher`, `polymarket_resolution`.

Verified by reading the `Odds` struct in sharp-api-go (main.go:603–664)
and against a live /api/v1/odds Polymarket sample. Typecheck + Nextra
build + check-links (340/340 internal) pass.

Fixes SHA-3434
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants