Live Tennis API — Full Reference

GET /health

Liveness probe (no auth)

Plan required: — · operationId: healthCheck

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/health

GET /matches

List matches by lifecycle status (FREE)

Plan required: FREE · operationId: listMatches

status=live and status=upcoming are the FREE current-state picture. status=completed pages historical results and is part of the paid History product — it requires BASIC (the same rule as /history/matches) and returns 403 upgrade_required on a FREE key. The player, country, from/to, tour and draw filters are optional, AND-composed, applied inside the query (before pagination), and work on every status — omitting them returns exactly what the endpoint returned before they existed.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}

Full match detail (FREE; +market PRO, +analysis ULTRA)

Plan required: FREE · operationId: getMatch

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953 \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/score

Current score only — lowest-latency REST read (FREE)

Plan required: FREE · operationId: getMatchScore

This is a POINT-IN-TIME SNAPSHOT: the single current state, overwritten on every score commit. It carries no history and no accumulated statistics. For the SEQUENCE of states — who served each game, hold/break, every score state in forward order — use /history/matches/{matchId}?sequence=clean, which works on a LIVE match, not only a completed one. For in-play statistics use /matches/{matchId}/statistics (ULTRA); they are deliberately not on this object, because they can be further behind the match than the score and must carry their own as_of.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/score \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/events

Match events, newest first (PRO)

Plan required: PRO · operationId: listMatchEvents

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/events \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/analysis

Model analysis for a match (ULTRA)

Plan required: ULTRA · operationId: getMatchAnalysis

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/analysis \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/statistics

In-play statistics — aces, double faults, serve split, hold/break %, break points, service & return points (ULTRA)

Plan required: ULTRA · operationId: getMatchStatistics

In-play statistics for one match, in TWO families that are deliberately not merged. DERIVED (the top level of players.pN) are rebuilt from the point-by-point record: service and return games played and won, hold and break percentage, break points faced, saved and converted, service and return points. MEASURED (players.pN.measured) are counted upstream, so they include what no point record can yield — ACES AND DOUBLE FAULTS, the first- and second-serve split, winners and unforced errors. Both families name some of the same quantities, computed two entirely different ways; that is a cross-check, not a duplication to collapse. Measured coverage is not uniform and every measured field is optional — an absent field is OMITTED, never zero-filled, so read the keys you are given. Aces and double faults are present across every tour. The serve split and break points saved are present on the main tours and absent on ITF singles. Winners and unforced errors historically appeared on a minority of main-tour matches and have not been delivered upstream since 2026-07-12 (measured 2026-08-17). freshness.derived and freshness.measured each carry their own coverage (live | final | stale | none | diverged; final = the closing figures of a completed match — a finished match cannot be "stale", so its age_seconds is null), as_of, age_seconds and describes — the match state the numbers describe. On diverged the measured VALUES are withheld and freshness.measured_divergence says why; the top-level coverage only summarises the response. none on both returns 200 with null players, not 404 — the match exists and holding nothing for it is the honest answer. THE TWO AGES USE DIFFERENT CLOCKS AND MUST NOT BE COMPARED. The derived age is measured against the newest SCORE row, because between points there is no new score either and wall-clock age would report staleness that does not exist. The measured age is wall clock, because those are fetched on a fixed cadence. Tiebreak games are excluded from the DERIVED family and counted separately; the live record collapses a whole tiebreak onto one entry, so most of its points are lost.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/statistics \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/points

Live per-point events in seq order — the REST catch-up for the WebSocket point stream (ULTRA)

Plan required: ULTRA · operationId: getMatchPoints

The live per-point event stream of one match, in seq order. The WebSocket point frames are best-effort with NO replay, so this endpoint is how you join mid-match and how you recover a dropped connection: subscribe the WS first, then GET with after_seq set to the last seq you hold, then dedup everything by seq — it is per-match, monotonic and never skips a value, so it is the whole reconciliation key. READ THE COVERAGE HONESTLY BEFORE YOU BUILD ON IT. A match's stream is per-point ONLY where a point-level feed covers it: pbp_coverage: "point" means this match has a true per-point stream; "game" means only the snapshot score path covers it — points is empty and that is an answer, not an error. Per-point coverage is never promised slate-wide; ITF and qualifying coverage in particular is partial. quality: "revised" means the upstream feed rewrote an already-served prefix at least once during this match; served rows are never edited (append-only). Each row is the state AFTER a played point: score/sets/games (tiebreaks carry the running count in score with games frozen at the pre-breaker score), its position (set/game/number), server (of the next point), the derived winner (null when not attributable to a single point — never guessed), and ts — CAPTURE time, when our pipeline committed the state, because no feed asserts a per-point clock and we fabricate none. Up to 500 rows per page; after_seq=last_seq fetches the next page while has_more is true. 404 unknown match; 400 points_disabled while the surface is switched off server-side. COMPLETED MATCHES: live capture is inherently partial — the stream serves what arrived while the match ran, and the match-closing point never streams live. Where a measured-complete recorded point sequence of the finished match exists, this endpoint serves THAT instead — the complete sequence projected into the same point-frame shape, love-love opener through the match-closing point, seq contiguous 1..N. The response field basis says which base served the page: live (the persisted live stream rows — every live match, and any completed match without a measured-complete recorded sequence) or reconstruction (the projected complete sequence; quality is clean, every transition measured legal). Completeness beats the partial live capture wholesale — the two sequences are never interleaved (they share no key, so any merge would fabricate an order). On projected frames ts is null on every row: the recorded sequence carries no per-point clock and we fabricate none. after_seq pagination and seq dedup work identically on either basis, but the two bases are different sequences: after a match completes and flips to reconstruction, re-read from after_seq=0 rather than resuming a live cursor into it.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/points \
  -H "Authorization: Bearer twjp_..."

GET /players

Search players by name (FREE)

Plan required: FREE · operationId: searchPlayers

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/players \
  -H "Authorization: Bearer twjp_..."

GET /players/{playerId}

One player's bio + ranking + cached stats (FREE)

Plan required: FREE · operationId: getPlayer

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/players/1104 \
  -H "Authorization: Bearer twjp_..."

GET /tournaments

Tournament catalogue — the id space Match.tournament_id joins (FREE)

Plan required: FREE · operationId: listTournaments

Stable tournament identity, one row per tournament × event type, stable across seasons. city/country come from a curated table and category only where our catalogues agree unambiguously on an exact-name join — each is null otherwise, never derived from the tournament name.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/tournaments \
  -H "Authorization: Bearer twjp_..."

GET /tournaments/{tournamentId}

One tournament by its stable id (FREE)

Plan required: FREE · operationId: getTournament

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/tournaments/{tournamentId} \
  -H "Authorization: Bearer twjp_..."

GET /markets

Match-winner market(s) for a match (PRO)

Plan required: PRO · operationId: listMarkets

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/markets \
  -H "Authorization: Bearer twjp_..."

GET /markets/{matchId}/prices

Market + recent price ticks per side, newest first (PRO)

Plan required: PRO · operationId: getMarketPrices

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/markets/18953/prices \
  -H "Authorization: Bearer twjp_..."

GET /matches/{matchId}/prices

Bare price ticks of the mapped match-winner market, newest first (PRO)

Plan required: PRO · operationId: listMatchPrices

Recent ticks only (no market wrapper). limit caps at 500; minutes bounds the lookback window. 404 when the match has no mapped market.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/matches/18953/prices \
  -H "Authorization: Bearer twjp_..."

GET /history/matches

Completed matches, newest first, with derived winner and tape coverage (BASIC)

Plan required: BASIC · operationId: listCompletedMatches

Requires BASIC on the live API, or any Historical Data API plan (Starter and up — see https://livetennisapi.com/historical-tennis-data-api). All tours, January 2023 → now (deeper results live in the results archive, 1968–2022, at /history/archive/matches). Filter to a date range with from/to, and by tour, draw (singles/doubles), player (either participant) and country — same vocabulary as /matches. Each item carries a tape object saying what point-by-point data we hold for that match, so a whole page can be qualified in one call instead of one request per match. NOTE ?coverage= is applied AFTER the page is cut, so a filtered page is routinely shorter than limit (and may be empty) while later pages still hold matching matches — a short filtered page is not an end-of-data signal; ?points_complete= filters the same way.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/matches \
  -H "Authorization: Bearer twjp_..."

GET /history/coverage

Measured completeness rollup per tour × draw bucket (BASIC)

Plan required: BASIC · operationId: getHistoryCoverage

Requires BASIC on the live API, or any Historical Data API plan (Starter and up — see https://livetennisapi.com/historical-tennis-data-api). The numbers to read BEFORE choosing what to backtest, in one call instead of paging the archive. A PREBUILT snapshot rebuilt nightly right after the completeness ledger reconverges — never computed at read time — so as_of (= built_at) dates every number, and ledger_max_computed_at is the newest underlying per-match measurement. Buckets are atp/wta/challenger/itf/juniors × singles/doubles plus other (team ties, mixed, exhibitions, and matches with no stated event type — counted, never dropped, so the totals cannot lie), derived from the same registries as the tour and draw fields. method states the full measurement rule in one paragraph, so every number carries its own definition. As of 2026-08-18 the headline spread it exposes: 51.1% of ITF singles matches are point-complete on the best basis against 3.5% of ITF doubles — do not extrapolate a completeness rate across a tour group.

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/coverage \
  -H "Authorization: Bearer twjp_..."

GET /history/matches/{matchId}

Per-match tape — point-by-point score + per-point model probabilities (BASIC)

Plan required: BASIC · operationId: getMatchTape

The tape is the point-by-point score sequence we hold for this match — every recorded score row including the model fields win_probability_p1 and danger at that point — plus match metadata and the model profiles produced during the match. The model fields here are part of the paid History product by design, distinct from the ULTRA-gated LIVE model fields. One match per request. Requires BASIC on the live API, or the Historical Data API Starter plan and up. The tape is NOT guaranteed to cover the whole match — check meta.coverage and meta.point_source before backtesting. Rows expanded after the fact from a finished-match point-by-point record carry a null timestamp and null model fields; nothing is ever synthesised. WORKS ON A LIVE MATCH, not only a completed one. The tape is assembled from whatever has been committed so far, so it is how you read the point-by-point history of a match in progress — including games played before you started watching, where we were already watching them. The LIST endpoint is completed-only; get live ids from /matches?status=live. /matches/{matchId}/score is one state; this is the sequence of states.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/matches/18953 \
  -H "Authorization: Bearer twjp_..."

GET /history/archive/matches

Results archive (1968–2022) — deep historical results (BASIC)

Plan required: BASIC · operationId: listArchiveMatches

Completed-match RESULTS from a licensed historical corpus — ATP and WTA main draws, qualifying/challengers and futures tiers, 1968 through 2022. Winner/loser-shaped records with final score, round, seeds, the players' ranks AT THE TIME, and per-match serve statistics where the era recorded them. Requires BASIC on the live API, or any Historical Data API plan (Starter and up). A SEPARATE id space from /matches — archive people are identified by the corpus person id and by name, never by roster player ids — and the archive ends where our own point-by-point coverage begins (2023-01), so no match is ever served from two datasets. event_date is the TOURNAMENT START date, the only date records of this era carry.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/archive/matches \
  -H "Authorization: Bearer twjp_..."

GET /history/archive/matches/{archiveId}

One archive result, with serve statistics where recorded (BASIC)

Plan required: BASIC · operationId: getArchiveMatch

Same entitlement as the archive listing. stats is null for the (mostly pre-1991) rows the source never recorded statistics for — never synthesised.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/archive/matches/{archiveId} \
  -H "Authorization: Bearer twjp_..."

GET /history/archive/players

Archive player bios — hand, DOB, country, height, career-high (BASIC)

Plan required: BASIC · operationId: listArchivePlayers

People of the results archive (1968–2022), in their own id space — id is the corpus person id that archive match rows carry as winner.player_id / loser.player_id, scoped per tour; never a roster id. Career-high rank and the earliest week it was reached are computed offline from the corpus's own weekly ranking tables. Null fields are the era's silence, never guessed. Requires BASIC, or any Historical Data API plan.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/archive/players \
  -H "Authorization: Bearer twjp_..."

GET /history/archive/career

Career aggregates over the results archive, 1968–2022 (BASIC)

Plan required: BASIC · operationId: getArchiveCareer

One player's whole archive career in one response: W-L record (overall, by surface, by level, by year), titles, and the summed serve-stat block with derived ratios. Everything is a sum or a ratio of sums over rows you can fetch individually from /history/archive/matches — nothing is modelled. serve.matches_with_stats states the coverage honestly: the corpus records per-match serve statistics from 1991 only, so a 1970s career has a full W-L record and an empty serve block. Ambiguous name fragments are refused with candidates (same rule as /h2h); an unknown name is a 404. Requires BASIC, or any Historical Data API plan.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/archive/career \
  -H "Authorization: Bearer twjp_..."

GET /h2h

Head-to-head across the results archive (1968–2022) and our own completed matches (2023→now) (BASIC)

Plan required: BASIC · operationId: getHeadToHead

The record between two players, assembled from BOTH halves of the product: the results archive, where the winner is a stored column, and our own completed matches, where the winner is derived from the final recorded state. Names are the keys — archive people have no roster ids. A fragment matching more than one player is refused with the candidate list (400 ambiguous_name), because two people summed into one record is a wrong answer, not a convenience. Totals count meetings with a KNOWN winner; undecided counts the rest. Walkovers and retirements are part of the record, and each meeting carries outcome so you can exclude them. Requires BASIC, or any Historical Data API plan. On ULTRA, a per-player stats block adds serve/return/break-point aggregates over the pairing: archive_serve (serve-side, from 1991) and current (2023+, adding return and break-point conversion, aces and winners), each with meetings_with_stats.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/h2h \
  -H "Authorization: Bearer twjp_..."

GET /history/packages

List the pre-built monthly bulk history packages (PRO)

Plan required: PRO · operationId: listHistoryPackages

Bulk downloads are a heavier product than single-match tape reads. Requires PRO on the live API, or the Historical Data API Pro plan and up, or a one-off package access pass. A key that can read the tape but is not package-entitled receives 403 upgrade_required.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/packages \
  -H "Authorization: Bearer twjp_..."

GET /history/packages/{period}

One monthly package — manifest, or the bulk file itself (PRO)

Plan required: PRO · operationId: getHistoryPackage

Without format returns the package manifest (file set, counts, sha256). With format=jsonl or format=csv streams that file as an attachment. Same entitlement as /history/packages. 404 when the month has not been built yet — list available months first.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/packages/{period} \
  -H "Authorization: Bearer twjp_..."

GET /fixtures

Upcoming scheduled fixtures, earliest first (FREE)

Plan required: FREE · operationId: listFixtures

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/fixtures \
  -H "Authorization: Bearer twjp_..."

GET /usage

Your own usage vs quota (FREE — any tier)

Plan required: FREE · operationId: getUsage

Durable daily usage for the calling key: tier, limits, today's calls (current to the second) and a 30-day history. The per-minute window is on the X-RateLimit-* headers of every response, not here. Calls to this endpoint are quota-exempt — checking your usage never consumes it.

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/usage \
  -H "Authorization: Bearer twjp_..."

GET /rankings

Rankings and Elo — rank-ordered listing (PRO) or per-player as-of records (ULTRA); the as-of Elo tape is ULTRA in both modes

Plan required: PRO · operationId: listRankings

Returns, per ranking system, the newest record effective ON OR BEFORE as_of — never one dated after it. Every other ranking field in this API is the player's CURRENT value joined at read time, so replaying an old match elsewhere shows today's ranks; this endpoint is the point-in-time answer. Systems are never collapsed into a single "rank": ATP/WTA and the ITF circuits carry rank+points, UTR carries a rating with null rank and points because it has neither. meta.coverage.oldest_available gives the earliest date each system can answer for — ITF and UTR observations reach back to 2026-06-01 (append-only per-player history accumulates from 2026-07-29) and nothing earlier can be reconstructed. TWO MODES — with player ids (ULTRA) — the per-player point-in-time records described above. WITHOUT player (PRO) — the FULL published table in rank order for exactly one system, the newest week at or before as_of; rows carry player_name as published and a null player_id for players outside our roster, so the table has no silent holes. utr has no listing (a rating, not a ranking). SYSTEM=UTR — observed ratings, honestly bounded. UTR records are observed from UTR's public search: a rating UTR withholds appears as ABSENT, never as 0, and rating is the only populated value — rank and points are always null. Per-player as-of ONLY — there is deliberately no UTR listing, because a table of only the players we happen to track would be a fake leaderboard. Per-player history accumulates from 2026-07-29; scattered earlier single-snapshot observations reach back to 2026-06-01. Coverage is a deliberate bias, not a roster mirror: the 24-hour sweep targets players with no official rank and no Elo rating (so it skews ITF), and among players active in the last 60 days it holds 931 of 5,606 ITF players (16.6%), 197 of 1,903 Challenger (10.4%), 43 of 573 WTA (7.5%) and 15 of 525 ATP (2.9%) — measured 2026-08-17. SYSTEM=ELO — THE AS-OF ELO TAPE (ULTRA in BOTH modes). Our own computed Elo for 65,622 players on four independent ladders (overall, hard, clay, grass), back to 1877 (ATP) and 1968 (WTA), covering the main tours plus challengers plus the futures tier. It answers what a player was rated BEFORE a given match, which is the only shape a backtest can consume. It is a HISTORICAL TAPE rather than a live leaderboard — the corpus behind it is fixed and no longer receives new results, so meta.coverage.newest_available states the tape's head date on every response (2026-06-15 at publication), and you should read it before treating the table as current. A week's results become effective 14 days after that week begins — strictly after the longest event in tennis — so the failure direction is staleness, never look-ahead. rating is the Elo. rank is LISTING MODE ONLY and is null in per-player mode, because an Elo has no global rank at a past instant until you say which field and which activity window you mean. points is always null. matches is the count on THAT ladder, published so that a rating still near its 1500 cold start is visible rather than inferred. A ladder a player has never played is omitted, never substituted. Ratings are on our own scale, are not comparable with Elo published elsewhere, and do not decay — a surface played only a few weeks a year (grass in particular) moves slowly, so a rising player can sit below an established one for several seasons while beating them. A CURRENT per-player Elo remains free on GET /players/{id}; this is the point-in-time series, the leaderboard and the bulk export. That free rating is sourced differently and sits on a DIFFERENT scale — the two differ by roughly 150 Elo of per-player standard deviation — so never present a rating from one scale against a rating from the other. The Elo listing REQUIRES tour — the ATP and WTA walks are disjoint, so a combined leaderboard would not be comparable — and takes exactly one surface (default overall). elo is never implicit — omitting system returns the official systems only.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/rankings \
  -H "Authorization: Bearer twjp_..."

GET /rally/matches

Charted matches with shot-by-shot data (ULTRA)

Plan required: ULTRA · operationId: listRallyMatches

Charted matches, newest first. RALLY CONSTRUCTION IS THE LAYER BELOW THE TAPE: the tape says what the score became after each point, this says how the point was played. It has its OWN id space. The charted corpus and our own match table are different populations — the corpus reaches back decades and concentrates on the biggest events, while our matches begin when our own collection did. Keying this on our match ids would hide most of it. Ask this endpoint for the authoritative coverage list rather than assuming a match is charted: charting is human work, so coverage is deep, not universal.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/rally/matches \
  -H "Authorization: Bearer twjp_..."

GET /rally/matches/{rallyMatchId}

Rally construction for one charted match (ULTRA)

Plan required: ULTRA · operationId: getRallyMatch

One charted match with its points, in play order. Paged with limit/offset; meta.total is the match's full point count.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/rally/matches/{rallyMatchId} \
  -H "Authorization: Bearer twjp_..."

GET /history/matches/{matchId}/rally

Rally construction by OUR match id (ULTRA)

Plan required: ULTRA · operationId: getMatchRally

Rally construction addressed by OUR match id, resolved through the optional link. Answers 404 {"error":"not_charted"} when we hold the match but nobody charted it — deliberately distinct from "no such match", because most of our matches are not charted and a consumer walking the archive must tell them apart.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/history/matches/18953/rally \
  -H "Authorization: Bearer twjp_..."

GET /charting/players

Career shot-level charting aggregate for one player (ULTRA)

Plan required: ULTRA · operationId: getChartingPlayer

The deepest serve/return profile we hold, from the Match Charting Project: serve placement (deuce/ad × wide/body/T), return depth and outcomes, net and serve-and-volley conversion, clutch break/game/set-point serving and returning, winners and unforced errors by wing, and rally-length and shot-direction tendencies — summed over the player's charted matches. name (min 3 chars) is the key; a fragment matching more than one charted person is refused with the candidate list, and gender=men|women disambiguates. Every field is a raw SUM over the player's Total rows and matches_charted states the sample. COVERAGE IS CURATED — 11,646 charted matches across both tours back to the 1960s, concentrated on the majors, NOT full-slate coverage.

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/charting/players \
  -H "Authorization: Bearer twjp_..."

GET /charting/matches/{chartingMatchId}

One charted match, every stat family for both players (ULTRA)

Plan required: ULTRA · operationId: getChartingMatch

Every Match Charting Project stat family for one charted match, both players, with the per-set split (row/set 1, 2, Total) exactly as charted. chartingMatchId is this product's own id space (1960–2026, mostly matches with no counterpart in the live table).

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/charting/matches/{chartingMatchId} \
  -H "Authorization: Bearer twjp_..."

POST /webhooks

Register an outbound webhook (ULTRA, direct keys only)

Plan required: ULTRA · operationId: createWebhook

We POST the same frames the WebSocket sends to your HTTPS endpoint on every live score commit. Up to 3 webhooks per key (409 webhook_limit past that). The response is the ONLY time the signing secret is shown — store it. Each delivery carries X-LTAPI-Signature (sha256=<hex> — HMAC-SHA256 of the RAW request body with your webhook secret; verify with a constant-time compare), X-LTAPI-Timestamp (Unix seconds at send time — reject stale replays at your edge) and X-LTAPI-Event (the frame type: score, break_point, break_point_result or point). Delivery is best-effort, at-most-once, no replay: one attempt per frame with a ~3s timeout and redirects disabled. Every score frame is the complete current score, so a missed delivery self-corrects on the next commit. A point frame is an EVENT, not a state — a missed one does NOT self-correct; recover it with GET /matches/{matchId}/points?after_seq= and dedup by seq. After 25 consecutive failures the webhook is disabled automatically (enabled:false, last_error set — visible in GET /webhooks); delete and re-register to resume.

Responses

Example

curl https://api.livetennisapi.com/api/public/v1/webhooks \
  -H "Authorization: Bearer twjp_..."

GET /webhooks

List your webhooks (ULTRA, direct keys only; never includes the secret)

Plan required: ULTRA · operationId: listWebhooks

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/webhooks \
  -H "Authorization: Bearer twjp_..."

DELETE /webhooks/{webhookId}

Remove one of your webhooks (ULTRA, direct keys only)

Plan required: ULTRA · operationId: deleteWebhook

Parameters

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/webhooks/{webhookId} \
  -H "Authorization: Bearer twjp_..."

GET /ws-token

Mint a connection token for the high-fan-out push feed (ULTRA)

Plan required: ULTRA · operationId: createWsToken

Returns a short-lived signed token plus the push WebSocket URL and the channel vocabulary: match:{match_id} per-match streams and slate:all for every live score frame. Frames are the same allowlist score objects the polling endpoints return. This is a separate surface from the native /ws feed described above — same ULTRA gate, built for high fan-out (no shared connection ceiling), and the recommended home for continuous/production streaming. The endpoint speaks the **Centrifugo client protocol** (v2, JSON). Easiest path: the official Python (livetennisapi ≥ 1.4.0) and JS (≥ 1.5.0) SDKs ship a built-in PushStream client — no extra dependency. Raw protocol, if you prefer your own client: (1) open a WebSocket to ws_url; (2) send {"connect": {"token": "<token>"}, "id": 1} — the token goes INSIDE this JSON frame, never as a raw first message; (3) subscribe per channel with {"subscribe": {"channel": "slate:all"}, "id": 2}; (4) publications arrive as {"push": {"channel": ..., "pub": {"data": <frame>}}}; (5) the server's heartbeat is an empty JSON object {} — reply with {} promptly or you will be disconnected. Messages may batch several newline-delimited JSON objects. Tokens are short-lived and the connection closes around token expiry: mint a fresh token on EVERY reconnect and re-subscribe. The channels object lists only channels that will actually deliver for your key right now (a channel name in this response is a promise). Where enabled server-side, additional channel families appear: point:match:{match_id} / point:slate (per-point events), listed — as point_match / point_slate in the vocabulary — only for keys whose plan carries the point surface, and signal:match:{match_id} / signal:slate (derived break_point, break_point_result and divergence events). A family absent from the response will not deliver for your key right now. Deliberately separate channels: a slate:all subscriber asked for score states and never starts receiving events unasked. Point and signal frames are events, not states — a missed point does NOT self-correct on the next frame; recover it via GET /matches/{matchId}/points?after_seq= and dedup by seq.

Responses

Response fields

Example

curl https://api.livetennisapi.com/api/public/v1/ws-token \
  -H "Authorization: Bearer twjp_..."