## Table Tennis API

> Table tennis data as a JSON API. 15 REST endpoints covering every professional event since December 2024: live scores, results with every game score, the event calendar, players, head to head and the world rankings. Send the key as Authorization: Bearer <key>; ids (ev_, mt_, pl_) never change.
> Factual data only: no predictions, ratings or tips.

### Complete reference

- [Full manual, one file](https://tabletennisapi.com/documentation/manual.md): every endpoint, parameter, sample response and guide in a single markdown document.
- [OpenAPI](https://tabletennisapi.com/openapi.json): machine-readable API description.
- [MCP server](https://tabletennisapi.com/mcp): Model Context Protocol endpoint.

### Guides

- [Getting started](https://tabletennisapi.com/documentation/getting-started): From no key to your first result in about two minutes.
- [Authentication](https://tabletennisapi.com/documentation/authentication): Every call carries your key in a header. Keys in the address are refused.
- [Pagination](https://tabletennisapi.com/documentation/pagination): Lists come back a page at a time. Two ways to move through them.
- [Rate limits](https://tabletennisapi.com/documentation/rate-limits): Two limits: calls a minute and calls a day. Every response tells you where you stand.
- [Errors](https://tabletennisapi.com/documentation/errors): Errors are JSON with a short code you can switch on and a message you can show.
- [Timezones and dates](https://tabletennisapi.com/documentation/timezones-and-dates): Times are UTC. The date of a match is the local day of play.
- [MCP server](https://tabletennisapi.com/documentation/mcp-server): Let Claude, ChatGPT, Cursor and other MCP apps call the API for you.
- [What we cover](https://tabletennisapi.com/documentation/what-we-cover): Every professional event since December 2024, every discipline, the calendar ahead.
- [The whole API in one file](https://tabletennisapi.com/documentation/the-whole-api-in-one-file): Everything about the API in files you can hand to a tool or a language model. No key needed to read them.
- [Webhooks](https://tabletennisapi.com/documentation/webhooks): We call your address the moment a match starts, a result is official or a new event is on the calendar.
- [Changelog](https://tabletennisapi.com/documentation/changelog): What changed in the API, newest first.

### Endpoints

- [GET /v1/usage](https://tabletennisapi.com/documentation/endpoints/usage): Your plan, calls today, limits and the dates your plan reads. Not counted against your allowance. Plans: Free key, Live, Archive, Complete
- [GET /v1/events](https://tabletennisapi.com/documentation/endpoints/events): Events: past, running and scheduled, newest first. Plans: Free key, Live, Archive, Complete
- [GET /v1/events/{id}](https://tabletennisapi.com/documentation/endpoints/event): One event: name, dates, venue, and its disciplines with match counts. Plans: Free key, Live, Archive, Complete
- [GET /v1/events/{id}/matches](https://tabletennisapi.com/documentation/endpoints/event-matches): An event's matches, in order of play. Plans: Free key, Live, Archive, Complete
- [GET /v1/matches](https://tabletennisapi.com/documentation/endpoints/matches): Matches on a day or across dates, every event. Plans: Free key, Live, Archive, Complete
- [GET /v1/matches/{id}](https://tabletennisapi.com/documentation/endpoints/match): One match: players, score, every game, length, table, format, real start, timeouts and cards. Plans: Free key, Live, Archive, Complete
- [GET /v1/matches/{id}/points](https://tabletennisapi.com/documentation/endpoints/match-points): Point by point: every score in every game as our live tracking saw it, about every 10 seconds, with who served. For matches followed live from October 2026. Plans: Free key, Live, Archive, Complete
- [GET /v1/live](https://tabletennisapi.com/documentation/endpoints/live): Matches being played now, with the game in progress. Refreshed about every 10 seconds. Plans: Live, Complete
- [GET /v1/results/yesterday](https://tabletennisapi.com/documentation/endpoints/results-yesterday): Yesterday's finished matches, every event. On every plan. Plans: Free key, Live, Archive, Complete
- [GET /v1/players](https://tabletennisapi.com/documentation/endpoints/players): Find players by name or country. Plans: Free key, Live, Archive, Complete
- [GET /v1/players/{id}](https://tabletennisapi.com/documentation/endpoints/player): One player: name, country and their record by discipline. Plans: Free key, Live, Archive, Complete
- [GET /v1/players/{id}/matches](https://tabletennisapi.com/documentation/endpoints/player-matches): A player's matches, newest first, singles and doubles. Plans: Live, Archive, Complete
- [GET /v1/h2h/{a}/{b}](https://tabletennisapi.com/documentation/endpoints/h2h): Two players against each other: wins, games, and every meeting. Plans: Live, Archive, Complete
- [GET /v1/rankings](https://tabletennisapi.com/documentation/endpoints/rankings): World rankings: the top 100 of a list for a week, with points and movement. The latest week unless you ask for one. Plans: Free key, Live, Archive, Complete
- [GET /v1/players/{id}/rankings](https://tabletennisapi.com/documentation/endpoints/player-rankings): A player's world ranking week by week, on every list they are in, newest first. Plans: Live, Archive, Complete

## Agent skill

- [Table Tennis API agent skill](https://tabletennisapi.com/.well-known/agent-skills/tabletennisapi/SKILL.md): how agents use Table Tennis API. Index: https://tabletennisapi.com/.well-known/agent-skills/index.json