---
title: "Discover public leagues"
method: POST
path: "/leagues"
tags: ["League Discovery"]
---

# Discover public leagues

`POST /leagues`

Returns a paginated list of public leagues with optional search and game filtering. Requires the leagues.league_public:read permission.

## Request body

- DiscoverLeaguesRequestBody — Filters and offset pagination for discovering leagues.
  - `search` string — Free-text search across league names.
  - `gameId` string — Filter to leagues that include this game id.
  - `page` integer — 1-based page number. Defaults to 1.
  - `limit` integer — Page size (1-50). Defaults to 12.

## Response `200`

Legacy offset-paginated result (page/limit based).

- object
  - `leagues` LeagueSummary[], required
    - `id` string, required — League ID.
    - `name` string, required — League display name.
    - `slug` string, required — URL-friendly league identifier.
    - `description` string, required — League description.
    - `avatarUrl` string, nullable, required — League avatar image URL.
    - `bannerUrl` string, nullable, required — League banner image URL.
    - `isVerified` boolean, required — Whether the league is verified.
    - `isFeatured` boolean, required — Whether the league is featured.
    - `games` object[], required — Games associated with the league.
    - `teamCount` integer, required — Number of teams in the league.
    - `seasonStatus` 'active' | 'upcoming' | 'none', required — Aggregate season state across the league's games.
    - `createdAt` number, required — Creation timestamp (epoch milliseconds).
    - `status` string — League status.
  - `count` integer, required
  - `pagination` object, required
    - `page` integer, required
    - `limit` integer, required
    - `total` integer, required
    - `totalPages` integer, required
  - `timestamp` string, required

## Other responses

- `400` — Bad request (invalid body, cursor, limit, or date).
- `401` — Missing or invalid API key.
- `403` — API key lacks the required permission.

---

[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/revisions/2ffe8fb53b7d/schema)