{ "components": { "headers": { "Retry-After": { "description": "Minimum number of seconds to wait before retrying.", "schema": { "minimum": 1, "type": "integer" } }, "WWW-Authenticate": { "description": "Bearer authentication challenge.", "schema": { "type": "string" } }, "X-Cache": { "description": "Disposable response-cache outcome. HIT means the response was served from cache. MISS means the cache was available but no usable entry existed, so the response was fetched from source; lifecycle-empty or oversized responses and best-effort write failures may not be stored. The header is absent for non-eligible routes, live=1 event discovery, disabled caching, or cache unavailability.", "schema": { "enum": [ "HIT", "MISS" ], "type": "string" } }, "X-Credits-Cost": { "description": "Credits charged for this response. Present on metered responses; zero means no charge.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Credits-Daily-Limit": { "description": "Independent UTC-daily credit limit.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Credits-Daily-Remaining": { "description": "UTC-daily credits spendable after this response.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Credits-Daily-Reset": { "description": "Next 00:00 UTC daily reset timestamp.", "schema": { "format": "date-time", "type": "string" } }, "X-Credits-Limit": { "description": "Plan-period credit limit (compatibility alias).", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Credits-Period-Limit": { "description": "Current plan-period credit limit.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Credits-Period-Remaining": { "description": "Plan-period credits spendable after this response.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Credits-Period-Reset": { "description": "Exact plan-period reset timestamp in UTC.", "schema": { "format": "date-time", "type": "string" } }, "X-Credits-Remaining": { "description": "Plan-period credits spendable after this response (compatibility alias).", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Next-Cursor": { "description": "Opaque continuation cursor for the next live-event page. When present, repeat the original filters and pass this value as cursor within five minutes. Absence means the scan is complete only when X-Result-Truncated is false; if truncation is true, narrow the filters and restart.", "schema": { "maxLength": 1024, "type": "string" } }, "X-Request-Id": { "description": "Opaque request ID for support correlation.", "schema": { "type": "string" } }, "X-Result-Rows": { "description": "Validated result rows. Always present on successful data responses and zero on metered errors.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Result-Truncated": { "description": "Whether additional matching rows may exist beyond this successful response. Narrow the filters or continue incremental polling when true.", "schema": { "type": "boolean" } }, "X-SharpRelay-Origin": { "description": "Canonical SharpRelay API origin that owns this response.", "schema": { "format": "uri", "type": "string" } } }, "schemas": { "APIError": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine-readable error code.", "type": "string" }, "message": { "description": "Safe human-readable explanation. Backend implementation details are never returned.", "type": "string" }, "request_id": { "description": "Opaque support correlation ID; also returned in X-Request-Id.", "type": "string" } }, "required": [ "code", "message", "request_id" ], "type": "object" }, "APIKeyScopes": { "description": "Non-empty least-privilege capabilities attached to this API key.", "items": { "enum": [ "data:read", "account:manage" ], "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array", "uniqueItems": true }, "AccountRecoveryAccepted": { "additionalProperties": false, "properties": { "message": { "description": "Generic response that does not disclose whether the address exists, is verified, is eligible, is cooling down, or queued email.", "type": "string" }, "status": { "const": "accepted", "type": "string" } }, "required": [ "status", "message" ], "type": "object" }, "AccountRecoveryClaimRequest": { "additionalProperties": false, "properties": { "recovery_token": { "description": "Opaque bearer read from the same-origin /recover URL fragment and submitted only in this body. Never put it in a query string, log, analytics event, or support ticket.", "pattern": "^rcv_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$", "type": "string" } }, "required": [ "recovery_token" ], "type": "object" }, "AccountRecoveryRequest": { "additionalProperties": false, "properties": { "email": { "format": "email", "maxLength": 254, "type": "string" }, "turnstile_token": { "description": "Fresh single-use token emitted by the same-origin recovery page and verified for the exact account_recovery action and public hostname.", "maxLength": 2048, "type": "string" } }, "required": [ "email", "turnstile_token" ], "type": "object" }, "AccountRecoverySuccess": { "additionalProperties": false, "properties": { "api_key": { "description": "The sole replacement key created by this recovery. All previously active API keys have been revoked.", "readOnly": true, "type": "string" }, "message": { "type": "string" }, "recovery_expires_at": { "description": "End of the 10-minute interrupted-delivery retry window for this exact recovery bearer.", "format": "date-time", "readOnly": true, "type": "string" }, "scopes": { "$ref": "#/components/schemas/APIKeyScopes" } }, "required": [ "api_key", "scopes", "recovery_expires_at", "message" ], "type": "object" }, "CheckoutIntentRequest": { "additionalProperties": false, "description": "Supply the email-fragment resume_token explicitly, or send an empty JSON object from /checkout to use the short-lived HttpOnly resume cookie. Cookie authentication additionally requires the exact public Origin, Sec-Fetch-Site: same-origin, and application/json.", "properties": { "resume_token": { "description": "Short-lived opaque fallback bearer delivered only in an emailed /checkout URL fragment and retained by that first-party-only page. Never log or place it in a query string.", "pattern": "^res_[A-Za-z0-9_-]{43}$", "type": "string" } }, "type": "object" }, "CheckoutIntentResponse": { "additionalProperties": false, "properties": { "checkout_url": { "description": "Freshly retrieved Stripe-hosted URL; present only while the exact Session remains open.", "format": "uri", "type": "string" }, "next_url": { "description": "First-party continuation present only when payment is already complete.", "enum": [ "/claim" ], "type": "string" }, "status": { "enum": [ "open", "complete", "closed" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "ClaimPending": { "additionalProperties": false, "properties": { "message": { "type": "string" }, "status": { "const": "claim_pending", "type": "string" } }, "required": [ "status", "message" ], "type": "object" }, "ClaimRequest": { "additionalProperties": false, "description": "Submit a checkout claim credential, or an empty JSON object when the same-origin browser uses the server-bounded HttpOnly claim cookie. Emailed links use claim_token. Cookie-authenticated requests require the exact public Origin, Sec-Fetch-Site: same-origin, and application/json. If delivery is interrupted, the exact same credential can retrieve the same result for at most 10 minutes.", "oneOf": [ { "required": [ "claim_token" ] }, { "maxProperties": 0 } ], "properties": { "claim_token": { "description": "Preferred opaque credential read by the same-origin claim page from the URL fragment and submitted only in this POST body. Retain it only until the API key response is safely stored; an exact retry can recover an interrupted delivery for at most 10 minutes.", "minLength": 1, "pattern": "^clm_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$", "type": "string" } }, "type": "object" }, "ClaimSuccess": { "additionalProperties": false, "properties": { "api_key": { "description": "New plaintext API key. Store it immediately. After the first successful claim, only the exact same claim credential can retrieve this result, and only during the 10-minute delivery-retry window.", "readOnly": true, "type": "string" }, "docs_url": { "format": "uri", "type": "string" }, "email": { "format": "email", "type": "string" }, "plan": { "type": "string" }, "scopes": { "$ref": "#/components/schemas/APIKeyScopes" } }, "required": [ "api_key", "scopes", "email", "plan", "docs_url" ], "type": "object" }, "ClosingLine": { "additionalProperties": false, "description": "The latest available closing price snapshot for one event market, period, and line. Closing data can be corrected and must be refreshed when revisions matter.", "properties": { "alt_line_id": { "description": "Identifier for an alternate spread or total line; null for the primary line.", "type": [ "integer", "null" ] }, "cutoff": { "description": "UTC time after which the market or line is no longer offered.", "type": [ "string", "null" ] }, "event_id": { "description": "Stable event identifier used across event, odds, line, result, and special-market calls.", "type": [ "integer", "null" ] }, "line": { "description": "Spread or total value from the selected side's perspective.", "type": [ "number", "null" ] }, "line_id": { "description": "Stable identifier for this market line snapshot.", "type": [ "integer", "null" ] }, "market": { "description": "Market family: moneyline, spread, totals, home_totals, or away_totals.", "type": [ "string", "null" ] }, "max_win": { "description": "Maximum win amount indicated for the line, when available.", "type": [ "number", "null" ] }, "odds0": { "description": "Decimal draw price; for totals-style markets, the middle outcome when supplied.", "type": [ "number", "null" ] }, "odds1": { "description": "Decimal home-side price; for totals-style markets, the over price.", "type": [ "number", "null" ] }, "odds2": { "description": "Decimal away-side price; for totals-style markets, the under price.", "type": [ "number", "null" ] }, "period": { "description": "Sport-specific period number; 0 represents the full event.", "type": [ "integer", "null" ] }, "result_status": { "description": "Numeric result state associated with the closing-line row.", "type": [ "integer", "null" ] }, "score_away": { "description": "Away-side score for this period or snapshot, when supplied.", "type": [ "number", "null" ] }, "score_home": { "description": "Home-side score for this period or snapshot, when supplied.", "type": [ "number", "null" ] }, "status": { "description": "Numeric availability-state code for this line snapshot.", "type": [ "integer", "null" ] }, "timestamp": { "description": "UTC time at which this price snapshot was recorded.", "type": [ "string", "null" ] }, "todds0": { "description": "Margin-removed fair decimal draw price, or middle-outcome fair price when supplied.", "type": [ "number", "null" ] }, "todds1": { "description": "Margin-removed fair decimal home-side price; for totals-style markets, the over fair price.", "type": [ "number", "null" ] }, "todds2": { "description": "Margin-removed fair decimal away-side price; for totals-style markets, the under fair price.", "type": [ "number", "null" ] } }, "type": "object" }, "ClosingLineValue": { "additionalProperties": false, "description": "Closing-line analysis for the supplied bet after a suitable event and closing price are matched.", "properties": { "closing_odds": { "description": "Observed decimal closing price matched to the supplied bet.", "type": [ "number", "null" ] }, "clv": { "description": "Closing-line-value result for the supplied bet and matched closing price.", "type": [ "number", "null" ] }, "expected_win": { "description": "Expected win amount for the supplied stake, expressed in the stake currency or unit.", "type": [ "number", "null" ] }, "true_closing_odds": { "description": "Margin-removed fair decimal closing price matched to the supplied bet.", "type": [ "number", "null" ] } }, "type": "object" }, "ErrorResponse": { "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/APIError" } }, "required": [ "error" ], "type": "object" }, "Event": { "additionalProperties": false, "description": "One future pre-game event by default, a currently offered in-play event with live=1, or a lifecycle-specific event selected through an explicit identifier or genuinely past kickoff window. A present or future starts_from remains locally enforced as a future lower bound, and a supplied starts_to remains locally enforced as the inclusive timestamp or complete UTC day. Fields are omitted or null when not available for that event state.", "properties": { "closing_available": { "description": "Whether a closing-line snapshot is currently available.", "type": [ "boolean", "integer", "null" ] }, "event_id": { "description": "Stable event identifier used across event, odds, line, result, and special-market calls.", "type": [ "integer", "null" ] }, "live_status": { "description": "Numeric in-play state for the event. A live=1 listing returns the event only after current open-offer verification.", "type": [ "integer", "null" ] }, "opening_available": { "description": "Whether an opening-line snapshot is currently available.", "type": [ "boolean", "integer", "null" ] }, "parent_id": { "description": "Parent event identifier for child or derivative fixtures, when applicable.", "type": [ "integer", "null" ] }, "resulting_unit": { "description": "Scoring or settlement unit used for the event, when supplied.", "type": [ "string", "null" ] }, "runner_away": { "description": "Away runner or team display name.", "type": [ "string", "null" ] }, "runner_home": { "description": "Home runner or team display name.", "type": [ "string", "null" ] }, "starts": { "description": "Scheduled event start time in UTC.", "type": [ "string", "null" ] }, "version": { "description": "Monotonic event version used to recognize updates.", "type": [ "integer", "null" ] } }, "type": "object" }, "KeyRotationSuccess": { "additionalProperties": false, "properties": { "api_key": { "description": "The replacement API key. Store it before discarding the old key and rotation nonce.", "readOnly": true, "type": "string" }, "message": { "type": "string" }, "recovery_expires_at": { "description": "End of the delivery-retry window. Until then, the exact old API key and exact Idempotency-Key can recover this same response.", "format": "date-time", "readOnly": true, "type": "string" }, "scopes": { "$ref": "#/components/schemas/APIKeyScopes" } }, "required": [ "api_key", "scopes", "recovery_expires_at", "message" ], "type": "object" }, "League": { "additionalProperties": false, "description": "One league currently discoverable for the requested sport.", "properties": { "container": { "description": "Higher-level competition or regional grouping, when supplied.", "type": [ "string", "null" ] }, "country_code": { "description": "Competition country code, when supplied.", "type": [ "string", "null" ] }, "league_id": { "description": "Stable league or competition identifier.", "type": [ "integer", "null" ] }, "league_name": { "description": "Display name of the league or competition.", "type": [ "string", "null" ] } }, "type": "object" }, "OddsSnapshot": { "additionalProperties": false, "description": "One market row from the event-and-period line-ID snapshot selected by the request, including margin-removed fair prices when supplied. In latest mode, every returned row for an event and period shares its greatest positive line_id; older off-board line IDs are excluded.", "properties": { "alt_line_id": { "description": "Identifier for an alternate spread or total line; null for the primary line.", "type": [ "integer", "null" ] }, "cutoff": { "description": "UTC time after which the market or line is no longer offered.", "type": [ "string", "null" ] }, "event_id": { "description": "Stable event identifier used across event, odds, line, result, and special-market calls.", "type": [ "integer", "null" ] }, "line": { "description": "Spread or total value from the selected side's perspective.", "type": [ "number", "null" ] }, "line_id": { "description": "Stable identifier for this market line snapshot.", "type": [ "integer", "null" ] }, "market": { "description": "Market family: moneyline, spread, totals, home_totals, or away_totals.", "type": [ "string", "null" ] }, "max_win": { "description": "Maximum win amount indicated for the line, when available.", "type": [ "number", "null" ] }, "odds0": { "description": "Decimal draw price; for totals-style markets, the middle outcome when supplied.", "type": [ "number", "null" ] }, "odds1": { "description": "Decimal home-side price; for totals-style markets, the over price.", "type": [ "number", "null" ] }, "odds2": { "description": "Decimal away-side price; for totals-style markets, the under price.", "type": [ "number", "null" ] }, "period": { "description": "Sport-specific period number; 0 represents the full event.", "type": [ "integer", "null" ] }, "red_cards_away": { "description": "Away-side red-card count at the snapshot time, when supplied.", "type": [ "integer", "null" ] }, "red_cards_home": { "description": "Home-side red-card count at the snapshot time, when supplied.", "type": [ "integer", "null" ] }, "score_away": { "description": "Away-side score for this period or snapshot, when supplied.", "type": [ "number", "null" ] }, "score_home": { "description": "Home-side score for this period or snapshot, when supplied.", "type": [ "number", "null" ] }, "status": { "description": "Numeric availability-state code for this line snapshot.", "type": [ "integer", "null" ] }, "timestamp": { "description": "UTC time at which this price snapshot was recorded.", "type": [ "string", "null" ] }, "todds0": { "description": "Margin-removed fair decimal draw price, or middle-outcome fair price when supplied.", "type": [ "number", "null" ] }, "todds1": { "description": "Margin-removed fair decimal home-side price; for totals-style markets, the over fair price.", "type": [ "number", "null" ] }, "todds2": { "description": "Margin-removed fair decimal away-side price; for totals-style markets, the under fair price.", "type": [ "number", "null" ] } }, "type": "object" }, "OpeningLine": { "additionalProperties": false, "description": "The earliest available price snapshot for one event market, period, and line.", "properties": { "alt_line_id": { "description": "Identifier for an alternate spread or total line; null for the primary line.", "type": [ "integer", "null" ] }, "cutoff": { "description": "UTC time after which the market or line is no longer offered.", "type": [ "string", "null" ] }, "event_id": { "description": "Stable event identifier used across event, odds, line, result, and special-market calls.", "type": [ "integer", "null" ] }, "line": { "description": "Spread or total value from the selected side's perspective.", "type": [ "number", "null" ] }, "line_id": { "description": "Stable identifier for this market line snapshot.", "type": [ "integer", "null" ] }, "market": { "description": "Market family: moneyline, spread, totals, home_totals, or away_totals.", "type": [ "string", "null" ] }, "max_win": { "description": "Maximum win amount indicated for the line, when available.", "type": [ "number", "null" ] }, "odds0": { "description": "Decimal draw price; for totals-style markets, the middle outcome when supplied.", "type": [ "number", "null" ] }, "odds1": { "description": "Decimal home-side price; for totals-style markets, the over price.", "type": [ "number", "null" ] }, "odds2": { "description": "Decimal away-side price; for totals-style markets, the under price.", "type": [ "number", "null" ] }, "period": { "description": "Sport-specific period number; 0 represents the full event.", "type": [ "integer", "null" ] }, "status": { "description": "Numeric availability-state code for this line snapshot.", "type": [ "integer", "null" ] }, "timestamp": { "description": "UTC time at which this price snapshot was recorded.", "type": [ "string", "null" ] }, "todds0": { "description": "Margin-removed fair decimal draw price, or middle-outcome fair price when supplied.", "type": [ "number", "null" ] }, "todds1": { "description": "Margin-removed fair decimal home-side price; for totals-style markets, the over fair price.", "type": [ "number", "null" ] }, "todds2": { "description": "Margin-removed fair decimal away-side price; for totals-style markets, the under fair price.", "type": [ "number", "null" ] } }, "type": "object" }, "Outright": { "additionalProperties": false, "description": "One contestant or outcome within an outright market not tied to a single event.", "properties": { "bet_type": { "description": "Market-type label for the special market.", "type": [ "string", "null" ] }, "category": { "description": "Grouping label for the special market or outright.", "type": [ "string", "null" ] }, "closing_available": { "description": "Whether a closing-line snapshot is currently available.", "type": [ "boolean", "integer", "null" ] }, "contestant_id": { "description": "Stable identifier for a contestant within a special market.", "type": [ "integer", "null" ] }, "contestant_name": { "description": "Display name of the contestant or outcome.", "type": [ "string", "null" ] }, "cutoff": { "description": "UTC time after which the market or line is no longer offered.", "type": [ "string", "null" ] }, "event_id": { "description": "Stable event identifier used across event, odds, line, result, and special-market calls.", "type": [ "integer", "null" ] }, "opening_available": { "description": "Whether an opening-line snapshot is currently available.", "type": [ "boolean", "integer", "null" ] }, "period": { "description": "Sport-specific period number; 0 represents the full event.", "type": [ "integer", "null" ] }, "runner_away": { "description": "Away runner or team display name.", "type": [ "string", "null" ] }, "runner_home": { "description": "Home runner or team display name.", "type": [ "string", "null" ] }, "special_id": { "description": "Stable identifier for the special market or outright.", "type": [ "integer", "null" ] }, "special_name": { "description": "Display name of the special market or outright.", "type": [ "string", "null" ] }, "units": { "description": "Units used by the special-market line, such as points or goals.", "type": [ "string", "null" ] } }, "type": "object" }, "PeriodDefinition": { "additionalProperties": false, "description": "One sport-specific period definition used by prices and results. Period 0 is the full event. Long and short display labels are separated by market: combined totals use totals_ fields, the home side uses home_totals_ fields, and the away side uses away_totals_ fields.", "properties": { "away_totals_description": { "description": "Full display label for the away_totals market in this period.", "type": [ "string", "null" ] }, "away_totals_short_description": { "description": "Compact display label for the away_totals market in this period.", "type": [ "string", "null" ] }, "description": { "description": "Full display label for this sport-specific period.", "type": [ "string", "null" ] }, "home_totals_description": { "description": "Full display label for the home_totals market in this period.", "type": [ "string", "null" ] }, "home_totals_short_description": { "description": "Compact display label for the home_totals market in this period.", "type": [ "string", "null" ] }, "moneyline_description": { "description": "Full moneyline label for this period.", "type": [ "string", "null" ] }, "moneyline_short_description": { "description": "Compact moneyline label for this period.", "type": [ "string", "null" ] }, "period": { "description": "Sport-specific period number; 0 represents the full event.", "type": [ "integer", "null" ] }, "short_description": { "description": "Compact display label for this sport-specific period.", "type": [ "string", "null" ] }, "spread_description": { "description": "Full spread label for this period.", "type": [ "string", "null" ] }, "spread_short_description": { "description": "Compact spread label for this period.", "type": [ "string", "null" ] }, "team_totals_description": { "deprecated": true, "description": "Deprecated compatibility field. It is not synthesized from side-specific labels and may be absent; use home_totals_description and away_totals_description.", "type": [ "string", "null" ] }, "team_totals_short_description": { "deprecated": true, "description": "Deprecated compatibility field. It is not synthesized from side-specific labels and may be absent; use home_totals_short_description and away_totals_short_description.", "type": [ "string", "null" ] }, "totals_description": { "description": "Full display label for the totals market in this period.", "type": [ "string", "null" ] }, "totals_short_description": { "description": "Compact display label for the totals market in this period.", "type": [ "string", "null" ] } }, "type": "object" }, "QuotaWindow": { "additionalProperties": false, "description": "One quota window. Remaining is the spendable balance after completed and active requests.", "properties": { "committed": { "format": "int64", "minimum": 0, "type": "integer" }, "in_flight": { "format": "int64", "minimum": 0, "type": "integer" }, "limit": { "format": "int64", "minimum": 0, "type": "integer" }, "remaining": { "format": "int64", "minimum": 0, "type": "integer" }, "resets_at": { "format": "date-time", "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "used": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "starts_at", "resets_at", "limit", "used", "in_flight", "committed", "remaining" ], "type": "object" }, "RecoveryEmailStatus": { "additionalProperties": false, "properties": { "verified": { "description": "Whether the exact current account mailbox has been explicitly authorized for future lost-key recovery.", "type": "boolean" }, "verified_at": { "description": "Server-recorded verification time, or null while lost-key recovery is disabled for this mailbox.", "format": "date-time", "readOnly": true, "type": [ "string", "null" ] } }, "required": [ "verified", "verified_at" ], "type": "object" }, "RecoveryEmailVerificationAccepted": { "additionalProperties": false, "properties": { "message": { "description": "Generic response that does not disclose whether verification was already complete, cooling down, or queued.", "type": "string" }, "status": { "const": "accepted", "type": "string" } }, "required": [ "status", "message" ], "type": "object" }, "RecoveryEmailVerificationRequest": { "additionalProperties": false, "properties": { "verification_token": { "description": "Single-use opaque bearer read from the same-origin /verify-recovery-email URL fragment and submitted only after explicit confirmation. Never put it in a query string, log, analytics event, or support ticket.", "pattern": "^emv_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$", "type": "string", "writeOnly": true } }, "required": [ "verification_token" ], "type": "object" }, "RecoveryEmailVerificationSuccess": { "additionalProperties": false, "properties": { "message": { "description": "Confirms recovery authority only; verification never returns or changes an API key.", "type": "string" }, "recovery_email_verified": { "const": true, "type": "boolean" }, "recovery_email_verified_at": { "format": "date-time", "readOnly": true, "type": "string" }, "status": { "const": "verified", "type": "string" } }, "required": [ "status", "recovery_email_verified", "recovery_email_verified_at", "message" ], "type": "object" }, "RequestGuidanceMessage": { "additionalProperties": false, "properties": { "body": { "maxLength": 1200, "minLength": 10, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "const": "support", "type": "string" }, "dismissed_at": { "format": "date-time", "type": "string" }, "endpoint": { "pattern": "^/v1/", "type": "string" }, "error_code": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "id": { "pattern": "^gdn_[0-9a-f]{32}$", "type": "string" }, "status": { "enum": [ "active", "dismissed", "withdrawn" ], "type": "string" }, "title": { "maxLength": 120, "minLength": 3, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "withdrawn_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "title", "body", "status", "created_by", "created_at", "updated_at" ], "type": "object" }, "RequestGuidanceResponse": { "additionalProperties": false, "properties": { "guidance": { "$ref": "#/components/schemas/RequestGuidanceMessage" } }, "required": [ "guidance" ], "type": "object" }, "RequestHealthDaily": { "additionalProperties": false, "properties": { "charged_failure_credits": { "format": "int64", "minimum": 0, "type": "integer" }, "charged_failures": { "format": "int64", "minimum": 0, "type": "integer" }, "day": { "format": "date", "type": "string" }, "failed_requests": { "format": "int64", "minimum": 0, "type": "integer" }, "requests": { "format": "int64", "minimum": 0, "type": "integer" }, "successful_requests": { "format": "int64", "minimum": 0, "type": "integer" }, "total_latency_ms": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "day", "requests", "successful_requests", "failed_requests", "charged_failures", "charged_failure_credits" ], "type": "object" }, "RequestHealthEvent": { "additionalProperties": false, "properties": { "api_key_id": { "pattern": "^key_[0-9a-f]{32}$", "type": "string" }, "api_key_name": { "type": "string" }, "api_key_prefix": { "type": "string" }, "charged_credits": { "format": "int64", "minimum": 0, "type": "integer" }, "endpoint": { "pattern": "^/v1/", "type": "string" }, "error_code": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" }, "guidance": { "$ref": "#/components/schemas/RequestHealthGuidance" }, "latency_ms": { "format": "int64", "minimum": 0, "type": "integer" }, "metered": { "type": "boolean" }, "occurred_at": { "format": "date-time", "type": "string" }, "request_id": { "pattern": "^req_[0-9a-f]{32}$", "type": "string" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" } }, "required": [ "request_id", "api_key_id", "endpoint", "status", "error_code", "charged_credits", "metered", "latency_ms", "occurred_at", "guidance" ], "type": "object" }, "RequestHealthGuidance": { "additionalProperties": false, "properties": { "actions": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "docs_path": { "pattern": "^/docs/", "type": "string" }, "explanation": { "type": "string" }, "responsibility": { "enum": [ "customer", "service", "unknown" ], "type": "string" }, "retryable": { "type": "boolean" }, "title": { "type": "string" } }, "required": [ "title", "explanation", "actions", "docs_path", "retryable", "responsibility" ], "type": "object" }, "RequestHealthIssue": { "additionalProperties": false, "properties": { "charged_credits": { "format": "int64", "minimum": 0, "type": "integer" }, "charged_failures": { "format": "int64", "minimum": 0, "type": "integer" }, "endpoint": { "pattern": "^/v1/", "type": "string" }, "error_code": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" }, "failures": { "format": "int64", "minimum": 0, "type": "integer" }, "guidance": { "$ref": "#/components/schemas/RequestHealthGuidance" }, "last_seen_at": { "format": "date-time", "type": "string" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" } }, "required": [ "endpoint", "status", "error_code", "failures", "charged_failures", "charged_credits", "last_seen_at", "guidance" ], "type": "object" }, "RequestHealthRange": { "additionalProperties": false, "properties": { "days": { "maximum": 90, "minimum": 1, "type": "integer" }, "detail_retention_days": { "const": 30, "type": "integer" }, "from": { "format": "date", "type": "string" }, "generated_at": { "format": "date-time", "type": "string" }, "to": { "format": "date", "type": "string" } }, "required": [ "days", "from", "to", "generated_at", "detail_retention_days" ], "type": "object" }, "RequestHealthReport": { "additionalProperties": false, "properties": { "daily": { "items": { "$ref": "#/components/schemas/RequestHealthDaily" }, "type": "array" }, "events": { "items": { "$ref": "#/components/schemas/RequestHealthEvent" }, "type": "array" }, "guidance_messages": { "items": { "$ref": "#/components/schemas/RequestGuidanceMessage" }, "type": "array" }, "issues": { "items": { "$ref": "#/components/schemas/RequestHealthIssue" }, "type": "array" }, "next_cursor": { "description": "Opaque cursor for the next detail page; empty when complete.", "type": "string" }, "range": { "$ref": "#/components/schemas/RequestHealthRange" }, "summary": { "$ref": "#/components/schemas/RequestHealthSummary" } }, "required": [ "range", "summary", "daily", "issues", "events", "guidance_messages", "next_cursor" ], "type": "object" }, "RequestHealthSummary": { "additionalProperties": false, "properties": { "average_latency_ms": { "minimum": 0, "type": "number" }, "charged_failure_credits": { "format": "int64", "minimum": 0, "type": "integer" }, "charged_failures": { "format": "int64", "minimum": 0, "type": "integer" }, "failed_requests": { "format": "int64", "minimum": 0, "type": "integer" }, "requests": { "format": "int64", "minimum": 0, "type": "integer" }, "success_rate": { "maximum": 1, "minimum": 0, "type": "number" }, "successful_requests": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "requests", "successful_requests", "failed_requests", "charged_failures", "charged_failure_credits", "success_rate", "average_latency_ms" ], "type": "object" }, "Result": { "additionalProperties": false, "description": "One current period-level result or settlement-state row for an event. Results can be corrected or re-settled and must be refreshed when revisions matter.", "properties": { "cancellation_reason": { "description": "Reason supplied when a result or settlement was cancelled; otherwise null.", "type": [ "string", "null" ] }, "period": { "description": "Sport-specific period number; 0 represents the full event.", "type": [ "integer", "null" ] }, "score_away": { "description": "Away-side score for this period or snapshot, when supplied.", "type": [ "number", "null" ] }, "score_home": { "description": "Home-side score for this period or snapshot, when supplied.", "type": [ "number", "null" ] }, "sets_away": { "description": "Away-side set count, when the sport uses sets.", "type": [ "number", "null" ] }, "sets_home": { "description": "Home-side set count, when the sport uses sets.", "type": [ "number", "null" ] }, "settlement_id": { "description": "Identifier for the current settlement revision, when supplied.", "type": [ "integer", "string", "null" ] }, "status": { "description": "Numeric settlement-state code supplied for this result row.", "type": [ "integer", "null" ] }, "timestamp": { "description": "UTC time of the latest result or settlement update.", "type": [ "string", "null" ] } }, "type": "object" }, "SpecialMarket": { "additionalProperties": false, "description": "One contestant or outcome discovered within an event-level special market or prop. In the v1 private beta, prices are retrieved one prop at a time through the prop-odds route.", "properties": { "bet_type": { "description": "Market-type label for the special market.", "type": [ "string", "null" ] }, "category": { "description": "Grouping label for the special market or outright.", "type": [ "string", "null" ] }, "closing_available": { "description": "Whether a closing-line snapshot is currently available.", "type": [ "boolean", "integer", "null" ] }, "contestant_id": { "description": "Stable identifier for a contestant within a special market.", "type": [ "integer", "null" ] }, "contestant_name": { "description": "Display name of the contestant or outcome.", "type": [ "string", "null" ] }, "cutoff": { "description": "UTC time after which the market or line is no longer offered.", "type": [ "string", "null" ] }, "event_id": { "description": "Stable event identifier used across event, odds, line, result, and special-market calls.", "type": [ "integer", "null" ] }, "opening_available": { "description": "Whether an opening-line snapshot is currently available.", "type": [ "boolean", "integer", "null" ] }, "period": { "description": "Sport-specific period number; 0 represents the full event.", "type": [ "integer", "null" ] }, "runner_away": { "description": "Away runner or team display name.", "type": [ "string", "null" ] }, "runner_home": { "description": "Home runner or team display name.", "type": [ "string", "null" ] }, "special_id": { "description": "Stable identifier for the special market or outright.", "type": [ "integer", "null" ] }, "special_name": { "description": "Display name of the special market or outright.", "type": [ "string", "null" ] }, "units": { "description": "Units used by the special-market line, such as points or goals.", "type": [ "string", "null" ] } }, "type": "object" }, "SpecialOddsSnapshot": { "additionalProperties": false, "description": "One timestamped contestant price for the requested special market or prop. In latest mode, exactly one row is returned per special_id and contestant_line_id, selected by that contestant's greatest positive line_id; handicap is a value on that row rather than part of its latest identity. The v1 private beta exposes one prop per request, not event-wide bulk prop prices.", "properties": { "contestant_line_id": { "description": "Identifier joining a contestant to one priced special-market line.", "type": [ "integer", "null" ] }, "handicap": { "description": "Handicap or threshold attached to this priced special-market outcome.", "type": [ "number", "null" ] }, "line_id": { "description": "Stable identifier for this market line snapshot.", "type": [ "integer", "null" ] }, "max_win": { "description": "Maximum win amount indicated for the line, when available.", "type": [ "number", "null" ] }, "odds": { "description": "Decimal price for this special-market contestant.", "type": [ "number", "null" ] }, "special_id": { "description": "Stable identifier for the special market or outright.", "type": [ "integer", "null" ] }, "timestamp": { "description": "UTC time at which this price snapshot was recorded.", "type": [ "string", "null" ] }, "todds": { "description": "Margin-removed fair decimal price for this special-market contestant.", "type": [ "number", "null" ] } }, "type": "object" }, "Sport": { "additionalProperties": false, "description": "One sport in the current SharpRelay catalog. Catalog responses can be served from the disposable response cache for roughly one hour; inspect X-Cache when evaluating freshness.", "properties": { "event_specials_count": { "description": "Number of event-level special markets currently represented for the sport, when supplied.", "type": [ "integer", "null" ] }, "has_offerings": { "description": "Whether the sport currently has available market offerings, encoded as a boolean or 0/1 flag.", "type": [ "boolean", "integer", "null" ] }, "leagues_specials_count": { "description": "Number of league-level special markets currently represented for the sport, when supplied.", "type": [ "integer", "null" ] }, "name": { "description": "Compatibility display name for the sport, when supplied.", "type": [ "string", "null" ] }, "sport_id": { "description": "Stable sport identifier used to query leagues, periods, events, and outrights.", "type": [ "integer", "null" ] }, "sport_name": { "description": "Canonical sport display name.", "type": [ "string", "null" ] }, "timestamp": { "description": "UTC time associated with the catalog availability snapshot, when supplied.", "type": [ "string", "null" ] } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "description": "Your API key, sent as `Authorization: Bearer YOUR_API_KEY`. Data endpoints require `data:read`; account endpoints require `account:manage`.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "## Overview\n\nPinnacle-sourced pre-game and in-play odds through the sports, leagues, events, markets, and history currently available from the source. Where present, responses can include live and historical prices, opening and closing lines, results, limits, and calculated margin-free odds. Coverage, fields, update cadence, and historical depth vary by sport, event, market, and source conditions; inspect the catalog and each response rather than assuming universal availability.\n\n## Private-beta data contract\n\nThe v1 private beta publishes **12 authenticated, read-only data routes**. Its prop and special-market scope is intentionally focused: discover event props, retrieve latest or available historical prices for one `prop_id` at a time, discover outrights, and use each outright's `special_id` as the prop identifier for its prices. Event-wide bulk prop-price retrieval and prop-specific opening, closing, results, and CLV operations are not exposed in the v1 private beta. They are not undocumented aliases; integrations must use only the routes present in this specification.\n\n## Data provenance\n\nSharpRelay is an independent delivery service for Pinnacle-sourced data. SharpRelay is not affiliated with, endorsed by, or sponsored by Pinnacle. Pinnacle is a trademark of its respective owner.\n\n## Authentication\n\nEvery request requires your API key as a Bearer token:\n\n```\ncurl -H \"Authorization: Bearer YOUR_API_KEY\" \"https://api.worksinprod.dev/v1/catalog/sports\"\n```\n\nAfter confirmed admission, a private one-time claim flow delivers the primary key. Completion time depends on successful access verification and service availability. Only the admission routes enabled for the selected service mode appear in this specification.\n\n## Key scopes\n\nKeys are least-privilege capabilities. Data endpoints require `data:read`; account inspection and key management require `account:manage`. Initial and support-issued primary keys receive both scopes. Rotation preserves the old key's exact scopes. Buyer-created additional keys default to `data:read` unless an account-managing key explicitly requests another valid non-empty subset.\n\n## Credential delivery and recovery\n\nDirect key rotation requires a fresh `Idempotency-Key` in the documented `rot_…` format. Keep the old key and nonce until the replacement is safely stored: their exact pair can retrieve an interrupted rotation response for 15 minutes without reactivating the old key. If every management key is lost, use the Turnstile-protected `/recover` page. A successful recovery revokes every old key and issues one full-management replacement. Initial-claim and account-recovery deliveries can be retried only with the exact same fragment credential, and only for their 10-minute delivery window.\n\n## Quota \u0026 metering\n\nFor ordinary routes, one SharpRelay credit includes up to **20 returned rows**. Larger responses use one additional credit per started 20-row block; empty responses cost one credit. Exact ordinary formula: `max(1, ceil(rows / 20))`. A `live=1` event-discovery request has a variable charge equal to the greater of its returned-row credits and bounded verified discovery/offer-check work, rounded through the same 20-unit blocks. Narrow sport, league, kickoff filters, and `limit` to control that work. `X-Credits-Cost` is the authoritative final charge. There are no bandwidth fees. Every plan has a plan-period allowance and an independent daily guard that resets at 00:00 UTC; a request must fit under both.\n\nEvery metered response carries usage headers. The original two limit headers\nremain compatibility aliases for the plan-period values:\n\n| Header | Meaning |\n|---|---|\n| `X-Credits-Limit` | Your plan's credit allowance per period |\n| `X-Credits-Remaining` | Credits left in the current period |\n| `X-Credits-Period-Limit` / `Remaining` / `Reset` | Exact plan-period entitlement state |\n| `X-Credits-Daily-Limit` / `Remaining` / `Reset` | UTC-daily guard state |\n| `X-Credits-Cost` | Credit cost of this request |\n| `X-Result-Rows` | Number of rows in this response |\n| `X-Result-Truncated` | Whether additional matching rows may exist beyond this response |\n| `X-Next-Cursor` | Opaque continuation for the next current-live event page. Absence means the scan is complete only when `X-Result-Truncated` is false |\n| `X-Cache` | `HIT` when served from disposable cache; `MISS` when that cache was available but the response was fetched from source (storage is not guaranteed); absent for non-eligible routes, `live=1` event discovery, disabled caching, or unavailable cache paths |\n| `X-SharpRelay-Origin` | Canonical SharpRelay API origin that owns the response |\n\nAuthentication, local validation, and pre-dispatch failures are not charged. A normalized backend error can cost one credit after data retrieval starts; the presence and value of `X-Credits-Cost` is authoritative. Metering headers are absent on unmetered errors.\n\n## Errors\n\nAll errors share one envelope: `{\"error\": {\"code\", \"message\", \"request_id\"}}`. Every response also carries the same opaque ID in `X-Request-Id` for support correlation. Backend messages, private headers, credentials, and implementation details are never forwarded.\n\n— SharpRelay", "title": "SharpRelay", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/.well-known/security.txt": { "get": { "description": "RFC 9116 security.txt document generated from the monitored deployment SECURITY_EMAIL and canonical public origin. The response advertises an expiry approximately 180 days ahead and is safe to cache for one day.", "operationId": "getSecurityContact", "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Canonical vulnerability-reporting contact", "headers": { "Cache-Control": { "description": "One-day public cache policy.", "schema": { "const": "public, max-age=86400", "type": "string" } }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [], "summary": "Private vulnerability-reporting coordinates", "tags": [ "Operations" ] } }, "/v1/account": { "get": { "description": "Requires account:manage. Returns your account status, current key scopes, current plan, real-time quota usage, and whether the current account mailbox is explicitly authorized for future lost-key recovery.", "operationId": "getAccount", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "api_key": { "properties": { "id": { "type": "string" }, "scopes": { "$ref": "#/components/schemas/APIKeyScopes" } }, "type": "object" }, "billing_managed": { "description": "Whether this account can open the hosted self-service billing portal.", "type": "boolean" }, "email": { "format": "email", "type": "string" }, "plan": { "properties": { "daily_credit_limit": { "description": "Independent guard resetting at 00:00 UTC.", "type": "integer" }, "name": { "type": "string" }, "rate_limit_rps": { "type": "integer" }, "slug": { "type": "string" } }, "type": "object" }, "quota": { "properties": { "billing_period": { "allOf": [ { "$ref": "#/components/schemas/QuotaWindow" } ], "description": "Compatibility field containing the current plan-period entitlement window." }, "committed": { "description": "Used plus active one-credit request reservations.", "type": "integer" }, "daily": { "$ref": "#/components/schemas/QuotaWindow" }, "limit": { "type": "integer" }, "period": { "enum": [ "day", "month" ], "type": "string" }, "remaining": { "type": "integer" }, "resets_at": { "format": "date-time", "type": "string" }, "used": { "type": "integer" } }, "type": "object" }, "recovery_email": { "$ref": "#/components/schemas/RecoveryEmailStatus" }, "status": { "type": "string" } }, "required": [ "email", "status", "billing_managed", "recovery_email", "api_key", "plan", "quota" ], "type": "object" } } }, "description": "Account and quota state", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key lacks account:manage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Your account, plan and live quota", "tags": [ "Account" ], "x-required-scope": "account:manage" } }, "/v1/account/guidance/{id}/dismiss": { "post": { "description": "Requires account:manage. Idempotently dismisses one active guidance message owned by the authenticated account. The operator audit row remains retained.", "operationId": "dismissRequestGuidance", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^gdn_[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestGuidanceResponse" } } }, "description": "Guidance dismissed or the existing dismissal replayed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key lacks account:manage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Guidance is not owned by this account or is unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Dismiss one support guidance message", "tags": [ "Account" ], "x-required-scope": "account:manage" } }, "/v1/account/keys": { "get": { "description": "Requires account:manage. Lists your keys redacted (prefix only), including each key's scopes, status, and last-use time.", "operationId": "listAPIKeys", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "api_keys": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "current": { "type": "boolean" }, "id": { "type": "string" }, "last_used_at": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "$ref": "#/components/schemas/APIKeyScopes" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" }, "max_keys": { "type": "integer" } }, "type": "object" } } }, "description": "Your redacted API keys and their scopes", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key lacks account:manage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List your API keys", "tags": [ "Account" ], "x-required-scope": "account:manage" }, "post": { "description": "Requires account:manage. Issues an extra key (maximum 5 active). The plaintext is returned exactly once. Omit scopes for the least-privilege data:read default.", "operationId": "createAPIKey", "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "maxLength": 100, "type": "string" }, "scopes": { "$ref": "#/components/schemas/APIKeyScopes" } }, "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "api_key": { "type": "string" }, "id": { "type": "string" }, "message": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "$ref": "#/components/schemas/APIKeyScopes" } }, "type": "object" } } }, "description": "The new API key and its scopes (plaintext shown once)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or empty scopes", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key lacks account:manage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Key limit reached", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Create an additional API key", "tags": [ "Account" ], "x-required-scope": "account:manage" } }, "/v1/account/keys/rotate": { "post": { "description": "Requires account:manage. Issues one replacement with the calling key's exact scopes and immediately revokes the calling key. Idempotency-Key is a caller-generated 32-byte random nonce encoded as unpadded base64url with the rot_ prefix. Retain the old API key and this nonce until the response is safely stored. If delivery is interrupted, retry with that exact pair before recovery_expires_at to retrieve the same replacement; this does not reactivate the old key.", "operationId": "rotateAPIKey", "parameters": [ { "description": "Fresh high-entropy rotation nonce: rot_ followed by the canonical unpadded base64url encoding of exactly 32 random bytes. Reuse only to recover the exact same interrupted rotation.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "pattern": "^rot_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRotationSuccess" } } }, "description": "Replacement created, or the same result retrieved during its 15-minute delivery-retry window", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Idempotency-Key is missing, duplicated, non-canonical, or not exactly 32 random bytes in the required format", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key lacks account:manage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "This key rotation was already started with a different Idempotency-Key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Key rotation or response delivery failed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authorization synchronization or rotation recovery is temporarily unavailable; retry with the exact same old key and Idempotency-Key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Rotate your API key", "tags": [ "Account" ], "x-required-scope": "account:manage" } }, "/v1/account/keys/{id}/revoke": { "post": { "description": "Requires account:manage. Immediately revokes one of your own keys by ID.", "operationId": "revokeAPIKey", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "const": "revoked", "type": "string" } }, "required": [ "id", "status" ], "type": "object" } } }, "description": "Key revoked", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key lacks account:manage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Key not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Revoke one of your keys", "tags": [ "Account" ], "x-required-scope": "account:manage" } }, "/v1/account/recovery-email/verification/resend": { "post": { "description": "Requires account:manage. Requests a single-use, 24-hour verification link for the current account mailbox. The operation accepts only an empty JSON object and is limited to one request per account every 10 minutes. Already-verified and cooling-down states intentionally return the same generic 202 response. This operation never returns a verification credential and never creates, reveals, revokes, replaces, or emails an API key.", "operationId": "resendRecoveryEmailVerification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "maxProperties": 0, "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryEmailVerificationAccepted" } } }, "description": "Generic accepted response; it does not disclose whether verification was required, cooling down, or queued", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request body is not exactly one empty JSON object", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key lacks account:manage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request body exceeds the configured limit", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The buyer pre-authentication per-IP limit was exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Recovery email verification is temporarily unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Request a recovery-email verification link", "tags": [ "Account" ], "x-required-scope": "account:manage" } }, "/v1/account/recovery-email/verify": { "post": { "description": "Public capability exchange used only by the first-party /verify-recovery-email page after explicit confirmation. It consumes one live, single-use, 24-hour emv_ bearer from the URL fragment, requires the exact email and pre-verification authority generation captured at issuance, and advances the mailbox's recovery-authority generation. Verification itself does not create, reveal, revoke, replace, or email any API key. The page strips query strings and never lets an invalid new fragment fall back to a stale tab credential. Treat the link as sensitive, never place it in a query string or log, and ignore it if you are not the buyer.", "operationId": "verifyRecoveryEmail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryEmailVerificationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryEmailVerificationSuccess" } } }, "description": "The current account mailbox is now authorized for future lost-key recovery", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The body or verification_token format is invalid", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The verification capability is invalid, expired, already consumed, or no longer matches the current account mailbox", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request body exceeds the configured limit", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The public per-IP rate limit was exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Recovery email verification is temporarily unavailable; retry with the exact same fragment bearer", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [], "summary": "Verify the account mailbox for lost-key recovery", "tags": [ "Account" ] } }, "/v1/account/recovery/claim": { "post": { "description": "Consumes one live rcv_ fragment credential for an eligible account whose current account mailbox and recovery-authority generation exactly match the snapshots captured at issuance. A mailbox reset or replacement permanently invalidates the older credential, including its interrupted-response replay. A successful recovery revokes every active API key and returns exactly one replacement with data:read and account:manage. The plaintext key is never emailed. If delivery is interrupted and authority is unchanged, the exact same credential returns the same replacement for 10 minutes. A different, expired, already used, stale-authority, or ineligible credential returns the same unavailable response.", "operationId": "claimAccountRecovery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRecoveryClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRecoverySuccess" } } }, "description": "All previous keys revoked and the sole full-management replacement returned, or its exact interrupted delivery recovered within 10 minutes", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The body or recovery_token format is invalid", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The recovery is invalid, expired, already used, or the account requires support", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request body exceeds the configured limit", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The public per-IP rate limit was exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Response delivery failed an integrity check; retry with the exact same credential", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authorization synchronization or account recovery is temporarily unavailable; retry with the exact same bearer", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [], "summary": "Replace all keys using a recovery link", "tags": [ "Account" ] } }, "/v1/account/recovery/request": { "post": { "description": "Public, Turnstile-protected recovery for a buyer who no longer has an account:manage key. After valid syntax and bot verification, the request path performs no customer lookup: every address receives the same fixed-size, record-bound encrypted durable intake and the same 202 response. A fenced worker resolves account existence, mailbox verification, eligibility, and the 30-minute per-authority-epoch cooldown asynchronously; under normal healthy load this internal handoff begins in well under one second. An eligible account receives one same-origin /recover#recovery_token=rcv_… fragment link only at its previously verified current account mailbox. The link is bound to that exact email and recovery-authority generation; delivery and claim fail closed after either changes. Never use this endpoint to test whether an account exists or whether a mailbox is verified, and do not treat 202 as proof of email delivery.", "operationId": "requestAccountRecovery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRecoveryRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRecoveryAccepted" } } }, "description": "Generic accepted response; it does not confirm account existence, mailbox-verification state, eligibility, cooldown state, or email delivery", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The email/body is invalid or the hostname/action-bound Turnstile challenge failed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request body exceeds the configured limit", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The public per-IP rate limit was exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Turnstile verification or public request protection is temporarily unavailable", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [], "summary": "Request lost-key account recovery", "tags": [ "Account" ] } }, "/v1/account/request-health": { "get": { "description": "Requires account:manage. Returns only the authenticated account's sanitized data-request outcomes: durable daily success/failure totals, normalized issue groups, up to 30 days of detailed failures, exact credits charged on each failure, automatic remediation, and active support guidance. Query values, bodies, credentials, IP addresses, and private-source details are never retained or returned.", "operationId": "getRequestHealth", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 30, "maximum": 90, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 30, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque newest-first detail cursor returned by the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 256, "type": "string" } }, { "description": "Exact documented data route.", "in": "query", "name": "endpoint", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "error_code", "required": false, "schema": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" } }, { "in": "query", "name": "api_key_id", "required": false, "schema": { "pattern": "^key_[0-9a-f]{32}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestHealthReport" } } }, "description": "Tenant-isolated Request Health report", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid range, filter, or cursor", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key lacks account:manage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request Health could not be loaded", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Inspect your request health", "tags": [ "Account" ], "x-required-scope": "account:manage" } }, "/v1/account/usage": { "get": { "description": "Requires account:manage. Returns your daily request/credit usage, zero-filled for charting.", "operationId": "getAccountUsage", "parameters": [ { "description": "Number of days to return (max 90).", "in": "query", "name": "days", "required": false, "schema": { "default": 30, "maximum": 90, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "from": { "format": "date", "type": "string" }, "to": { "format": "date", "type": "string" }, "usage": { "items": { "additionalProperties": false, "properties": { "credits": { "format": "int64", "minimum": 0, "type": "integer" }, "day": { "format": "date", "type": "string" }, "requests": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "day", "requests", "credits" ], "type": "object" }, "type": "array" } }, "required": [ "usage", "from", "to" ], "type": "object" } } }, "description": "Usage series", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "API key lacks account:manage", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Per-day usage series", "tags": [ "Account" ], "x-required-scope": "account:manage" } }, "/v1/analytics/clv": { "get": { "description": "Matches one supplied bet description to a corresponding event and available Pinnacle closing line, then returns the observed close, margin-removed fair close, expected win, and closing-line value. A 404 means no suitable event/close could be matched; it is not a zero-value result.", "operationId": "calculateClosingLineValue", "parameters": [ { "description": "Scheduled start time in UTC. Accepts YYYY-MM-DD, a UTC date-time, or RFC 3339.", "in": "query", "name": "starts", "required": true, "schema": { "type": "string" } }, { "description": "Sport identifier returned by /v1/catalog/sports.", "in": "query", "name": "sport_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Home runner or team name.", "in": "query", "name": "runner_home", "required": true, "schema": { "maxLength": 256, "minLength": 1, "type": "string" } }, { "description": "Away runner or team name.", "in": "query", "name": "runner_away", "required": true, "schema": { "maxLength": 256, "minLength": 1, "type": "string" } }, { "description": "Market type for the supplied bet.", "in": "query", "name": "market", "required": true, "schema": { "enum": [ "moneyline", "spread", "totals", "home_totals", "away_totals" ], "type": "string" } }, { "description": "Sport-specific period number; 0 is the full event.", "in": "query", "name": "period", "required": true, "schema": { "format": "int32", "minimum": 0, "type": "integer" } }, { "description": "Bet selection, consistent with the selected market.", "in": "query", "name": "selection", "required": true, "schema": { "enum": [ "home", "draw", "away", "over", "under" ], "type": "string" } }, { "description": "Stake amount; expected_win uses the same units.", "in": "query", "name": "bet_stake", "required": true, "schema": { "exclusiveMinimum": 0, "maximum": 1000000000000, "type": "number" } }, { "description": "Decimal price received for the bet.", "in": "query", "name": "bet_price", "required": true, "schema": { "exclusiveMinimum": 1, "maximum": 1000000, "type": "number" } }, { "description": "Spread or total from the selected side's perspective.", "in": "query", "name": "line", "required": false, "schema": { "maximum": 1000000000, "minimum": -1000000000, "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosingLineValue" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Calculate closing line value for one bet", "tags": [ "Analytics" ], "x-required-scope": "data:read" } }, "/v1/catalog/leagues": { "get": { "description": "Returns leagues currently discoverable for one sport, including display names, country codes, and groupings when supplied. Catalog membership can change as Pinnacle offerings change.", "operationId": "listLeagues", "parameters": [ { "description": "Sport identifier returned by /v1/catalog/sports.", "in": "query", "name": "sport_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/League" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List leagues for a sport", "tags": [ "Reference" ], "x-required-scope": "data:read" } }, "/v1/catalog/periods": { "get": { "description": "Returns the sport-specific period numbers and long/short display labels used by event odds, opening and closing lines, and results. Period 0 represents the full event. Fields beginning with totals_ describe the totals market, home_totals_ describes the home_totals market, and away_totals_ describes the away_totals market.", "operationId": "listPeriods", "parameters": [ { "description": "Sport identifier returned by /v1/catalog/sports.", "in": "query", "name": "sport_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PeriodDefinition" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List period definitions for a sport", "tags": [ "Reference" ], "x-required-scope": "data:read" } }, "/v1/catalog/sports": { "get": { "description": "Returns the current catalog of sports discoverable through SharpRelay, together with available offering indicators. This API catalog supersedes a dated marketing snapshot for integration decisions, but it can be served from the disposable response cache for roughly one hour. Inspect X-Cache and refresh it on a slow timer rather than assuming zero-staleness.", "operationId": "listSports", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Sport" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List sports", "tags": [ "Reference" ], "x-required-scope": "data:read" } }, "/v1/claim": { "post": { "description": "Consumes an initial claim issued after private-beta activation or paid checkout and reveals its API key. The normal browser handoff uses a server-bounded host-only HttpOnly claim cookie on the first-party /claim page. A private-beta handoff remains usable only through its original claim deadline, so closing the claim page does not forfeit an unrevealed key; after first delivery the cookie is reduced to the sealed-response retry window. Cookie-authenticated requests require exact same-origin browser metadata and JSON content. Where a paid-mode email fallback is available, its opaque claim_token remains only in the URL fragment and is submitted from that page. Retry a 202 response after the Retry-After interval. If a successful response is interrupted, the exact same claim credential returns the same key for at most 10 minutes and never beyond the original claim expiry. A different credential or a later retry returns 410. Never log, persist, or send either claim credential to third parties.", "operationId": "claimInitialAPIKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimSuccess" } } }, "description": "Claim consumed and plaintext API key returned, or the same response retrieved during the 10-minute delivery-retry window.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPending" } } }, "description": "Access is confirmed but secure provisioning has not finished; retry after the advertised delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The JSON body or claim credential is invalid.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The account associated with this claim is not active.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The claim is invalid, expired, outside its post-consumption delivery window, or bound to an inactive key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request body exceeds the configured limit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The public endpoint rate limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Public request protection is temporarily unavailable.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [], "summary": "Claim the API key issued after admission", "tags": [ "Commercial" ] } }, "/v1/events": { "get": { "description": "Returns events with optional event, parent, sport, league, kickoff-window, line-availability, and incremental-update filters. Ordinary discovery is future pre-game by default. When starts_from, event_id, and parent_id are omitted, SharpRelay applies a request-current UTC lower bound. An explicitly supplied starts_from at or after the request boundary remains locally enforced as a future lower bound; only a genuinely past starts_from is the historical-discovery opt-in. A supplied starts_to is also enforced locally for future discovery: timestamp values are inclusive and date-only values include the complete UTC day. Eligible ordinary rows must remain pre-game, inside that owned window, and strictly future at final validation. Exact event_id and parent_id lookups are lifecycle-specific and may return past records where consistent with the selected live mode. The since filter describes fixture metadata changes and does not by itself opt into past kickoffs. With live=1, SharpRelay freshly reads the complete bounded candidate boundary for the selected filters on every request, orders candidates deterministically, and applies bounded per-page price verification; live discovery is not response-cached. A returned row must have live_status=1, its latest odds response must be bound to the requested event, and at least one row in that latest snapshot must have status=1 with a parseable cutoff strictly after final validation. Expiry is rechecked at that final validation boundary. There is no arbitrary odds-update-age or kickoff-age rule: a legitimately long-running event remains eligible while those current-offer conditions hold. Without starts_from, live discovery applies no minimum kickoff and uses a conservative whole-second source ceiling that covers the request instant; local offer validation owns the exact boundary. Provide starts_from only to narrow the candidate window. In live mode, omit since when you need a complete current snapshot because since filters fixture-metadata changes rather than price changes. SharpRelay applies limit after verification, defaults it to 100, and rejects values above 1,000. Each broad live scan reads the complete bounded boundary of up to 1,000 candidate fixtures, then verifies at most max(4, 2 × limit) candidates per page, capped at 512; an exact event_id lookup verifies only that event. A page can therefore contain fewer rows than limit. The live=1 charge is variable: it is the greater of returned-row credits and bounded verified discovery/offer-check work, rounded through the same 20-unit blocks. Narrow filters and limit to control that work, and treat X-Credits-Cost as authoritative. When X-Next-Cursor is present, repeat the original filters and pass that opaque value within five minutes; continue even when an intermediate page is empty. The scan is complete only when X-Next-Cursor is absent and X-Result-Truncated is false. X-Result-Truncated without X-Next-Cursor means the 1,000-candidate boundary was itself truncated and the client must narrow the sport, league, or kickoff window.", "operationId": "listEvents", "parameters": [ { "description": "Return one lifecycle-specific event when available, including a past event.", "in": "query", "name": "event_id", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Return lifecycle-specific child fixtures for this parent event, including past records.", "in": "query", "name": "parent_id", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Filter by sport.", "in": "query", "name": "sport_id", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Filter by league.", "in": "query", "name": "league_id", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Earliest kickoff, in UTC. For ordinary pre-game discovery, omission means request-current UTC and therefore future events only. A supplied value at or after the request boundary remains locally enforced as a future lower bound; only a genuinely past value opts into historical discovery. With live=1, omission applies no minimum kickoff; provide a value only to narrow the live candidate window. Accepts YYYY-MM-DD or a whole-second UTC date-time using a space or T separator, with an optional trailing Z.", "in": "query", "name": "starts_from", "required": false, "schema": { "type": "string" } }, { "description": "Latest kickoff, in UTC. For future discovery this bound is enforced locally after source validation: timestamps are inclusive and date-only values include that full UTC day. When starts_from is omitted for ordinary discovery, this bound must still leave a non-empty future window. Accepts YYYY-MM-DD or a whole-second UTC date-time using a space or T separator, with an optional trailing Z.", "in": "query", "name": "starts_to", "required": false, "schema": { "type": "string" } }, { "description": "Return events added or changed after this UTC value. This filters metadata update time and does not by itself include past kickoffs. Accepts YYYY-MM-DD, a UTC date-time, or RFC 3339.", "in": "query", "name": "since", "required": false, "schema": { "type": "string" } }, { "description": "0 for future pre-game discovery by default; 1 for currently offered in-play events. live=1 is not response-cached: every request reads the complete bounded candidate boundary, requires live_status=1, binds latest odds to the requested event, and requires at least one latest row with status=1 and a parseable cutoff strictly after final validation. Expiry is rechecked at that boundary. Fully suspended, expired, settled, and historical-only records are excluded. No update-age or kickoff-age floor is invented; without starts_from, live discovery applies no minimum kickoff and uses a conservative whole-second source ceiling that covers the request instant while local validation owns the exact offer boundary.", "in": "query", "name": "live", "required": false, "schema": { "default": 0, "enum": [ 0, 1 ], "format": "int32", "type": "integer" } }, { "description": "Set to 1 to require closing-line data.", "in": "query", "name": "closing_available", "required": false, "schema": { "enum": [ 0, 1 ], "format": "int32", "type": "integer" } }, { "description": "Set to 1 to require opening-line data.", "in": "query", "name": "opening_available", "required": false, "schema": { "enum": [ 0, 1 ], "format": "int32", "type": "integer" } }, { "description": "Maximum rows. Defaults to 100 and cannot exceed 1,000.", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "Opaque X-Next-Cursor value from the preceding live=1 page. It is filter-bound, snapshot-window-bound, and valid for five minutes. Do not decode or modify it.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 1024, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Event" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List pre-game or currently offered live events", "tags": [ "Events" ], "x-required-scope": "data:read" } }, "/v1/events/{event_id}/lines/closing": { "get": { "description": "Returns the latest available Pinnacle-sourced closing price for each requested market, period, and line, with result fields when available. Closing data can be corrected; refresh this resource when revisions matter rather than treating one response as immutable.", "operationId": "getClosingLines", "parameters": [ { "description": "Event identifier returned by /v1/events.", "in": "path", "name": "event_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Sport-specific period number; 0 is the full event.", "in": "query", "name": "period", "required": false, "schema": { "format": "int32", "minimum": 0, "type": "integer" } }, { "description": "Filter by market type.", "in": "query", "name": "market", "required": false, "schema": { "enum": [ "moneyline", "spread", "totals", "home_totals", "away_totals" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ClosingLine" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Closing lines", "tags": [ "Odds" ], "x-required-scope": "data:read" } }, "/v1/events/{event_id}/lines/opening": { "get": { "description": "Returns the earliest available Pinnacle-sourced price for each requested market, period, and line.", "operationId": "getOpeningLines", "parameters": [ { "description": "Event identifier returned by /v1/events.", "in": "path", "name": "event_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Sport-specific period number; 0 is the full event.", "in": "query", "name": "period", "required": false, "schema": { "format": "int32", "minimum": 0, "type": "integer" } }, { "description": "Filter by market type.", "in": "query", "name": "market", "required": false, "schema": { "enum": [ "moneyline", "spread", "totals", "home_totals", "away_totals" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/OpeningLine" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Opening lines", "tags": [ "Odds" ], "x-required-scope": "data:read" } }, "/v1/events/{event_id}/odds": { "get": { "description": "Returns the current Pinnacle-sourced line-ID snapshot for each matching event and period by default. Latest mode selects the greatest positive line_id for an event and period, returns every primary and alternate market row present at that winning snapshot, and excludes rows from older off-board line IDs. Set full_history=1 to request available matching history, or use since by itself to select incremental historical snapshots. Do not combine since with full_history=0; that contradictory query is rejected. Historical depth varies, so inspect X-Result-Truncated and never assume a response contains a complete event timeline. Alternate lines are included by default; set main_lines_only=1 to exclude them. odds* fields are decimal prices; todds* fields are margin-removed fair prices when supplied.", "operationId": "listOdds", "parameters": [ { "description": "Event identifier returned by /v1/events.", "in": "path", "name": "event_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Sport-specific period number; 0 is the full event.", "in": "query", "name": "period", "required": false, "schema": { "format": "int32", "minimum": 0, "type": "integer" } }, { "description": "Filter by market type.", "in": "query", "name": "market", "required": false, "schema": { "enum": [ "moneyline", "spread", "totals", "home_totals", "away_totals" ], "type": "string" } }, { "description": "Spread or total from the selected side's perspective.", "in": "query", "name": "line", "required": false, "schema": { "maximum": 1000000000, "minimum": -1000000000, "type": "number" } }, { "description": "Return historical snapshots recorded after this UTC value; supplying since selects incremental-history mode. Do not combine it with full_history=0. Accepts YYYY-MM-DD, a UTC date-time, or RFC 3339.", "in": "query", "name": "since", "required": false, "schema": { "type": "string" } }, { "description": "Omit for the current greatest-line_id snapshot when since is absent; 0 explicitly selects that latest mode; 1 requests available matching history. Supplying since also selects history, so since cannot be combined with full_history=0. When requesting history, inspect X-Result-Truncated and do not assume the timeline is complete.", "in": "query", "name": "full_history", "required": false, "schema": { "enum": [ 0, 1 ], "format": "int32", "type": "integer" } }, { "description": "Set to 1 to exclude alternate spread and total lines.", "in": "query", "name": "main_lines_only", "required": false, "schema": { "default": 0, "enum": [ 0, 1 ], "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/OddsSnapshot" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List odds for an event", "tags": [ "Odds" ], "x-required-scope": "data:read" } }, "/v1/events/{event_id}/props": { "get": { "description": "Discovers contestant and market metadata for props and other special markets attached to one event. Use each returned special_id as the prop_id on the prop-odds route to retrieve latest or available historical prices one prop at a time. Opening/closing filters require the corresponding price snapshots to be available. This v1 private-beta discovery route does not return event-wide bulk prop prices; prop-specific opening, closing, results, and CLV operations are not exposed in the 12-route beta contract.", "operationId": "listEventSpecialMarkets", "parameters": [ { "description": "Event identifier returned by /v1/events.", "in": "path", "name": "event_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Set to 1 to require opening prices.", "in": "query", "name": "opening_available", "required": false, "schema": { "enum": [ 0, 1 ], "format": "int32", "type": "integer" } }, { "description": "Set to 1 to require closing prices.", "in": "query", "name": "closing_available", "required": false, "schema": { "enum": [ 0, 1 ], "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SpecialMarket" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List event special markets and props", "tags": [ "Special markets" ], "x-required-scope": "data:read" } }, "/v1/events/{event_id}/results": { "get": { "description": "Returns current period-level scores and settlement, cancellation, or re-settlement state for one event. Results can be corrected or re-settled; refresh this resource when revisions matter rather than treating one response as immutable.", "operationId": "getResults", "parameters": [ { "description": "Event identifier returned by /v1/events.", "in": "path", "name": "event_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Result" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Get scores and settlement state", "tags": [ "Results" ], "x-required-scope": "data:read" } }, "/v1/outrights": { "get": { "description": "Discovers tournament and competition markets that are not tied to one event in the v1 private beta. Use each returned special_id as the prop_id with /v1/props/{prop_id}/odds to retrieve latest or available historical prices one market at a time.", "operationId": "listOutrights", "parameters": [ { "description": "Sport identifier returned by /v1/catalog/sports.", "in": "query", "name": "sport_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Filter by competition.", "in": "query", "name": "league_id", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Case-insensitive market-name substring.", "in": "query", "name": "special_name", "required": false, "schema": { "maxLength": 256, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Outright" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List outright markets", "tags": [ "Outrights" ], "x-required-scope": "data:read" } }, "/v1/private-beta/activate": { "post": { "description": "Fresh redemption consumes a single-use fragment-delivered invitation after current policy acceptance, security verification, and admission checks. A browser-generated, tab-local retry nonce binds an exact post-commit retry to the original browser. That retry revalidates the stored immutable acceptance and retained claim-key candidate, intentionally surviving retry-IP, active consent-key, current-policy, and admission-gate changes because it can recover only the already-created claim. A redeemed invitation alone or with a different nonce cannot recover the handoff or create access. On success, the browser receives an HttpOnly claim handoff; no API key or claim bearer is returned in JSON.", "operationId": "activatePrivateBeta", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "accepted_policies": { "const": true, "type": "boolean" }, "activation_nonce": { "type": "string", "writeOnly": true }, "authorized_to_bind": { "const": true, "type": "boolean" }, "business_use_only": { "const": true, "type": "boolean" }, "invite_token": { "type": "string", "writeOnly": true }, "policy_version": { "type": "string" }, "turnstile_token": { "type": "string", "writeOnly": true } }, "required": [ "invite_token", "activation_nonce", "turnstile_token", "accepted_policies", "policy_version", "authorized_to_bind", "business_use_only" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Access active; continue to the one-time claim page" }, "400": { "description": "Invalid verification or policy acceptance" }, "409": { "description": "Fresh admission is paused or capacity is unavailable" }, "410": { "description": "Invitation is invalid, expired, revoked, or no longer replayable" }, "503": { "description": "Activation is temporarily unavailable" } }, "summary": "Activate a verified private-beta invitation", "tags": [ "Private beta" ] } }, "/v1/props/{prop_id}/odds": { "get": { "description": "Returns contestant prices and margin-removed fair prices for exactly one prop or special market identified by prop_id. Latest mode returns exactly one most-recent row per special_id and contestant_line_id, selected by that contestant's greatest positive line_id; handicap is a value on the winning row rather than part of its latest identity. full_history=1 requests available matching history. Historical depth varies, so inspect X-Result-Truncated and never assume a response contains a complete timeline. Event-wide bulk prop prices are not exposed in the v1 private beta.", "operationId": "listSpecialMarketOdds", "parameters": [ { "description": "The special_id returned by an event prop or outright response.", "in": "path", "name": "prop_id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "0 for one greatest-line_id row per special_id and contestant_line_id; 1 requests available matching history. Handicap is not a separate latest identity. When requesting history, inspect X-Result-Truncated and do not assume the timeline is complete.", "in": "query", "name": "full_history", "required": false, "schema": { "default": 0, "enum": [ 0, 1 ], "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SpecialOddsSnapshot" }, "type": "array" } } }, "description": "Successful validated data response.", "headers": { "X-Cache": { "$ref": "#/components/headers/X-Cache" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Next-Cursor": { "$ref": "#/components/headers/X-Next-Cursor" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-Result-Truncated": { "$ref": "#/components/headers/X-Result-Truncated" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported request parameters.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The key lacks data:read, or the account or plan cannot access data.", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource or result does not exist.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The IP/customer rate limit or a daily/plan-period credit limit was exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unexpected internal gateway error.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A backend data response failed transport, status, schema, size, or integrity validation.", "headers": { "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A required gateway dependency, request coordinator, data-capacity pool, or accounting service is temporarily unavailable.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-Credits-Cost": { "$ref": "#/components/headers/X-Credits-Cost" }, "X-Credits-Daily-Limit": { "$ref": "#/components/headers/X-Credits-Daily-Limit" }, "X-Credits-Daily-Remaining": { "$ref": "#/components/headers/X-Credits-Daily-Remaining" }, "X-Credits-Daily-Reset": { "$ref": "#/components/headers/X-Credits-Daily-Reset" }, "X-Credits-Limit": { "$ref": "#/components/headers/X-Credits-Limit" }, "X-Credits-Period-Limit": { "$ref": "#/components/headers/X-Credits-Period-Limit" }, "X-Credits-Period-Remaining": { "$ref": "#/components/headers/X-Credits-Period-Remaining" }, "X-Credits-Period-Reset": { "$ref": "#/components/headers/X-Credits-Period-Reset" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Result-Rows": { "$ref": "#/components/headers/X-Result-Rows" }, "X-SharpRelay-Origin": { "$ref": "#/components/headers/X-SharpRelay-Origin" } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List special-market and prop prices", "tags": [ "Special markets" ], "x-required-scope": "data:read" } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api.worksinprod.dev" } ], "tags": [ { "description": "Sports, leagues, and sport-specific period definitions.", "name": "Reference" }, { "description": "Pre-game and in-play events with bounded filtering and incremental polling.", "name": "Events" }, { "description": "Pinnacle-sourced prices, opening lines, and closing lines.", "name": "Odds" }, { "description": "Scores, settlements, cancellations, and re-settlements.", "name": "Results" }, { "description": "Closing-line-value analysis for one supplied bet.", "name": "Analytics" }, { "description": "Private-beta prop discovery and per-prop latest or available historical prices. Event-wide bulk prop prices and prop-specific opening, closing, results, and CLV are outside the v1 beta contract.", "name": "Special markets" }, { "description": "Tournament and competition market discovery, with prices retrieved one returned special_id at a time through the prop-odds route.", "name": "Outrights" }, { "description": "Authenticated account, quota, billing, and API-key management.", "name": "Account" }, { "description": "Mode-selected admission, paid checkout, initial-claim delivery, and recovery-capability exchanges.", "name": "Commercial" }, { "description": "Public security contact metadata.", "name": "Operations" } ] }