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:

API token — for your own tournaments. Create it in the app:

  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 and every public tournament, sets results in your own tournaments and manages your webhooks.

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. 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 tournament is private and the key does not belong to its organizer
  • 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 TOURNAMENT_NOT_PUBLIC / 403 TOURNAMENT_FINISHED / 400 TOO_MANY_SUBSCRIPTIONS — 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