Skip to main content
Documentation

API Overview

Programmatic access to Tabletop League. Part of the API is live today; the rest is planned.

API status

Live today: the public competitions API (open and in-progress competitions and their fighter and map pools, no key needed), the Personal API (your own matches and stats — early access, entitlement-gated) and the public aggregate statistics exports (character win rates and matchups as CSV, available to any signed-in user). Explore every live endpoint in the interactive reference. Everything under "Planned" below is not built yet.

Base URL

https://tabletopleague.com/api/v1

Authentication

The public competitions endpoints need no authentication at all: no key, no session, no headers.

Every other live endpoint authenticates with a personal API key (Authorization: Bearer ttl_user_…) or a logged-in session cookie. Keys have no scopes and only ever expose your own data or public aggregates. See Authentication.

Response format

JSON endpoints wrap successful responses in a success / data / _meta envelope:

{
  "success": true,
  "data": {},
  "_meta": {
    "request_id": "55f8c764-b324-42e1-ac9c-fe385057278d",
    "timestamp": "2026-05-19T03:19:19.645Z",
    "terms_url": "/api-terms"
  }
}

Errors use the same envelope with success: false:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found",
    "details": {}
  },
  "_meta": {}
}

The statistics exports are the exception — they return a CSV file, not JSON. See Public statistics exports.

Live endpoints

Public competitions — /api/v1/public/competitions*

The competitions that are open for registration or in progress, and one competition's fighter and map pool, as JSON. The list can be filtered by game, by organizer (?organization=<org slug>, for example every official event run by one organization) and by status. No key or account needed. Full reference: Public competitions API.

Personal API — /api/v1/me/*

Your own profile, career stats, per-fighter and per-opponent breakdowns, plus key management. Early access (requires the api.personal.read entitlement). Full reference: Personal API.

Public statistics exports — /api/v1/public/hero-stats*

Aggregate character win rates and head-to-head matchup rates across all recorded 1v1 games, as CSV. Available to any signed-in user; no entitlement required. Public posting requires attribution. Full reference: Public statistics exports.

Planned

These are on the roadmap and not yet available:

  • Competition results — standings and match results (listing competitions and their pools is live)
  • Players — public profiles, stats, and match history
  • Matches — create and fetch matches from your own tools
  • Webhooks — subscribe to competition and match events
  • Overlays — stream graphics and live updates

Machine-readable spec

The live surface is documented as OpenAPI 3.1:

Get notified

Want to know when more of the API opens up — or to enable the Personal API early access on your account? Contact us at api@tabletopleague.com.

Documentation sections