{ "openapi": "3.0.3", "info": { "title": "Realtime Sports API", "version": "1.0.0", "description": "Live scores, play-by-play, box scores, schedules, teams, athletes, injuries, news and betting odds\nfor NFL, college football, NBA, men's college basketball, MLB, NHL and 23 soccer competitions, under one\nschema and one API key. Push delivery is available over webhooks and WebSocket.\n\n**Freshness:** data is aggregated from public sources and is typically 20-30 seconds behind live play\n(our pipeline adds about 1 second after our source). Not suitable for in-play betting that needs\nsub-second data. There is no SLA.\n\n**Auth:** send `Authorization: Bearer ` (or `X-API-Key: `). Get a free key at\nhttps://www.realtimesportsapi.com/signup.\n\n**Quotas:** monthly call quotas per plan (Free 125/month, 1,000 in the first 30 days; Starter 10,000;\nGrowth 25,000; Pro 50,000; Scale 500,000). Every successful REST call counts as one call. When the quota is\nexhausted the API returns HTTP 429 with a `Retry-After` header. Per-second rates also apply\n(Free 1/s, Starter 5/s, Growth 10/s, Pro 20/s, Scale 100/s). Remaining monthly quota is reported in\n`meta.rateLimit` on most responses.", "termsOfService": "https://www.realtimesportsapi.com/terms", "contact": { "name": "Realtime Sports API support", "email": "austin@elcodev.com", "url": "https://www.realtimesportsapi.com" }, "license": { "name": "Proprietary", "url": "https://www.realtimesportsapi.com/terms" } }, "externalDocs": { "description": "Guides, WebSocket and webhook docs", "url": "https://www.realtimesportsapi.com/docs" }, "servers": [ { "url": "https://www.realtimesportsapi.com/api/v1", "description": "Production" } ], "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "tags": [ { "name": "Sports", "description": "Sports and leagues" }, { "name": "Events", "description": "Games: lists, live games, single game, box score, win probability, game rosters" }, { "name": "Plays", "description": "Play-by-play and penalties" }, { "name": "Odds", "description": "Current betting lines and line history (single source book)" }, { "name": "Teams", "description": "Teams, rosters and depth charts" }, { "name": "Athletes", "description": "Athletes, search, game logs and availability history" }, { "name": "Seasons", "description": "Seasons, season types, groups, weeks, schedules and tournaments" }, { "name": "Injuries & Availability", "description": "Injury reports and normalized player availability" }, { "name": "News", "description": "League news and the news archive" }, { "name": "Transactions", "description": "Roster transactions" }, { "name": "Webhooks", "description": "Manage webhook subscriptions (paid plans). These management calls do not count toward your quota; deliveries do." }, { "name": "WebSocket", "description": "Get a short-lived token for the WebSocket push stream" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key from the dashboard: `Authorization: Bearer `. Keys are opaque strings, not JWTs." }, "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative to the Authorization header (useful behind proxies that strip Authorization)." } }, "responses": { "Unauthorized": { "description": "Missing, malformed, unknown or expired API key (codes: MISSING_TOKEN, USER_NOT_FOUND, TRIAL_EXPIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimitExceeded": { "description": "Too many requests: either the monthly quota is exhausted (code RATE_LIMIT_EXCEEDED; upgrade or enable overage) or the plan's per-second rate was exceeded (code RATE_LIMIT_PER_SECOND; Free 1/s, Starter 5/s, Growth 10/s, Pro 20/s, Scale 100/s). Wait for `Retry-After` seconds.", "headers": { "Retry-After": { "description": "Seconds until you may retry.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Unexpected error. Safe to retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "MISSING_TOKEN" }, "message": { "type": "string", "example": "Authorization required" }, "hint": { "type": "string", "example": "Use Authorization: Bearer or X-API-Key: ." } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, "RateLimit": { "type": "object", "properties": { "limit": { "type": "integer", "example": 10000, "description": "Calls included this month." }, "remaining": { "type": "integer", "example": 9876, "description": "Calls remaining this month (approximate; updated asynchronously)." }, "reset": { "type": "integer", "example": 1767225600000, "description": "Quota reset time, Unix epoch milliseconds." } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 180 }, "totalPages": { "type": "integer", "example": 8 }, "pageCount": { "type": "integer", "example": 8, "description": "Present on some endpoints instead of totalPages." }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { "type": "boolean", "example": false } } }, "Sport": { "type": "object", "properties": { "id": { "type": "string", "example": "20" }, "name": { "type": "string", "example": "Football" }, "slug": { "type": "string", "example": "football" }, "displayName": { "type": "string", "example": "Football" } } }, "League": { "type": "object", "properties": { "id": { "type": "string", "example": "28" }, "name": { "type": "string", "example": "National Football League" }, "slug": { "type": "string", "example": "nfl" }, "abbreviation": { "type": "string", "example": "NFL" }, "shortName": { "type": "string", "example": "NFL" }, "isTournament": { "type": "boolean", "example": false }, "currentSeason": { "type": "integer", "example": 2026 } } }, "LeagueDetail": { "type": "object", "properties": { "id": { "type": "string", "example": "28" }, "name": { "type": "string", "example": "National Football League" }, "displayName": { "type": "string", "example": "National Football League" }, "abbreviation": { "type": "string", "example": "NFL" }, "shortName": { "type": "string", "example": "NFL" }, "slug": { "type": "string", "example": "nfl" }, "currentSeason": { "type": "object", "properties": { "year": { "type": "integer", "example": 2026 }, "type": { "type": "string", "example": "Regular Season" }, "startDate": { "type": "string" }, "endDate": { "type": "string" } } }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Relative URLs of related endpoints." } } }, "EventTeam": { "type": "object", "properties": { "id": { "type": "string", "example": "12" }, "name": { "type": "string", "example": "Kansas City Chiefs" }, "abbreviation": { "type": "string", "example": "KC" }, "logo": { "type": "string", "nullable": true, "description": "Team logo URL when available." }, "color": { "type": "string", "example": "e31837" }, "alternateColor": { "type": "string", "example": "ffb612" }, "winner": { "type": "boolean", "example": false }, "record": { "type": "string", "example": "3-1" }, "score": { "type": "integer", "example": 14 } } }, "EventStatus": { "type": "object", "properties": { "state": { "type": "string", "example": "in", "enum": [ "pre", "in", "post" ] }, "completed": { "type": "boolean", "example": false }, "period": { "type": "integer", "example": 2 }, "clock": { "type": "string", "example": "5:23" }, "detail": { "type": "string", "example": "5:23 - 2nd Quarter" }, "halftime": { "type": "boolean", "example": false }, "firstHalfEnded": { "type": "boolean", "example": false } } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "example": "401772982" }, "uid": { "type": "string" }, "name": { "type": "string", "example": "Kansas City Chiefs at Baltimore Ravens" }, "shortName": { "type": "string", "example": "KC @ BAL" }, "date": { "type": "string", "example": "2026-10-04T17:00Z", "format": "date-time" }, "status": { "$ref": "#/components/schemas/EventStatus" }, "homeTeam": { "$ref": "#/components/schemas/EventTeam" }, "awayTeam": { "$ref": "#/components/schemas/EventTeam" }, "competition": { "type": "object", "properties": { "attendance": { "type": "integer" }, "neutralSite": { "type": "boolean" }, "conferenceCompetition": { "type": "boolean" }, "divisionCompetition": { "type": "boolean" }, "playByPlayAvailable": { "type": "boolean" }, "highlightsAvailable": { "type": "boolean" } } }, "venue": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "indoor": { "type": "boolean" }, "grass": { "type": "boolean" } }, "nullable": true }, "notes": { "type": "array", "items": { "type": "string" } }, "season": { "type": "object", "properties": { "year": { "type": "integer", "example": 2026 }, "displayName": { "type": "string", "example": "2026" }, "type": { "type": "object", "properties": { "id": { "type": "string", "example": "2" }, "name": { "type": "string", "example": "Regular Season" }, "abbreviation": { "type": "string", "example": "reg" } } }, "week": { "type": "object", "properties": { "number": { "type": "integer", "example": 5 }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "text": { "type": "string", "example": "Week 5" } } } } }, "broadcasts": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "example": "CBS" }, "type": { "type": "string", "example": "TV" } } } }, "officials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fullName": { "type": "string" }, "displayName": { "type": "string" }, "order": { "type": "integer" }, "position": { "type": "string" } } } }, "odds": { "allOf": [ { "$ref": "#/components/schemas/Odds" } ], "description": "Present only when includeOdds=true and odds are available." } } }, "PlayAthlete": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string" }, "shortName": { "type": "string" }, "position": { "type": "string", "example": "QB" }, "team": { "type": "object", "properties": { "id": { "type": "string" } } }, "role": { "type": "string", "example": "passer" }, "type": { "type": "string", "example": "passer" }, "order": { "type": "integer" } } }, "Play": { "type": "object", "properties": { "id": { "type": "string", "example": "4017729821234" }, "sequenceNumber": { "type": "string" }, "text": { "type": "string", "example": "P.Mahomes pass short right to T.Kelce for 12 yards" }, "shortText": { "type": "string" }, "alternativeText": { "type": "string" }, "type": { "type": "object", "properties": { "id": { "type": "string", "example": "24" }, "text": { "type": "string", "example": "Pass Reception" }, "abbreviation": { "type": "string", "example": "REC" } } }, "period": { "type": "integer", "example": 2 }, "clock": { "type": "object", "properties": { "value": { "type": "number", "example": 323 }, "displayValue": { "type": "string", "example": "5:23" } } }, "wallClock": { "type": "string", "format": "date-time" }, "homeScore": { "type": "integer", "example": 14 }, "awayScore": { "type": "integer", "example": 10 }, "scoringPlay": { "type": "boolean", "example": false }, "scoreValue": { "type": "integer", "example": 0 }, "scoringType": { "type": "string" }, "situation": { "type": "object", "properties": { "down": { "type": "integer" }, "distance": { "type": "integer" }, "yardLine": { "type": "integer" }, "yardsToEndzone": { "type": "integer" }, "downDistanceText": { "type": "string" }, "possessionText": { "type": "string" } }, "nullable": true }, "endSituation": { "type": "object", "properties": { "down": { "type": "integer" }, "distance": { "type": "integer" }, "yardLine": { "type": "integer" }, "yardsToEndzone": { "type": "integer" } }, "nullable": true }, "yardsGained": { "type": "integer", "example": 12 }, "teamId": { "type": "string", "example": "12" }, "athletes": { "type": "array", "items": { "$ref": "#/components/schemas/PlayAthlete" } }, "priority": { "type": "boolean" }, "modified": { "type": "string" } } }, "Odds": { "type": "object", "properties": { "provider": { "type": "string", "description": "Name of the single source book." }, "spread": { "type": "object", "properties": { "line": { "type": "number", "example": -3.5 }, "home": { "type": "number", "example": -110 }, "away": { "type": "number", "example": -110 } }, "nullable": true }, "moneyline": { "type": "object", "properties": { "home": { "type": "number", "example": -180 }, "away": { "type": "number", "example": 150 } }, "nullable": true }, "overUnder": { "type": "object", "properties": { "total": { "type": "number", "example": 48.5 }, "over": { "type": "number", "example": -110 }, "under": { "type": "number", "example": -110 } }, "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OddsHistoryEntry": { "type": "object", "properties": { "odds": { "$ref": "#/components/schemas/Odds" }, "timestamp": { "type": "string", "format": "date-time" }, "changeType": { "type": "array", "items": { "type": "string", "example": "spread" } } } }, "BoxScore": { "type": "object", "properties": { "homeTeam": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "abbreviation": { "type": "string" }, "score": { "type": "integer" } } }, "awayTeam": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "abbreviation": { "type": "string" }, "score": { "type": "integer" } } }, "homePlayers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Basketball/soccer/baseball: flat stat keys (points, rebounds, assists, minutes, ...). Football: per-category stats under `categories`." } }, "awayPlayers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "periodScores": { "type": "object", "properties": { "home": { "type": "array", "items": { "type": "integer" } }, "away": { "type": "array", "items": { "type": "integer" } } } } } }, "WinProbability": { "type": "object", "properties": { "eventId": { "type": "string" }, "winProbability": { "type": "array", "items": { "type": "object", "properties": { "playId": { "type": "string" }, "homeWinPercentage": { "type": "number", "example": 0.62 }, "awayWinPercentage": { "type": "number", "example": 0.38 }, "tiePercentage": { "type": "number", "example": 0 } } } }, "drives": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "Drive summaries (omitted when drives=false)." } } } }, "GameRoster": { "type": "object", "properties": { "eventId": { "type": "string" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "abbreviation": { "type": "string" } } }, "homeAway": { "type": "string", "example": "home", "enum": [ "home", "away" ] }, "players": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "shortName": { "type": "string" }, "jersey": { "type": "string" }, "position": { "type": "string" }, "headshot": { "type": "string" }, "starter": { "type": "boolean" }, "didNotPlay": { "type": "boolean" }, "active": { "type": "boolean" }, "forPlayerId": { "type": "string" } } } }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "starters": { "type": "integer" }, "didNotPlay": { "type": "integer" } } } } } } } }, "Team": { "type": "object", "properties": { "id": { "type": "string", "example": "12" }, "uid": { "type": "string" }, "slug": { "type": "string", "example": "kansas-city-chiefs" }, "location": { "type": "string", "example": "Kansas City" }, "name": { "type": "string", "example": "Chiefs" }, "nickname": { "type": "string", "example": "Chiefs" }, "abbreviation": { "type": "string", "example": "KC" }, "displayName": { "type": "string", "example": "Kansas City Chiefs" }, "shortDisplayName": { "type": "string", "example": "Chiefs" }, "color": { "type": "string" }, "alternateColor": { "type": "string" }, "logos": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "rel": { "type": "array", "items": { "type": "string" } } } } }, "record": { "type": "string", "example": "3-1" }, "standingSummary": { "type": "string", "example": "1st in AFC West" }, "league": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "abbreviation": { "type": "string" }, "slug": { "type": "string" } } }, "venue": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "capacity": { "type": "integer" }, "indoor": { "type": "boolean" }, "grass": { "type": "boolean" } }, "nullable": true }, "isActive": { "type": "boolean" }, "isAllStar": { "type": "boolean" } } }, "RosterAthlete": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "jersey": { "type": "string" }, "position": { "type": "string" }, "age": { "type": "integer" }, "height": { "type": "string" }, "weight": { "type": "string" }, "experience": { "type": "integer" }, "status": { "type": "string" }, "headshot": { "type": "string" } } }, "Roster": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "abbreviation": { "type": "string" } } }, "season": { "type": "integer", "example": 2026 }, "count": { "type": "integer", "example": 53 }, "groups": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string", "example": "offense" }, "athletes": { "type": "array", "items": { "$ref": "#/components/schemas/RosterAthlete" } } } } }, "athletes": { "type": "array", "items": { "$ref": "#/components/schemas/RosterAthlete" } } } }, "DepthChart": { "type": "object", "properties": { "formations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "example": "Base 4-3 D" }, "positions": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string", "example": "QB" }, "positionName": { "type": "string", "example": "Quarterback" }, "athletes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "position": { "type": "string" }, "jersey": { "type": "string" }, "rank": { "type": "integer", "example": 1 }, "slot": { "type": "integer" } } } } } } } } } } } }, "Athlete": { "type": "object", "properties": { "id": { "type": "string", "example": "3139477" }, "displayName": { "type": "string", "example": "Patrick Mahomes" }, "firstName": { "type": "string", "example": "Patrick" }, "lastName": { "type": "string", "example": "Mahomes" }, "position": { "type": "string", "example": "QB" }, "jersey": { "type": "string", "example": "15" }, "age": { "type": "integer", "example": 31 }, "team": { "type": "object", "properties": { "id": { "type": "string", "example": "12" }, "name": { "type": "string", "example": "Chiefs" } } }, "headshot": { "type": "string" }, "hasStats": { "type": "boolean", "example": true }, "statistics": { "type": "object", "properties": { "splits": { "type": "object", "additionalProperties": true } }, "description": "Present on the single-athlete endpoint, or on the list with include=statistics." }, "statisticsScope": { "type": "object", "properties": { "season": { "type": "string", "example": "2025" }, "seasonType": { "type": "integer", "example": 2, "nullable": true } } } } }, "AthleteSearchResult": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "shortName": { "type": "string" }, "jersey": { "type": "string" }, "sport": { "type": "string", "example": "football" }, "league": { "type": "string", "example": "nfl" }, "image": { "type": "string" }, "team": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "abbreviation": { "type": "string" }, "logo": { "type": "string" } } } } }, "GameLogEntry": { "type": "object", "properties": { "eventId": { "type": "string" }, "name": { "type": "string" }, "shortName": { "type": "string" }, "date": { "type": "string" }, "week": { "type": "integer", "example": 5 }, "seasonType": { "type": "integer", "example": 2 }, "teamId": { "type": "string" }, "played": { "type": "boolean", "example": true }, "statistics": { "type": "object", "additionalProperties": true } } }, "AvailabilityState": { "type": "object", "properties": { "athleteId": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "string" }, "teamId": { "type": "string" }, "teamName": { "type": "string" }, "availability": { "type": "string", "example": "QUESTIONABLE", "enum": [ "OUT", "DOUBTFUL", "QUESTIONABLE", "PROBABLE", "DAY_TO_DAY", "INJURED_RESERVE", "SUSPENDED", "AVAILABLE", "UNKNOWN" ] }, "status": { "type": "string", "example": "Questionable" }, "reason": { "type": "string", "example": "Hamstring" }, "detail": { "type": "string" }, "reportDate": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "seasonYear": { "type": "integer", "example": 2026 }, "seasonType": { "type": "integer", "example": 2 }, "week": { "type": "integer", "example": 5 } } }, "AvailabilityTransition": { "allOf": [ { "$ref": "#/components/schemas/AvailabilityState" }, { "type": "object", "properties": { "sport": { "type": "string", "example": "football" }, "league": { "type": "string", "example": "nfl" }, "previousAvailability": { "type": "string" }, "previousStatus": { "type": "string" }, "changeType": { "type": "string", "example": "change", "enum": [ "new", "change", "cleared" ] } } } ] }, "Injury": { "type": "object", "properties": { "athlete": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "position": { "type": "string" } } }, "team": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" } } }, "status": { "type": "string", "example": "Out" }, "statusType": { "type": "string" }, "fantasyStatus": { "type": "string" }, "type": { "type": "string" }, "bodyPart": { "type": "string" }, "location": { "type": "string" }, "detail": { "type": "string" }, "side": { "type": "string" }, "date": { "type": "string" }, "shortComment": { "type": "string" }, "longComment": { "type": "string" } } }, "InjuryReport": { "type": "object", "properties": { "count": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" } } }, "injuries": { "type": "array", "items": { "$ref": "#/components/schemas/Injury" } } } } }, "injuries": { "type": "array", "items": { "$ref": "#/components/schemas/Injury" } } } }, "PlayerAvailability": { "type": "object", "properties": { "athlete": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "position": { "type": "string" } } }, "team": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" } } }, "availability": { "type": "string", "example": "OUT", "enum": [ "OUT", "DOUBTFUL", "QUESTIONABLE", "PROBABLE", "DAY_TO_DAY", "INJURED_RESERVE", "SUSPENDED", "AVAILABLE", "UNKNOWN" ] }, "status": { "type": "string" }, "statusType": { "type": "string" }, "reason": { "type": "string" }, "detail": { "type": "string" }, "date": { "type": "string" } } }, "PlayerAvailabilityReport": { "type": "object", "properties": { "count": { "type": "integer" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" } } }, "players": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerAvailability" } } } } }, "players": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerAvailability" } } } }, "NewsArticle": { "type": "object", "properties": { "id": { "type": "integer" }, "headline": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "example": "HeadlineNews" }, "published": { "type": "string", "format": "date-time" }, "lastModified": { "type": "string" }, "premium": { "type": "boolean", "example": false }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "caption": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } }, "link": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "athletes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } }, "Transactions": { "type": "object", "properties": { "count": { "type": "integer" }, "season": { "type": "integer" }, "page": { "type": "integer" }, "pageCount": { "type": "integer" }, "total": { "type": "integer" }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "description": { "type": "string" }, "team": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "abbreviation": { "type": "string" }, "logo": { "type": "string" } } } } } } } }, "Season": { "type": "object", "properties": { "year": { "type": "integer", "example": 2026 }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "displayName": { "type": "string", "example": "2026" }, "currentType": { "type": "object", "properties": { "id": { "type": "string", "example": "2" }, "name": { "type": "string", "example": "Regular Season" }, "abbreviation": { "type": "string", "example": "reg" }, "slug": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" } }, "nullable": true }, "types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "abbreviation": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" } } } }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" } } } }, "SeasonSummary": { "type": "object", "properties": { "year": { "type": "integer", "example": 2026 }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "displayName": { "type": "string" }, "currentType": { "type": "string", "example": "Regular Season" }, "slug": { "type": "string" } } }, "SeasonType": { "type": "object", "properties": { "id": { "type": "string", "example": "2" }, "name": { "type": "string", "example": "Regular Season" }, "abbreviation": { "type": "string", "example": "reg" }, "slug": { "type": "string", "example": "regular-season" }, "year": { "type": "integer", "example": 2026 }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "hasGroups": { "type": "boolean" }, "hasStandings": { "type": "boolean" }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Group": { "type": "object", "properties": { "id": { "type": "string", "example": "80" }, "name": { "type": "string", "example": "FBS (I-A)" }, "abbreviation": { "type": "string", "example": "FBS" }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Week": { "type": "object", "properties": { "number": { "type": "integer", "example": 5 }, "seasonType": { "type": "integer", "example": 2 }, "label": { "type": "string", "example": "Week 5" }, "startDate": { "type": "string", "example": "2026-10-01T07:00Z", "format": "date-time" }, "endDate": { "type": "string", "example": "2026-10-08T06:59Z", "format": "date-time" } } }, "TournamentGame": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "tournament": { "type": "object", "properties": { "region": { "type": "string", "example": "South" }, "round": { "type": "string", "example": "1st Round" }, "firstFour": { "type": "boolean", "example": false } } } } } ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "example": "https://example.com/hooks/sports", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "leagues": { "type": "array", "items": { "type": "string", "example": "nfl" }, "nullable": true, "description": "League slugs to filter on; null = all leagues." }, "frequency": { "$ref": "#/components/schemas/WebhookFrequency" }, "active": { "type": "boolean", "example": true }, "consecutiveFailures": { "type": "integer", "example": 0 }, "deactivatedReason": { "type": "string", "nullable": true }, "deactivatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "WebhookEventType": { "type": "string", "example": "event.score_change", "enum": [ "event.live", "event.score_change", "event.status_change", "event.play", "event.final" ] }, "WebhookFrequency": { "type": "string", "example": "asap", "enum": [ "asap", "30s", "1m", "5m", "10m", "30m" ] }, "WebhookInput": { "type": "object", "properties": { "url": { "type": "string", "example": "https://example.com/hooks/sports", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "leagues": { "type": "array", "items": { "type": "string", "example": "nfl" }, "nullable": true }, "frequency": { "$ref": "#/components/schemas/WebhookFrequency" }, "active": { "type": "boolean", "example": true } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string", "example": "failed" }, "attempts": { "type": "integer", "example": 1 }, "responseCode": { "type": "integer", "example": 500, "nullable": true }, "error": { "type": "string", "nullable": true }, "eventId": { "type": "string", "nullable": true }, "league": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "paths": { "/sports": { "get": { "operationId": "listSports", "tags": [ "Sports" ], "summary": "List sports", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sport" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues": { "get": { "operationId": "listLeagues", "tags": [ "Sports" ], "summary": "List leagues for a sport", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/League" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}": { "get": { "operationId": "getLeague", "tags": [ "Sports" ], "summary": "Get league details", "description": "League metadata, current season, and links to related endpoints.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LeagueDetail" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "League not found (LEAGUE_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events": { "get": { "operationId": "listEvents", "tags": [ "Events" ], "summary": "List events for a league", "description": "Current and upcoming events (the provider's current scoreboard window). For a specific date range or week use the season schedule endpoint.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum events to return (default 50).", "schema": { "type": "integer", "example": 50, "default": 50, "minimum": 1 } }, { "name": "includeOdds", "in": "query", "required": false, "description": "Attach current betting odds (when available) to each event. Adds latency.", "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events/live": { "get": { "operationId": "listLiveEvents", "tags": [ "Events" ], "summary": "List live events", "description": "Events currently in progress (status.state = \"in\"). Returns an empty array when nothing is live. For continuous updates prefer webhooks or the WebSocket stream over tight polling.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "includeOdds", "in": "query", "required": false, "description": "Attach current betting odds (when available) to each event. Adds latency.", "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events/{eventId}": { "get": { "operationId": "getEvent", "tags": [ "Events" ], "summary": "Get an event", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event (game) id, as returned by the events endpoints.", "schema": { "type": "string", "example": "401772982" } }, { "name": "includeOdds", "in": "query", "required": false, "description": "Attach current betting odds (when available) to each event. Adds latency.", "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Event" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Event not found (EVENT_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events/{eventId}/boxscore": { "get": { "operationId": "getEventBoxScore", "tags": [ "Events" ], "summary": "Get box score", "description": "Team totals and player stats. Supported for basketball, soccer, baseball and football. Football players carry per-category stats (passing, rushing, receiving, defensive, kicking, returns) under `categories`.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event (game) id, as returned by the events endpoints.", "schema": { "type": "string", "example": "401772982" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BoxScore" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Box score not available, e.g. pre-game (BOXSCORE_NOT_AVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events/{eventId}/winprobability": { "get": { "operationId": "getEventWinProbability", "tags": [ "Events" ], "summary": "Get win probability", "description": "Per-play win probability series (join to plays via playId) plus drive summaries, where the source publishes them.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event (game) id, as returned by the events endpoints.", "schema": { "type": "string", "example": "401772982" } }, { "name": "drives", "in": "query", "required": false, "description": "Include drive summaries (default true).", "schema": { "type": "boolean", "example": true } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WinProbability" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "count": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Event summary not available (NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events/{eventId}/roster": { "get": { "operationId": "getEventRoster", "tags": [ "Events" ], "summary": "Get game rosters", "description": "Game-specific rosters with per-player flags (starter, didNotPlay, active). Published by the source at kickoff.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event (game) id, as returned by the events endpoints.", "schema": { "type": "string", "example": "401772982" } }, { "name": "team", "in": "query", "required": false, "description": "Return only this team id.", "schema": { "type": "string", "example": "12" } }, { "name": "starters", "in": "query", "required": false, "description": "Only starters.", "schema": { "type": "boolean", "example": false } }, { "name": "enrich", "in": "query", "required": false, "description": "Resolve athlete names, teams and positions for play participants (default true). Pass false for faster, id-only results.", "schema": { "type": "boolean", "example": true } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/GameRoster" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Game roster not published yet (ROSTER_NOT_PUBLISHED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events/{eventId}/plays": { "get": { "operationId": "listPlays", "tags": [ "Plays" ], "summary": "Get play-by-play", "description": "Plays in chronological order, paginated. Use `limit` up to 1000 to fetch a whole game in one call.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event (game) id, as returned by the events endpoints.", "schema": { "type": "string", "example": "401772982" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum plays to return (default 25, max 1000).", "schema": { "type": "integer", "example": 25, "default": 25, "minimum": 1, "maximum": 1000 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, { "name": "enrich", "in": "query", "required": false, "description": "Resolve athlete names, teams and positions for play participants (default true). Pass false for faster, id-only results.", "schema": { "type": "boolean", "example": true } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Play" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events/{eventId}/penalties": { "get": { "operationId": "listPenalties", "tags": [ "Plays" ], "summary": "Get penalty plays", "description": "Only the penalty plays of an event; all plays are scanned, not just one page.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event (game) id, as returned by the events endpoints.", "schema": { "type": "string", "example": "401772982" } }, { "name": "enrich", "in": "query", "required": false, "description": "Resolve athlete names, teams and positions for play participants (default true). Pass false for faster, id-only results.", "schema": { "type": "boolean", "example": true } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Play" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "totalPlaysScanned": { "type": "integer" }, "count": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events/{eventId}/odds": { "get": { "operationId": "getEventOdds", "tags": [ "Odds" ], "summary": "Get current odds", "description": "Current spread, moneyline and total from a single source book. `data` is null (with a `message`) when no odds are available.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event (game) id, as returned by the events endpoints.", "schema": { "type": "string", "example": "401772982" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Odds" } ], "nullable": true }, "message": { "type": "string", "example": "Odds not available for this event" } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/events/{eventId}/odds/history": { "get": { "operationId": "getEventOddsHistory", "tags": [ "Odds" ], "summary": "Get odds history", "description": "Snapshots recorded each time the line changed, newest first.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "eventId", "in": "path", "required": true, "description": "Event (game) id, as returned by the events endpoints.", "schema": { "type": "string", "example": "401772982" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum snapshots to return (default 100).", "schema": { "type": "integer", "example": 100, "default": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OddsHistoryEntry" } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/teams": { "get": { "operationId": "listTeams", "tags": [ "Teams" ], "summary": "List teams", "description": "Paginated. College football has 800+ teams across all divisions; for FBS only use the group endpoint (/seasons/{season}/types/2/groups/80/teams).", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum teams to return (default 50, max 200).", "schema": { "type": "integer", "example": 50, "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/teams/{teamId}": { "get": { "operationId": "getTeam", "tags": [ "Teams" ], "summary": "Get a team", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "teamId", "in": "path", "required": true, "description": "Team id, as returned by the teams endpoints.", "schema": { "type": "string", "example": "12" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Team" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Team not found (TEAM_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/teams/{teamId}/roster": { "get": { "operationId": "getTeamRoster", "tags": [ "Teams" ], "summary": "Get team roster", "description": "Current roster grouped by position plus a flat list. Pass `season` for a historical season roster (flat list).", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "teamId", "in": "path", "required": true, "description": "Team id, as returned by the teams endpoints.", "schema": { "type": "string", "example": "12" } }, { "name": "season", "in": "query", "required": false, "description": "Historical season year.", "schema": { "type": "integer", "example": 2025 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Roster" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Roster not found (ROSTER_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/teams/{teamId}/depthchart": { "get": { "operationId": "getTeamDepthChart", "tags": [ "Teams" ], "summary": "Get depth chart", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "teamId", "in": "path", "required": true, "description": "Team id, as returned by the teams endpoints.", "schema": { "type": "string", "example": "12" } }, { "name": "season", "in": "query", "required": false, "description": "Season year (defaults to current).", "schema": { "type": "integer", "example": 2026 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DepthChart" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Depth chart not found (DEPTH_CHART_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/athletes": { "get": { "operationId": "listAthletes", "tags": [ "Athletes" ], "summary": "List athletes", "description": "Paginated. Some leagues have tens of thousands of athletes; prefer team rosters or search.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum athletes to return (default 25).", "schema": { "type": "integer", "example": 25, "default": 25, "minimum": 1 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, { "name": "include", "in": "query", "required": false, "description": "Pass `statistics` to attach stats to each athlete (slower).", "schema": { "type": "string", "example": "statistics", "enum": [ "statistics" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Athlete" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/athletes/search": { "get": { "operationId": "searchAthletes", "tags": [ "Athletes" ], "summary": "Search athletes by name", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "query", "in": "query", "required": true, "description": "Name to search for (`q` is accepted as an alias).", "schema": { "type": "string", "example": "mahomes" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results to return (default 25).", "schema": { "type": "integer", "example": 25, "default": 25, "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AthleteSearchResult" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "query": { "type": "string" }, "count": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "query parameter is required (MISSING_QUERY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/athletes/{athleteId}": { "get": { "operationId": "getAthlete", "tags": [ "Athletes" ], "summary": "Get an athlete", "description": "Athlete profile with statistics. Omit season for career/current totals.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "athleteId", "in": "path", "required": true, "description": "Athlete id, as returned by the athletes endpoints.", "schema": { "type": "string", "example": "3139477" } }, { "name": "season", "in": "query", "required": false, "description": "Scope statistics to a season year.", "schema": { "type": "integer", "example": 2025 } }, { "name": "seasonType", "in": "query", "required": false, "description": "1 = preseason, 2 = regular season, 3 = postseason. `type` is accepted as an alias.", "schema": { "type": "integer", "example": 2, "enum": [ 1, 2, 3 ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Athlete" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Athlete not found (ATHLETE_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/athletes/{athleteId}/gamelog": { "get": { "operationId": "getAthleteGameLog", "tags": [ "Athletes" ], "summary": "Get athlete game log", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "athleteId", "in": "path", "required": true, "description": "Athlete id, as returned by the athletes endpoints.", "schema": { "type": "string", "example": "3139477" } }, { "name": "season", "in": "query", "required": true, "description": "Season year.", "schema": { "type": "integer", "example": 2026 } }, { "name": "week", "in": "query", "required": false, "description": "Only this week.", "schema": { "type": "integer", "example": 5 } }, { "name": "seasonType", "in": "query", "required": false, "description": "1 = preseason, 2 = regular season, 3 = postseason. `type` is accepted as an alias.", "schema": { "type": "integer", "example": 2, "enum": [ 1, 2, 3 ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GameLogEntry" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "season": { "type": "string", "example": "2025" }, "count": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "season query parameter is required (MISSING_SEASON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/athletes/{athleteId}/availability-history": { "get": { "operationId": "getAthleteAvailabilityHistory", "tags": [ "Athletes", "Injuries & Availability" ], "summary": "Get athlete availability history", "description": "Time series of a player's injury/availability designations, newest first, as observed by our snapshots (every 30 minutes).", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "athleteId", "in": "path", "required": true, "description": "Athlete id, as returned by the athletes endpoints.", "schema": { "type": "string", "example": "3139477" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum transitions to return (default 100, max 500).", "schema": { "type": "integer", "example": 100, "default": 100, "minimum": 1, "maximum": 500 } }, { "name": "from", "in": "query", "required": false, "description": "Only items on or after this ISO-8601 timestamp.", "schema": { "type": "string", "example": "2026-09-01T00:00:00Z", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Only items on or before this ISO-8601 timestamp.", "schema": { "type": "string", "example": "2026-10-01T00:00:00Z", "format": "date-time" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "athleteId": { "type": "string" }, "current": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/AvailabilityState" } ], "nullable": true }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityTransition" } } } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "count": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/injuries": { "get": { "operationId": "getInjuries", "tags": [ "Injuries & Availability" ], "summary": "Get injury report", "description": "Current injuries grouped by team. Without `team` the league-wide feed is truncated by the source to the 25 most recent records per team; with `team` the complete current report is returned. Empty in the off-season.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "team", "in": "query", "required": false, "description": "Filter to one team id.", "schema": { "type": "string", "example": "12" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InjuryReport" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "note": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/player-availability": { "get": { "operationId": "getPlayerAvailability", "tags": [ "Injuries & Availability" ], "summary": "Get normalized player availability", "description": "One normalized `availability` value per player (OUT, DOUBTFUL, QUESTIONABLE, PROBABLE, DAY_TO_DAY, INJURED_RESERVE, SUSPENDED, AVAILABLE, UNKNOWN).", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "team", "in": "query", "required": false, "description": "Filter to one team id.", "schema": { "type": "string", "example": "12" } }, { "name": "status", "in": "query", "required": false, "description": "Filter to one normalized availability value.", "schema": { "type": "string", "example": "OUT" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PlayerAvailabilityReport" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/player-availability/history": { "get": { "operationId": "getPlayerAvailabilityHistory", "tags": [ "Injuries & Availability" ], "summary": "Get availability changes feed", "description": "League-wide feed of availability designation changes, newest first.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "team", "in": "query", "required": false, "description": "Filter to one team id.", "schema": { "type": "string", "example": "12" } }, { "name": "since", "in": "query", "required": false, "description": "Only changes at or after this time.", "schema": { "type": "string", "example": "2026-09-01T00:00:00Z", "format": "date-time" } }, { "name": "status", "in": "query", "required": false, "description": "Filter to one normalized availability value.", "schema": { "type": "string", "example": "OUT" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum changes to return (default 100, max 500).", "schema": { "type": "integer", "example": 100, "default": 100, "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityTransition" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "count": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/news": { "get": { "operationId": "getNews", "tags": [ "News" ], "summary": "Get latest news", "description": "Rolling window of recent articles from the source. For older articles use /news/history.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum articles to return (default 10, max 50).", "schema": { "type": "integer", "example": 10, "default": 10, "minimum": 1, "maximum": 50 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, { "name": "team", "in": "query", "required": false, "description": "Filter to one team id.", "schema": { "type": "string", "example": "12" } }, { "name": "athlete", "in": "query", "required": false, "description": "Only articles tagged with this athlete id.", "schema": { "type": "string", "example": "3139477" } }, { "name": "since", "in": "query", "required": false, "description": "Alias of `from`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "from", "in": "query", "required": false, "description": "Only items on or after this ISO-8601 timestamp.", "schema": { "type": "string", "example": "2026-09-01T00:00:00Z", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Only items on or before this ISO-8601 timestamp.", "schema": { "type": "string", "example": "2026-10-01T00:00:00Z", "format": "date-time" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NewsArticle" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "count": { "type": "integer" }, "note": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/news/history": { "get": { "operationId": "getNewsHistory", "tags": [ "News" ], "summary": "Get archived news", "description": "Our archive of league news, newest first. The archive begins 2026-09-02.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "from", "in": "query", "required": false, "description": "Only items on or after this ISO-8601 timestamp.", "schema": { "type": "string", "example": "2026-09-01T00:00:00Z", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Only items on or before this ISO-8601 timestamp.", "schema": { "type": "string", "example": "2026-10-01T00:00:00Z", "format": "date-time" } }, { "name": "team", "in": "query", "required": false, "description": "Filter to one team id.", "schema": { "type": "string", "example": "12" } }, { "name": "athlete", "in": "query", "required": false, "description": "Only articles tagged with this athlete id.", "schema": { "type": "string", "example": "3139477" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum articles to return (default 25, max 100).", "schema": { "type": "integer", "example": 25, "default": 25, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NewsArticle" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "count": { "type": "integer" }, "note": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/transactions": { "get": { "operationId": "getTransactions", "tags": [ "Transactions" ], "summary": "Get transactions", "description": "Recent signings, injured-list moves, call-ups, releases and trades. Empty in the off-season.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum transactions to return (default 25).", "schema": { "type": "integer", "example": 25, "default": 25, "minimum": 1 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, { "name": "team", "in": "query", "required": false, "description": "Filter to one team id.", "schema": { "type": "string", "example": "12" } }, { "name": "season", "in": "query", "required": false, "description": "Season year.", "schema": { "type": "integer", "example": 2026 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Transactions" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/season": { "get": { "operationId": "getCurrentSeason", "tags": [ "Seasons" ], "summary": "Get the active season", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Season" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Active season not found (SEASON_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons": { "get": { "operationId": "listSeasons", "tags": [ "Seasons" ], "summary": "List seasons", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum seasons to return (default 25).", "schema": { "type": "integer", "example": 25, "default": 25, "minimum": 1 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeasonSummary" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}": { "get": { "operationId": "getSeason", "tags": [ "Seasons" ], "summary": "Get a season", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Season" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Season not found (SEASON_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}/schedule": { "get": { "operationId": "getSeasonSchedule", "tags": [ "Seasons" ], "summary": "Get season schedule", "description": "Events for a season, optionally one week (NFL and college football only). With `week`, our synced store (which covers about the next week) is merged with the live scoreboard so future weeks are complete. Without `week`, up to 200 events from the synced store, falling back to the live source. `meta.source` is \"synced\", \"live\" or \"merged\".", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } }, { "name": "week", "in": "query", "required": false, "description": "Week number (NFL and college-football only).", "schema": { "type": "integer", "example": 5, "minimum": 0 } }, { "name": "seasonType", "in": "query", "required": false, "description": "1 = preseason, 2 = regular season, 3 = postseason. `type` is accepted as an alias.", "schema": { "type": "integer", "example": 2, "enum": [ 1, 2, 3 ] } }, { "name": "includeOdds", "in": "query", "required": false, "description": "Attach current betting odds (when available) to each event. Adds latency.", "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "week": { "type": "integer" }, "seasonType": { "type": "integer" }, "dateRange": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } }, "source": { "type": "string", "example": "synced", "enum": [ "synced", "live", "merged" ] } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Invalid week, or weeks not supported for this league (INVALID_WEEK, SCHEDULE_WEEKS_NOT_SUPPORTED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Season not found (SEASON_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}/weeks": { "get": { "operationId": "listSeasonWeeks", "tags": [ "Seasons" ], "summary": "List weeks in a season", "description": "NFL and college football only.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } }, { "name": "seasonType", "in": "query", "required": false, "description": "1 = preseason, 2 = regular season, 3 = postseason. `type` is accepted as an alias.", "schema": { "type": "integer", "example": 2, "enum": [ 1, 2, 3 ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Week" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Weeks not supported for this league (SCHEDULE_WEEKS_NOT_SUPPORTED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}/types": { "get": { "operationId": "listSeasonTypes", "tags": [ "Seasons" ], "summary": "List season types", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeasonType" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Season types not found (TYPES_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}/types/{typeId}": { "get": { "operationId": "getSeasonType", "tags": [ "Seasons" ], "summary": "Get a season type", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } }, { "name": "typeId", "in": "path", "required": true, "description": "Season type id: 1 = preseason, 2 = regular season, 3 = postseason (4 = off-season for some leagues).", "schema": { "type": "string", "example": "2" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/SeasonType" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Season type not found (TYPE_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}/types/{typeId}/groups": { "get": { "operationId": "listGroups", "tags": [ "Seasons" ], "summary": "List groups (conferences/divisions)", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } }, { "name": "typeId", "in": "path", "required": true, "description": "Season type id: 1 = preseason, 2 = regular season, 3 = postseason (4 = off-season for some leagues).", "schema": { "type": "string", "example": "2" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Groups not found (GROUPS_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}/types/{typeId}/groups/{groupId}": { "get": { "operationId": "getGroup", "tags": [ "Seasons" ], "summary": "Get a group", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } }, { "name": "typeId", "in": "path", "required": true, "description": "Season type id: 1 = preseason, 2 = regular season, 3 = postseason (4 = off-season for some leagues).", "schema": { "type": "string", "example": "2" } }, { "name": "groupId", "in": "path", "required": true, "description": "Group (conference/division) id. College football: 80 = FBS, 81 = FCS.", "schema": { "type": "string", "example": "80" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Group" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Group not found (GROUP_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}/types/{typeId}/groups/{groupId}/teams": { "get": { "operationId": "listGroupTeams", "tags": [ "Seasons", "Teams" ], "summary": "List teams in a group", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } }, { "name": "typeId", "in": "path", "required": true, "description": "Season type id: 1 = preseason, 2 = regular season, 3 = postseason (4 = off-season for some leagues).", "schema": { "type": "string", "example": "2" } }, { "name": "groupId", "in": "path", "required": true, "description": "Group (conference/division) id. College football: 80 = FBS, 81 = FCS.", "schema": { "type": "string", "example": "80" } }, { "name": "pageSize", "in": "query", "required": false, "description": "Teams per page (default 25, max 200). `limit` is accepted as an alias.", "schema": { "type": "integer", "example": 25, "maximum": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Teams not found (TEAMS_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}/teams/{teamId}/events": { "get": { "operationId": "listTeamSeasonEvents", "tags": [ "Seasons", "Teams" ], "summary": "List a team's events in a season", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } }, { "name": "teamId", "in": "path", "required": true, "description": "Team id, as returned by the teams endpoints.", "schema": { "type": "string", "example": "12" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-based).", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Source page size (default 25).", "schema": { "type": "integer", "example": 25 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum events from the page to return (default 50).", "schema": { "type": "integer", "example": 50, "default": 50, "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Events not found (EVENTS_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/sports/{sport}/leagues/{league}/seasons/{season}/tournament": { "get": { "operationId": "getTournament", "tags": [ "Seasons" ], "summary": "Get NCAA tournament games", "description": "NCAA tournament games for a season with region, round and First Four flag. Basketball only; excludes NIT/CBI/CIT.", "parameters": [ { "name": "sport", "in": "path", "required": true, "description": "Sport slug: football, basketball, baseball, hockey, soccer.", "schema": { "type": "string", "example": "football" } }, { "name": "league", "in": "path", "required": true, "description": "League slug, e.g. nfl, college-football, nba, mens-college-basketball, mlb, nhl, eng.1, usa.1.", "schema": { "type": "string", "example": "nfl" } }, { "name": "season", "in": "path", "required": true, "description": "Season year, e.g. 2026.", "schema": { "type": "integer", "example": 2026 } }, { "name": "round", "in": "query", "required": false, "description": "Round label filter (substring, case-insensitive).", "schema": { "type": "string", "example": "Sweet 16" } }, { "name": "region", "in": "query", "required": false, "description": "Region name filter.", "schema": { "type": "string", "example": "South" } }, { "name": "firstFour", "in": "query", "required": false, "description": "true = only First Four games, false = exclude them.", "schema": { "type": "boolean" } }, { "name": "startDate", "in": "query", "required": false, "description": "Override scan window start (YYYYMMDD).", "schema": { "type": "string", "example": "20260317" } }, { "name": "endDate", "in": "query", "required": false, "description": "Override scan window end (YYYYMMDD).", "schema": { "type": "string", "example": "20260407" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TournamentGame" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "season": { "type": "string" }, "total": { "type": "integer" }, "firstFour": { "type": "integer" }, "mainBracket": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Only available for basketball leagues (TOURNAMENT_NOT_SUPPORTED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List your webhooks", "description": "Requires a paid plan.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "count": { "type": "integer" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Paid plan or direct API key required (TIER_REQUIRED, DIRECT_API_KEY_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Deliveries are signed with HMAC-SHA256 in the `X-Webhook-Signature` header. The signing secret is returned only in this response (retrieve it later via /webhooks/{webhookId}/secret).", "parameters": [], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Invalid body (INVALID_JSON, INVALID_URL, INVALID_EVENTS, INVALID_LEAGUES, INVALID_FREQUENCY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Paid plan or direct API key required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookInput" } ], "required": [ "url", "events" ] } } } } } }, "/webhooks/{webhookId}": { "get": { "operationId": "getWebhook", "tags": [ "Webhooks" ], "summary": "Get a webhook", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook id, as returned by GET /webhooks.", "schema": { "type": "string", "example": "3fK9xQ2mLp7Rz1Vb" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Webhook" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not your webhook, or paid plan required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found (WEBHOOK_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Partial update of any of url, events, leagues, frequency, active. `active: true` re-enables an automatically deactivated webhook.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook id, as returned by GET /webhooks.", "schema": { "type": "string", "example": "3fK9xQ2mLp7Rz1Vb" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Webhook" }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Invalid body or no changes (NO_CHANGES).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not your webhook, or paid plan required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } } }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook id, as returned by GET /webhooks.", "schema": { "type": "string", "example": "3fK9xQ2mLp7Rz1Vb" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not your webhook, or paid plan required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhooks/{webhookId}/secret": { "get": { "operationId": "getWebhookSecret", "tags": [ "Webhooks" ], "summary": "Reveal the signing secret", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook id, as returned by GET /webhooks.", "schema": { "type": "string", "example": "3fK9xQ2mLp7Rz1Vb" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not your webhook, or paid plan required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "rotateWebhookSecret", "tags": [ "Webhooks" ], "summary": "Rotate the signing secret", "description": "The old secret stops being used within about one second.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook id, as returned by GET /webhooks.", "schema": { "type": "string", "example": "3fK9xQ2mLp7Rz1Vb" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not your webhook, or paid plan required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhooks/{webhookId}/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Send a test delivery", "description": "Sends a signed sample payload (header `X-Webhook-Test: true`), or replays a recorded failed delivery when `deliveryId` is given.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook id, as returned by GET /webhooks.", "schema": { "type": "string", "example": "3fK9xQ2mLp7Rz1Vb" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "statusCode": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true }, "durationMs": { "type": "integer" }, "responseSnippet": { "type": "string", "nullable": true }, "sent": { "type": "object", "properties": { "url": { "type": "string" }, "event": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "object", "additionalProperties": true } } } } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not your webhook, or paid plan required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook or delivery not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "$ref": "#/components/schemas/WebhookEventType" }, "deliveryId": { "type": "string", "description": "Replay this failed delivery instead of a sample." } } } } } } } }, "/webhooks/{webhookId}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "List failed deliveries", "description": "Recent failed delivery attempts. Successful deliveries are not recorded individually.", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook id, as returned by GET /webhooks.", "schema": { "type": "string", "example": "3fK9xQ2mLp7Rz1Vb" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum deliveries to return (default 50, max 200).", "schema": { "type": "integer", "example": 50, "default": 50, "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "type": "object", "properties": { "rateLimit": { "$ref": "#/components/schemas/RateLimit" }, "count": { "type": "integer" }, "note": { "type": "string" } } } }, "required": [ "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not your webhook, or paid plan required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/websocket/auth": { "servers": [ { "url": "https://www.realtimesportsapi.com/api", "description": "Production (not under /v1)" } ], "post": { "operationId": "createWebSocketToken", "tags": [ "WebSocket" ], "summary": "Get a WebSocket token", "description": "Returns the WebSocket URL and a token valid for one hour. Connect to `${url}?token=${token}`, then send `{\"type\":\"subscribe\",\"event\":\"event_score_change\",\"filters\":{\"sport\":\"football\",\"league\":\"nfl\"}}`. Event types: event_score_change, event_live, event_status_change, event_play, event_final, event_odds_change. Each delivered message counts toward your quota.", "parameters": [], "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "url": { "type": "string", "example": "wss://example.up.railway.app" }, "token": { "type": "string" }, "expiresIn": { "type": "integer", "example": 3600 }, "userId": { "type": "string" }, "tier": { "type": "string", "example": "starter" } } } }, "required": [ "success", "data" ] } } } }, "401": { "description": "Missing or invalid API key (UNAUTHORIZED, INVALID_API_KEY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Subscription inactive or monthly quota exhausted (SUBSCRIPTION_INACTIVE, WEBSOCKET_QUOTA_EXCEEDED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } } } }