Skip to main content
POST
/
leagues
curl -X POST https://teambattles.gg/api/v1/leagues \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"search": "competitive", "limit": 12}'

{
  "leagues": [
    {
      "id": "<string>",
      "name": "<string>",
      "slug": "<string>",
      "description": "<string>",
      "status": "<string>"
    }
  ],
  "count": 123,
  "pagination": {},
  "timestamp": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://teambattles.gg/docs/llms.txt

Use this file to discover all available pages before exploring further.

curl -X POST https://teambattles.gg/api/v1/leagues \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"search": "competitive", "limit": 12}'

​
Permission Required

This endpoint requires the leagues.league_public permission on your API key.

​
What’s Returned

Returns a paginated list of public leagues with optional search and game filtering. Each league includes its name, slug, description, status, and other public metadata.

​
Filtering Options

Use the search parameter to search leagues by name or description.

​
Game Filtering

Use gameId to filter leagues associated with a specific game.

​
Request Body

ParameterTypeRequiredDescription
searchstringNoSearch term to filter leagues by name
gameIdstringNoFilter by game ID
pagenumberNoPage number, starting from 1 (default 1)
limitnumberNoResults per page (1-50, default 12)

​
Pagination

Results are paginated with a default of 12 leagues per page (maximum 50). Use the page parameter to navigate through results. The response includes a pagination object with page metadata.

​
Common Use Cases

​
Search for Leagues by Name

{
	"search": "Call of Duty",
	"limit": 12
}

​
Filter by Game

{
	"gameId": "call_of_duty",
	"limit": 25
}

​
Paginate Through All Leagues

{
	"page": 2,
	"limit": 50
}

Authorizations

​
Authorization
string
header
required

API key authentication. Generate an API key from Settings > Developer in the TeamBattles app. Format: tb_xxxxxxxx...

Body

application/json

Optional search, game filter, and pagination options

​
search
string

Search term to filter leagues by name

​
gameId
string

Filter by game ID

​
page
integer
default:1

Page number, starting from 1

Required range: x >= 1
​
limit
integer
default:12

Maximum number of leagues to return per page (1-50)

Required range: 1 <= x <= 50

Response

Successful response

​
leagues
object[]
​
count
integer

Number of leagues returned in this page

​
pagination
object

Pagination metadata

​
timestamp
string<date-time>

Response timestamp (ISO 8601)