canonical: https://jentic.com/apis/realtimesportsapi.com/realtimesportsapi # Realtime Sports API The Realtime Sports API serves live scores, play-by-play, box scores, schedules, teams, athletes, injuries, news, and betting odds for the NFL, college football, the NBA, men's college basketball, MLB, the NHL, and 23 soccer competitions under one schema. Every resource is addressed by a sport slug and a league slug in the URL path, such as football and nfl, down to individual events, teams, athletes, and seasons. Webhooks with HMAC-SHA256 signed deliveries and a WebSocket token operation push updates instead of polling; the spec notes data is typically 20-30 seconds behind live play. ## For AI agents Get live scores, box scores, play-by-play, win probability, odds, injuries, rosters, and news for NFL, NBA, MLB, NHL, college, and soccer leagues, and subscribe to updates by webhook. ## Scope Does not place bets, stream video, or sell tickets. Use for reading scores, game data, odds, and sports news only. ## Capabilities - List live events for a league, optionally attaching current betting odds with includeOdds - Read an event's box score, play-by-play, penalty plays, and win probability by eventId - Track current odds and odds history for a single event - Check injury reports and normalized player availability by team, plus a feed of availability changes since a timestamp - Search athletes by name and pull a season game log filtered by week and seasonType - Pull a season schedule by week, conference and division groups, and NCAA tournament games by round and region - Register webhooks for chosen events, rotate their signing secret, send a test delivery, and list failed deliveries ## Use cases ### Sports answers from an AI agent through Jentic A chat assistant asked 'what's the score of the Chiefs game?' needs a live lookup, not stale training data. Through Jentic the agent searches for 'live scores for a league', receives the live events operation with its sport and league inputs, and calls it while your self-hosted Jentic One instance injects the bearer key. It can follow up with the box score or win probability for the same eventId. Example prompt: Call GET `/sports/{sport}/leagues/{league}/events/live` with sport 'football' and league 'nfl', find the event involving Kansas City, then GET its boxscore by eventId ### Fantasy and lineup decisions Fantasy players and lineup tools care about who is playing. The injury report and normalized player availability operations filter by team and status, the availability history feed returns changes since a timestamp, and an athlete's game log can be pulled per season and week. Team depth charts and game rosters with starters fill in the rest. Example prompt: Call GET `/sports/{sport}/leagues/{league}/player-availability/history` with sport 'football', league 'nfl', and since set to this morning, then list players whose status changed ### Push updates by webhook Polling scores burns monthly quota. A webhook created with a url and a list of events receives pushed deliveries signed with HMAC-SHA256 in the X-Webhook-Signature header, and the signing secret is returned once at creation and can be revealed or rotated later. A test delivery and a failed-deliveries list help debug the receiver. Webhooks need a paid plan or a direct API key. Example prompt: POST /webhooks with url 'https://example.com/hooks/scores' and the events to subscribe to, then POST `/webhooks/{webhookId}/test` to send a test delivery ### Odds tracking Betting content and research tools follow how lines move. The current odds and odds history operations work per eventId, and live and scheduled event lists can carry odds inline with includeOdds. The spec states the data runs about 20-30 seconds behind live play and is not suitable for in-play betting that needs sub-second data. Example prompt: Call GET `/sports/{sport}/leagues/{league}/events/{eventId}/odds/history` for sport 'basketball', league 'nba', and the event's eventId, then summarise how the spread moved ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/sports/{sport}/leagues/{league}/events/live` | List live events | | GET | `/sports/{sport}/leagues/{league}/events/{eventId}/boxscore` | Get box score | | GET | `/sports/{sport}/leagues/{league}/events/{eventId}/plays` | Get play-by-play | | GET | `/sports/{sport}/leagues/{league}/events/{eventId}/odds` | Get current odds | | GET | `/sports/{sport}/leagues/{league}/injuries` | Get injury report | | GET | `/sports/{sport}/leagues/{league}/seasons/{season}/schedule` | Get season schedule | | GET | `/sports/{sport}/leagues/{league}/athletes/search` | Search athletes by name | | POST | `/webhooks` | Create a webhook | ## Key resources - **Events** — Games with live status, box scores, plays, win probability, rosters, and odds - **Teams** — Team details, rosters, depth charts, and season events - **Athletes** — Athlete profiles, name search, game logs, and availability history - **Seasons** — Schedules, weeks, season types, groups, and NCAA tournament games - **Injuries and news** — Injury reports, player availability, news, and transactions - **Webhooks** — Signed push deliveries with secret rotation and failure listing ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 67 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 99 / 100 - Developer Experience & Jentic Compatibility: 77 / 100 - AI-Readiness & Agent Experience: 45 / 100 - Agent Usability: 94 / 100 - Security: 55 / 100 - AI Discoverability: 69 / 100 - **View full report:** https://jentic.com/apis/realtimesportsapi.com/realtimesportsapi/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the Realtime Sports API by hand means choosing between the bearer and X-API-Key headers, composing sport and league slugs into every path, and watching meta.rateLimit so you do not hit 429s. Through Jentic you install once, import the Realtime Sports API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** The sport and league slugs sit in the URL path (`/sports/{sport}/leagues/{league}/...`), so a rule can pin your agent to one league such as nfl, and event, team, and athlete ids narrow it further. You choose the operations it may call, so webhook deletion or signing-secret reveal and rotation are not included unless you add them. - **Credential handling:** Your Realtime Sports API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'live NFL scores' or 'injury report for a team', and Jentic returns the matching Realtime Sports operation with its input schema so the agent fills the right sport and league slugs without browsing the reference docs. ## Related APIs - **SportsData.io NFL API** — NFL scores, stats, and projections - **API-Sports Football** — Football (soccer) fixtures, standings, and statistics - **The Odds API** — Bookmaker odds across many sports and regions ## FAQ ### What authentication does the Realtime Sports API use? Per its OpenAPI spec, the Realtime Sports API accepts your API key either as a bearer token in the Authorization header or through the ApiKeyHeader scheme, an apiKey sent in the `X-API-Key` header that is useful behind proxies that strip Authorization. Keys are opaque strings, not JWTs. Through Jentic, the key is stored encrypted by your own Jentic One instance and injected at execution time, so it never enters the agent's context. ### Is there a Realtime Sports API MCP server? You don't need an MCP server to give your agent the Realtime Sports API. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls it. Operations are discovered on demand, so the agent loads the score or odds operation it needs rather than the whole surface. ### Can I limit what my agent is allowed to do with the Realtime Sports API? Yes. For a fantasy football assistant, allow only the GET operations under `/sports/football/leagues/nfl`/, so the agent can read NFL scores, injuries, and rosters but cannot query other leagues, create or delete webhooks, or reveal a webhook signing secret. Every call it makes is logged. ### What are the rate limits for the Realtime Sports API? The spec's own description sets monthly call quotas per plan: Free 125 per month (1,000 in the first 30 days), Starter 10,000, Growth 25,000, Pro 50,000, and Scale 500,000. Per-second rates also apply, from Free 1/s up to Scale 100/s. When the quota runs out the API returns HTTP 429 with a Retry-After header, and remaining quota appears in meta.rateLimit on most responses. ### How fresh is the Realtime Sports API data? The spec states data is aggregated from public sources and is typically 20-30 seconds behind live play, with no SLA. It is not suitable for in-play betting that needs sub-second data; for faster delivery than polling, use webhooks or the WebSocket token from POST `/websocket/auth.` ### Which leagues does the Realtime Sports API cover? The spec lists the NFL, college football, the NBA, men's college basketball, MLB, the NHL, and 23 soccer competitions. Sport slugs include football, basketball, baseball, hockey, and soccer, and league slugs include nfl, nba, mlb, nhl, eng.1, and usa.1; GET /sports and the leagues listing return the full set. ### How do I get live scores through Jentic? Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import the Realtime Sports API from the API Directory, and store your key. Your agent searches for 'live scores for a league', receives the live events operation with its sport and league inputs, and calls it. To run it on your own infrastructure, install Jentic One from its GitHub repo.