League Dispatcher API (v1)

The League Dispatcher API runs a league's game days: check players in, propose and dispatch games, record results, manage the roster, tournaments, seasons and court bookings.

Experimental: the API and its SDKs may change in any release while they are experimental.

Base URL and authentication

Send requests to https://api.leaguedispatcher.com/v1 with a league API token in the X-Api-Key header. A league administrator creates tokens in the app under Setup > API access (paid plans). A token belongs to one league and carries the permissions chosen when it was created; an operation the token is not allowed to call returns 403.

SDKs

Official SDKs for TypeScript, Python and .NET are generated from this description. Install them and see samples at leaguedispatcher.com/en/developers.

Errors

Errors return an ErrorResponse with a machine-readable code (see the ErrorCode values) and a message. Too many requests return 429 with a Retry-After header (seconds).

Retries

A request whose answer was lost (timeout, dropped connection) can be sent again without doing the action twice:

  • Operations that create something (POST /players, /tournaments, /tournaments/{tournamentId}/teams, /tournaments/{tournamentId}/teams/randomize, /seasons, /exports) and the start and finish of the game day take an Idempotency-Key header. Send a new random value (a UUID) for each action and the same value on every retry of it: the repeat answers what the first call did. Use a key for one action only; a malformed key returns 400 (INVALID_FORMAT).
  • Dispatching a game, adding players to a court, starting or finishing a tournament and ending the season recognize their own repeat from the state the first call left, and answer it. Finishing a game does too when it carries gameStartTime (the court's lastPlayDate as read): resend the same value. Without it, a retry can finish the court's next game (a continued series).

Concurrent changes

Several devices change a league at the same time. Operations that could overwrite someone else's change take the version they were based on and refuse the request with 409 when it is outdated:

  • PUT /players takes the rosterVersion returned by GET /players and GET /gameDay (ROSTER_CHANGED). Prefer the single-player operations (POST /players, PUT and DELETE /players/{playerId}) when you change one player.
  • POST /gameDay/courts/{courtId}/game/finish takes the court's lastPlayDate as gameStartTime.

Webhooks

Webhooks receive every league event with the same payload as the app's live updates; GET /webhooks/sample returns an example for each event type.

Servers
https://api.leaguedispatcher.com/v1
https://api-dev.leaguedispatcher.com/v1