DocumentationTeams and players
Volleyball teams API
GET/v1/teams
Clubs, national teams and beach pairs found by name, including the other names a team has played under. Each comes back once, under one id.
Parameters
Parameters marked required must be sent; the rest are optional.
| Name | Type | What it does | Example |
|---|---|---|---|
q | text | Part of the name, 2 to 80 characters. Required. | Korea |
discipline | enum | One of indoor, beach. | indoor |
gender | enum | One of men, women, mixed. | men |
country | text | A two-letter country code, like IT: teams that play for that country. | |
page | int | Page number, from 1. Adds totals to meta. | 2 |
per_page | int | Rows a page, 1 to 200. 50 when not sent. | 200 |
cursor | string | The next_cursor from the last answer. Send it alone. |
Request
Send your key in the Authorization header as a Bearer token, or in X-API-Key. A key in the address is refused, so it never ends up in a log.
# Teams and beach pairs, found by name curl "https://api.volleyballapi.com/v1/teams?q=Korea" \ -H "Authorization: Bearer $VBA_KEY"
$q = http_build_query(['q' => 'Korea']); $ch = curl_init('https://api.volleyballapi.com/v1/teams?' . $q); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('VBA_KEY')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true); print_r($res['data']);
import os, requests r = requests.get( "https://api.volleyballapi.com/v1/teams", params={"q": "Korea"}, headers={"Authorization": f"Bearer {os.environ['VBA_KEY']}"}, ) print(r.json()["data"])
const res = await fetch("https://api.volleyballapi.com/v1/teams?q=Korea", { headers: { "X-API-Key": process.env.VBA_KEY }, }); const { data, meta } = await res.json();
Response
Every answer is data plus meta. A first call with page adds totals to meta; a call with cursor carries only the next cursor, which is quicker over long ranges. This is a real answer to the request above, counted 2026-10-12, with long lists cut short.
{
"data": [
{
"id": "tm_rk2hqqay",
"name": "Korea",
"discipline": "indoor",
"gender": "women",
"kind": "national",
"federation": "KOR",
"country_code": "KR"
},
{
"id": "tm_fqsfp7d4",
"name": "Korea",
"discipline": "indoor",
"gender": "men",
"kind": "national",
"federation": "KOR",
"country_code": "KR"
},
...
],
"meta": {
"plan": "Complete",
"count": 16,
"next_cursor": null,
"page": 1,
"per_page": 50,
"total": 16,
"total_pages": 1,
"next_page": null,
"prev_page": null
}
}Fields
| Field | Type | What it holds |
|---|---|---|
id | string | Stable team id, tm_ |
name | string | The name it plays under |
discipline | enum | indoor or beach |
gender | enum | men, women or mixed |
kind | enum | club, national or pair |
federation | string | Three-letter federation code, for national teams and pairs |
country_code | string | Two-letter country the team plays for, or null where it is not certain |
Errors
Errors come back as {"error": {"code", "message", "docs"}}, with plan and pricing added when a plan would answer. Every error.
| HTTP | Code | When |
|---|---|---|
| 400 | bad_request | A value of the wrong shape, or per_page outside 1 to 200, or a required parameter left out |
| 401 | unauthorized | No key, or a key that is not known or was revoked |
| 422 | unknown_parameter | A parameter this endpoint does not take; the answer lists the ones it does |
| 429 | rate_limited | Too many calls this minute; Retry-After says when to try again |
| 429 | quota_exceeded | The day's or month's allowance is used; the answer says when it resets |
Try it
Fill in what you need; the request is built as you type. Paste your key to run it here, straight against the API.