API v1

REST API Reference

Build integrations, power live scoreboards, and sync tournament data with the ThrowDown API.

Get an API Key

Generate a key in your org settings under the API Keys section.

Make a Request

Pass your key as a Bearer token in the Authorization header.

Go Live

Embed live brackets, power walk-in kiosks, or build custom integrations.

Authentication

All API requests require a valid API key passed in the Authorization header.

curl https://throwdown-darts.com/api/v1/events \
  -H "Authorization: Bearer td_live_your_api_key_here"

Read-only key

Access all GET endpoints. Cannot create or modify data.

Read + Write key

Full access including POST and PATCH operations.

Response Format

All responses are JSON with a consistent structure. Successful responses return a data field. Errors return an error field.

Success

{
  "data": { ... },
  "meta": { "timestamp": 1715300000 }
}

Error

{
  "error": {
    "code": "not_found",
    "message": "Event not found"
  }
}

Pagination

List endpoints support pagination via page and page_size query parameters. Maximum page size is 200. Default is 50.

GET /api/v1/players?page=2&page_size=25

Organization

Retrieve information about your organization.

Events

Manage tournaments and events for your organization.

Games

Games within an event (e.g., Open Singles 501, Cricket Doubles).

Brackets

Full bracket structure with rounds, matches, and scores.

Participants

Players entered into a specific game bracket.

Rounds

Query rounds and matches with optional filtering.

Registrations

Event registrations — sign players up and manage check-in.

Players

Player roster for your organization.

Built-in Integrations

ThrowDown ships two features that consume the public API — use them directly or as reference implementations for your own integrations.

Live Bracket Embed

Embeddable iframe widget that polls the brackets endpoint every 12 seconds. Drop it into any website to show real-time match results.

<iframe
  src="https://throwdown-darts.com/embed/{eventId}/{gameId}?key=YOUR_API_KEY"
  width="100%"
  height="600"
  frameborder="0"
></iframe>

Uses: GET /api/v1/org, GET /api/v1/events/{eventId}/games/{gameId}/brackets

Walk-in Kiosk

Touch-optimized registration kiosk for venue tablets. Players search/create their profile and register for games on-site.

https://throwdown-darts.com/kiosk/{eventId}?key=YOUR_API_KEY

Uses: GET /api/v1/org, GET /api/v1/events, GET /api/v1/players, POST /api/v1/players, POST /api/v1/events/{eventId}/registrations

Quick Start Example

Fetch your upcoming events and display live bracket data:

const API_KEY = "td_live_your_key_here";
const BASE = "https://throwdown-darts.com/api/v1";

// List active events
const events = await fetch(`${BASE}/events?status=active`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
}).then(r => r.json());

// Get bracket for the first game of the first event
const eventId = events.data[0].id;
const games = await fetch(`${BASE}/events/${eventId}/games`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
}).then(r => r.json());

const bracket = await fetch(
  `${BASE}/events/${eventId}/games/${games.data[0].id}/brackets`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
).then(r => r.json());

console.log(bracket.data.rounds);