---
title: "Discover public tournaments"
method: POST
path: "/tournaments/discover"
tags: ["Tournament Discovery"]
---

# Discover public tournaments

`POST /tournaments/discover`

Returns publicly listed tournaments, featured entries first. Unlisted and draft tournaments are never included, whoever asks. Requires tournaments.tournament_public:read.

## Request body

- TournamentDiscoverBody — Filters for public tournament discovery.
  - `search` string — Case-insensitive name substring. Ignored below 2 characters.
  - `gameId` string — Filter to a single game by Convex ID.
  - `format` 'SINGLE_ELIMINATION' | 'DOUBLE_ELIMINATION' | 'ROUND_ROBIN' | 'SWISS' — Bracket format of a tournament.
  - `status` 'DRAFT' | 'REGISTRATION_OPEN' | 'REGISTRATION_CLOSED' | 'IN_PROGRESS' | 'COMPLETED' | 'CANCELLED' — Lifecycle status of a tournament.
  - `page` integer — 1-based page number.
  - `limit` integer — Page size, 1-50.

## Response `200`

A page of publicly listed tournaments.

- TournamentDiscoverPage — A page of publicly listed tournaments, featured entries first.
  - `tournaments` TournamentSummary[], required — Tournaments on this page.
    - `id` string, required — Tournament ID.
    - `name` string, required — Tournament display name.
    - `slug` string, required — URL-friendly tournament identifier.
    - `description` string — Short tournament description.
    - `format` 'SINGLE_ELIMINATION' | 'DOUBLE_ELIMINATION' | 'ROUND_ROBIN' | 'SWISS', required — Bracket format of a tournament.
    - `status` 'DRAFT' | 'REGISTRATION_OPEN' | 'REGISTRATION_CLOSED' | 'IN_PROGRESS' | 'COMPLETED' | 'CANCELLED', required — Lifecycle status of a tournament.
    - `isFeatured` boolean, required — Whether the featured placement is live at request time.
    - `participantCount` integer, required — Current number of participants.
    - `maxParticipants` integer, required — Participant cap.
    - `startsAt` number — Scheduled start (epoch milliseconds).
    - `prizePool` number — Total prize pool.
    - `prizeCurrency` string — ISO currency code of the pool.
    - `bannerUrl` string, nullable — Banner image URL.
    - `logoUrl` string, nullable — Logo image URL.
    - `game` object, nullable, required — Game summary, or null if the game row is missing.
  - `count` integer, required — Number of tournaments in this page.
  - `total` integer, required — Total tournaments matching the filters.
  - `page` integer, required — Echo of the requested 1-based page.
  - `limit` integer, required — Echo of the applied page size.
  - `timestamp` string, required — Response generation time (ISO 8601).

## Other responses

- `400` — Bad request (invalid body, cursor, limit, or date).
- `401` — Missing or invalid API key.
- `403` — API key lacks the required permission.
- `429` — Rate limited.
- `500` — Internal server error.

---

[API](https://skmtc.net/teambattles/apis/teambattles-api.md) · [All operations](https://skmtc.net/teambattles/apis/teambattles-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/teambattles/teambattles-api/versions/2ffe8fb53b7d/schema)