Quick Start

Get up and running with the Tournament Suite Data API in 5 minutes.

What the Data API is

The public, X-API-Key-authenticated REST surface is the Data API, mounted under /api/v1/data/*. It is read-only — you can list and retrieve tournaments, brackets, matches, match events, player stats, and teams. There is no way to create or modify a tournament, and no webhook registration, using an API key. See Creating and managing tournaments and Setting up a webhook below for the flows that actually cover those actions.

Two extra gates apply on top of a valid key:

• Scopes — every endpoint requires a specific scope on the key (for example read:tournaments). See Authorization & Scopes.
• Plan entitlement — your project's plan must include the Developer API capability. A valid, correctly-scoped key on a plan without it still gets a 403.

Prerequisites

• A Tournament Suite organizer account (Sign up)
• A project on a plan that includes the Developer API capability
• An API key generated from your project's Settings → Developer → API Keys, with the scopes you need (read:tournaments, read:matches, read:player_stats, read:teams, as applicable)

1. Make your first request

List tournaments in your project (requires the read:tournaments scope):

curl https://api.tournamentsuite.com/api/v1/data/tournaments \
  -H "X-API-Key: YOUR_API_KEY"

Expected response:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Summer Open 2026",
      "status": "PUBLISHED",
      "startDate": "2026-07-01T00:00:00Z",
      "maxParticipants": 64,
      "currentParticipants": 48
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

2. Get a tournament by ID

Also requires read:tournaments:

curl https://api.tournamentsuite.com/api/v1/data/tournaments/TOURNAMENT_ID \
  -H "X-API-Key: YOUR_API_KEY"

3. Retrieve the bracket

Once a tournament has started, fetch the full bracket (also read:tournaments):

curl https://api.tournamentsuite.com/api/v1/data/tournaments/TOURNAMENT_ID/bracket \
  -H "X-API-Key: YOUR_API_KEY"

Creating and managing tournaments

The Data API does not create or edit tournaments — it is a read-only reporting surface. Tournament creation, editing, and lifecycle management (starting a bracket, publishing, etc.) happen through the organizer dashboard at Projects → your project → Tournaments, authenticated as a signed-in organizer, not with an API key. If you need to automate tournament creation from your own systems, do it through an authenticated session in that dashboard flow rather than the public API key.

4. Set up a webhook

Webhook subscriptions are also managed as a project-owner/admin, not with an API key. Register one either from your project's Settings → Developer → Webhooks, or by calling the project-scoped endpoint with your organizer session's access token:

curl -X POST https://api.tournamentsuite.com/api/v1/projects/PROJECT_ID/developer/webhooks \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/tournamentsuite",
    "events": ["tournament.started", "match.completed"]
  }'

This route requires an OWNER or ADMIN role on the project — it does not accept an X-API-Key. See Webhooks for the full setup guide, including signature verification.

Using TypeScript

const BASE_URL = 'https://api.tournamentsuite.com/api/v1/data';
const API_KEY = process.env.TOURNAMENTSUITE_API_KEY!;

// Requires the `read:tournaments` scope on the key.
async function getTournaments() {
  const response = await fetch(`${BASE_URL}/tournaments`, {
    headers: { 'X-API-Key': API_KEY },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  return response.json();
}

Using Python

import requests
import os

BASE_URL = 'https://api.tournamentsuite.com/api/v1/data'
headers = {'X-API-Key': os.environ['TOURNAMENTSUITE_API_KEY']}

# Requires the `read:tournaments` scope on the key.
response = requests.get(f'{BASE_URL}/tournaments', headers=headers)
response.raise_for_status()
data = response.json()
print(data['data'])

Common errors

Next steps

• Authentication — API keys vs. OAuth 2
• Authorization & Scopes — scopes required per endpoint
• Core Concepts — understand the data model
• Endpoint Catalog — full list of available endpoints
• Webhooks — react to events in real time