Skip to content
tournament.iotournament.io Manual

Getting started

Welcome to the Tournament.app Public API documentation. This API allows you to access tournament data from our platform, enabling you to integrate Tournament.app functionality into your own applications or services.

Introduction

Section titled “Introduction”

The Tournament.app Public API provides programmatic access to tournament information, including organizers, tournament details, courts, and matches. This API is designed for end-users who want to retrieve data from tournaments they have created or have access to on the Tournament.app platform.

The API uses one name for each concept regardless of the sport: participants are entries, tables are courts, the ranking is standings. The glossary maps these names to the terms of the Kickertool manual.

Supported Apps

Section titled “Supported Apps”

Currently this API is only supported by the Kickertool V3 Alpha: https://app.kickertool3.de

Authentication

Section titled “Authentication”

Every request needs a key in the Authorization header. There are two kinds:

Private API token

Section titled “Private API token”
  1. Log in to your Tournament.app account
  2. Click on your profile picture in the bottom left corner
  3. Navigate to “Settings”
  4. Select the “API” section
  5. Generate your API token

An API token reads your own tournaments, sets results in your own tournaments and manages your webhooks.

Public API key

Section titled “Public API key”

for reading public tournaments of other organizers, for example for stream overlays, notification devices or analytics. Public tournaments are the ones organizers share on their result page (tournament option “Share on result page”). A public API key reads public tournaments, can subscribe its own webhooks to them, and is tied to one sport. It cannot set results. Start with GET /organizers to find the venue or club you are interested in, then list its tournaments. If you have an account but want to read other organizers’ public tournaments, you still need a public API key. To get a key, send an e-mail to hello@tournament.io with:

  • your name
  • the name of your app
  • a short description of what it does
  • the e-mail address the key should go to
  • the sport (table_soccer, petanque, darts, cornhole, table_tennis)

Both kinds are sent the same way:

Authorization: Bearer <YOUR_KEY>

Errors

Section titled “Errors”
  • 401 ACCESS_TOKEN_MISSING — no Authorization header
  • 401 ACCESS_TOKEN_INVALID — unknown or revoked key
  • 400 Bad Request — invalid query or body, e.g. limit outside 1–100
  • 403 FORBIDDEN — the key may not read this tournament: an API token reads only the tournaments of its own account, a public API key only public ones
  • 403 SCOPE_MISSING — the key may not do this (e.g. a public API key setting a result)
  • 403 ACCOUNT_TOKEN_REQUIRED — the endpoint needs an API token, not a public API key
  • 403 PUBLIC_API_KEY_REQUIRED — the endpoint is only for public API keys, not for API tokens (e.g. GET /organizers)
  • 403 TOURNAMENT_NOT_PUBLIC / 403 TOURNAMENT_FINISHED / 400 TOO_MANY_SUBSCRIPTIONS / 400 SUBSCRIPTION_NOT_NEEDED — webhook subscriptions, see Webhooks
  • 429 Too Many Requests — see rate limit

Rate limit

Section titled “Rate limit”

GET requests are limited to 120 requests per minute per key. Poll courts or matches no more often than every few seconds.

Base URL

Section titled “Base URL”

All API requests should be made to:

https://api.tournament.io/v1/public