# Getting started

:::caution
The document and the API is still work in progress. It only works with Version 3 of Kickertool.
:::

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

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](/kickertool/glossary/) maps these names to the terms of the Kickertool manual.

### Supported Apps
Currently this API is only supported by the Kickertool V3 Alpha: [https://app.kickertool3.de](https://app.kickertool3.de)

### 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

- `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

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

### Base URL

All API requests should be made to:

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