# Snooker API

> 28 REST endpoints covering professional snooker from 1927: events, draws, results with frame scores, live frame scores, players, world rankings and century breaks. Factual data only: no predictions, ratings or tips.

## Complete reference

- [Full manual, one file](https://snookerapi.net/documentation/manual.md): every endpoint, parameter, sample response and guide in a single markdown document.
- [MCP server](https://snookerapi.net/mcp): Model Context Protocol endpoint.

## Agent skill

- [Snooker API agent skill](https://snookerapi.net/.well-known/agent-skills/snookerapi/SKILL.md): how agents use the Snooker API. Index: https://snookerapi.net/.well-known/agent-skills/index.json

## Guides

- [Quick start](https://snookerapi.net/documentation/quick-start): A key, the first call and the answer, in three steps.
- [Authentication](https://snookerapi.net/documentation/authentication): Sending the key, and what happens without one.
- [Plans and limits](https://snookerapi.net/documentation/plans): What each plan reads, its limits and the headers that report them.
- [Pagination](https://snookerapi.net/documentation/pagination): Pages or a cursor, and the totals in meta.
- [Errors](https://snookerapi.net/documentation/errors): Every error code, what it means and what to do.
- [Dates](https://snookerapi.net/documentation/dates): Days, windows and how close a date is.
- [Coverage](https://snookerapi.net/documentation/coverage): What the data holds and how far back.
- [Events and draws](https://snookerapi.net/documentation/events-and-draws): Tournaments, their draws, champions and prize money.
- [Results and frames](https://snookerapi.net/documentation/results-and-frames): Match results, rounds and frame-by-frame scores.
- [Player records](https://snookerapi.net/documentation/player-records): Finding players and reading their records.
- [World rankings](https://snookerapi.net/documentation/world-rankings): The ranking lists of each season.
- [Breaks](https://snookerapi.net/documentation/breaks): Century breaks and maximums.
- [Live scores](https://snookerapi.net/documentation/live): Following matches as they are played: one match, the feed, and the stream.
- [Webhooks](https://snookerapi.net/documentation/webhooks): The live events posted to your app, signed and retried.
- [Changelog](https://snookerapi.net/documentation/changelog): What changed, newest first.
- [MCP](https://snookerapi.net/documentation/mcp): Connecting an assistant to the Snooker API.
- [MCP tools](https://snookerapi.net/documentation/mcp-tools): Every tool, its purpose, parameters and endpoint.
- [Agent skill](https://snookerapi.net/documentation/agent-skill): The one file that teaches an agent the Snooker API.

## Endpoints

- [GET /v1/events](https://snookerapi.net/documentation/events): Events: every tournament and championship, newest first.
- [GET /v1/events/{event_id}](https://snookerapi.net/documentation/event): One event: its dates, venue, champion, final, prize fund and its own figures (frames played, deciding frames, whitewashes, centuries).
- [GET /v1/events/{event_id}/points](https://snookerapi.net/documentation/event-points): The world ranking points each player earned at a ranking event, as the season's rankings publish them, and whether our own results for the event give the same points.
- [GET /v1/matches](https://snookerapi.net/documentation/matches): Matches: results and draws, newest first, by event, player, season or dates.
- [GET /v1/matches/{match_id}](https://snookerapi.net/documentation/match): One match, with its status, its frames where they are known (points and breaks of 50 and over), and every change to it since it entered our record.
- [GET /v1/results/yesterday](https://snookerapi.net/documentation/results-yesterday): Every match finished yesterday (UTC): those our live tracker saw finish yesterday, and those whose own day is yesterday.
- [GET /v1/players](https://snookerapi.net/documentation/players): Players: everyone who has played in an event we hold, from 1927 on.
- [GET /v1/players/{player_id}](https://snookerapi.net/documentation/player): One player: nationality, birth date and place, the year they turned professional, their ranking, minor-ranking and world titles, the first season they were ranked, their highest world ranking, matches played and won, titles, and the seasons they span.
- [GET /v1/head-to-head](https://snookerapi.net/documentation/head-to-head): Two players' meetings: how many, who won, frames won by each, their finals, and every match between them, newest first.
- [GET /v1/rankings](https://snookerapi.net/documentation/rankings): World rankings: a season's list, position by position, with ranking points where they are known.
- [GET /v1/centuries](https://snookerapi.net/documentation/centuries): Century breaks: every break of 100 or more in the events we hold, by event, player or season.
- [GET /v1/maximums](https://snookerapi.net/documentation/maximums): Maximum breaks: every officially recognised 147, newest first, with the player, the opponent and the event.
- [GET /v1/export/{part}](https://snookerapi.net/documentation/export): Bulk export: one part of the whole record as a gzip file of JSON lines, one record a line, in the same shape as the API, rebuilt daily.
- [GET /v1/usage](https://snookerapi.net/documentation/usage): Your key: its plan, calls today, limits, when they reset, and the data window the plan covers.
- [GET /v1/matches/{match_id}/live](https://snookerapi.net/documentation/match-live): One match as it stands: whether it is under way, the frames won, every frame known, and its latest change.
- [GET /v1/live/events](https://snookerapi.net/documentation/live-events): The live feed: every score change, frame won, result and century in the events being played, oldest first after since.
- [GET /v1/stream/token](https://snookerapi.net/documentation/stream-token): A token for the stream, for a browser: EventSource cannot send a header, so it opens /v1/stream?token=... instead of sending the key.
- [GET /v1/stream](https://snookerapi.net/documentation/stream): The live feed as Server-Sent Events, sent as it happens: one connection holds for five minutes, then reconnects by itself from the last event.
- [GET /v1/stats/yesterday](https://snookerapi.net/documentation/stats-yesterday): Yesterday (UTC) in one answer: matches, walkovers, frames, deciding frames, whitewashes, average match length, centuries and the highest break, in all and by stage.
- [GET /v1/stats/yesterday/players](https://snookerapi.net/documentation/stats-yesterday-players): Every player who played yesterday: matches won and lost, frames won and lost, frame difference and frame win rate, centuries and their highest. Most wins first.
- [GET /v1/stats/yesterday/deciders](https://snookerapi.net/documentation/stats-yesterday-deciders): Yesterday's matches settled in the deciding frame (won by one frame at full length), as the matches list gives them.
- [GET /v1/stats/yesterday/whitewashes](https://snookerapi.net/documentation/stats-yesterday-whitewashes): Yesterday's matches won without losing a frame, as the matches list gives them.
- [GET /v1/stats/yesterday/upsets](https://snookerapi.net/documentation/stats-yesterday-upsets): Yesterday's wins over a higher-ranked player, on the newest world ranking list, biggest ranking gap first. An unranked winner counts as one place below the list.
- [GET /v1/stats/yesterday/top16](https://snookerapi.net/documentation/stats-yesterday-top16): How the world's top 16 on the newest ranking list fared yesterday: each one who played, their matches, wins, losses and frames, and every result.
- [GET /v1/stats/yesterday/nations](https://snookerapi.net/documentation/stats-yesterday-nations): Yesterday by nation, as the draws flag each player (ENG, CHN, WAL ...): players in action, matches won and lost, frames won and lost, centuries. Most wins first.
- [GET /v1/stats/yesterday/events](https://snookerapi.net/documentation/stats-yesterday-events): Yesterday by event, and within each event by round: matches, frames, deciding frames, whitewashes and average match length; centuries and the highest by event.
- [GET /v1/stats/yesterday/scorelines](https://snookerapi.net/documentation/stats-yesterday-scorelines): How often each scoreline came up yesterday, by match length: 4-0, 4-1, 4-2, 4-3 in best of 7, and so on, with each one's share.
- [GET /v1/stats/yesterday/centuries](https://snookerapi.net/documentation/stats-yesterday-centuries): Every century break we had yesterday, highest first, with the player, the event and the stage.