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" }
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)