> For the complete documentation index, see [llms.txt](https://docs.matchplay.events/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.matchplay.events/tournaments-api.md).

# Tournaments API

Tournaments are the basic building blocks of Match Play. The tournament object contains basic tournament data like the name, date and configuration options, but also optionally the players and arenas.

## Get tournament

```http
GET /api/tournaments/{tournamentId}
```

Get details for a single tournament, optionally include players, arenas and other details in the response.

**Query params**

| Name                                  | Description                                                                 |
| ------------------------------------- | --------------------------------------------------------------------------- |
| `includePlayers` (boolean)            | Set to `true` to include players                                            |
| `includeArenas` (boolean)             | Set to `true` to include arenas                                             |
| `includeBanks` (boolean)              | Set to `true` to include banks                                              |
| `includeScorekeepers` (boolean)       | Set to `true` to include scorekeepers                                       |
| `includeLocation` (boolean)           | Set to `true` to include location                                           |
| `includeEntryConfiguration` (boolean) | Set to `true` to include the entry configuration for best game tournaments  |
| `includeRsvpConfiguration` (boolean)  | Set to `true` to include RSVP configuration                                 |
| `includeLinkedTournaments` (boolean)  | Set to `true` to include linked tournaments such as qualifying and playoffs |
| `includeEvent` (boolean)              | Set to `true` to include the event this tournament is part of               |
| `includeShortcut` (boolean)           | Set to `true` to include custom link                                        |
| `includeSeries` (boolean)             | Set to `true` to include series                                             |

## Get tournament list

```http
GET /api/tournaments
```

Retrieve a list of tournaments. You can filter the list using various parameters. **Note: Do not attempt to iterate over thousands of tournaments using this endpoint.** Get in touch if you are looking to download large amounts of data.

**Query params**

| Name               | Description                                                                         |
| ------------------ | ----------------------------------------------------------------------------------- |
| `page` (integer)   | Which page of results to get                                                        |
| `limit` (integer)  | Number of results per page. Defaults to `25`, max is `100`                          |
| `owner` (integer)  | Filter to tournaments created by this user                                          |
| `played` (integer) | Filter to tournaments played by this user                                           |
| `status` (string)  | Filter to tournaments in this state. Possible values: `planned, started, completed` |
| `series` (integer) | Filter to tournaments belonging to this series                                      |

## Get tournament standings

```http
GET /api/tournaments/{tournamentId}/standings
```

Retrieve the tournament standings. **Do not request this endpoint more frequently than once every 15 seconds for tournaments that are in progress.** For completed tournaments only fetch standings once. They will never change.

## Get WPPR estimate

```http
POST /api/ifpa/wppr-estimator
```

Generate a WPPR estimate for a tournament or a series.

**Post data**

| Name                     | Description                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------- |
| `tournamentId` (integer) | Tournament to generate estimate for. Provide either this or a series id but not both. |
| `seriesId` (integer)     | Series to generate estimate for. Provide either this or a tournament id but not both. |

## Get tournament arena summary

```http
GET /api/tournaments/{tournamentId}/summary/arenas
```

One entry per arena in the tournament with data on how many times that arena was played. This summary is only available once the tournament has been completed.

**Query params**

| Name             | Description                  |
| ---------------- | ---------------------------- |
| `page` (integer) | Which page of results to get |

## Get tournament player/arena summary

```http
GET /api/tournaments/{tournamentId}/summary/player-arenas
```

One entry per player/arena combination in the tournament with data on how many times the player played each arena and how many wins & losses the player had. This summary is only available once the tournament has been completed.

**Query params**

| Name             | Description                  |
| ---------------- | ---------------------------- |
| `page` (integer) | Which page of results to get |

## Get tournament player/opponent/arena summary

```http
GET /api/tournaments/{tournamentId}/summary/matches
```

One entry per player/opponent/arena combination in the tournament with data on how many times the player played that opponent on each arena and how many wins & losses the player had. This summary is only available once the tournament has been completed.

The data from this endpoint is intentionally duplicated. If Player A and Player B played Machine X there will be both a `playerA-playerB-machineX` entry and a `playerB-playerA-machineX`.

**Query params**

| Name             | Description                  |
| ---------------- | ---------------------------- |
| `page` (integer) | Which page of results to get |