# Volleyball API

> Live scores, results, set scores, rally-by-rally points and player figures for indoor and beach volleyball since 2001, as JSON over HTTPS, with an MCP server for AI agents.

Base URL: https://api.volleyballapi.com/v1. Send the key as `Authorization: Bearer <key>` or `X-API-Key: <key>`; keys in the address are refused. Every answer is `{"data", "meta"}`, or `{"error": {"code", "message", "docs"}}`. Lists take page and per_page (up to 200) or cursor. Ids are stable strings: mt_ matches, cp_ competitions, tm_ teams, pl_ players.

## Endpoints

- [GET /v1/usage](https://volleyballapi.com/documentation/usage): Your plan, your calls today and this month, your limits and the dates you can read. Plans: Free key, Live, Archive, Complete.
- [GET /v1/matches/live](https://volleyballapi.com/documentation/live): Every match being played now, with the running set scores. Plans: Live, Complete.
- [GET /v1/results/yesterday](https://volleyballapi.com/documentation/results-yesterday): Yesterday's finished matches. Plans: Free key, Live, Archive, Complete.
- [GET /v1/matches](https://volleyballapi.com/documentation/matches): Matches on a day or between two days, filtered by discipline, gender, status, competition or team. Plans: Free key, Live, Archive, Complete.
- [GET /v1/matches/{id}/points](https://volleyballapi.com/documentation/match-points): Every rally of every set: the score after it, who won it and who served. Plans: Live, Archive, Complete.
- [GET /v1/matches/{id}/players](https://volleyballapi.com/documentation/match-players): Per-player figures for the match: points, serve, reception, attack and block. Plans: Archive, Complete.
- [GET /v1/matches/{id}/lineups](https://volleyballapi.com/documentation/match-lineups): Starting six by court zone for every set, the players who came on, and both head coaches. Plans: Archive, Complete.
- [GET /v1/export/matches](https://volleyballapi.com/documentation/export-matches): Every match between two days in one call, with sets, venue, officials and coaches (up to 184 days). Plans: Complete.
- [GET /v1/export/lineups](https://volleyballapi.com/documentation/export-lineups): Every lineup between two days in one call: starting six by zone, players who came on, coaches (up to 92 days). Plans: Complete.
- [GET /v1/export/points](https://volleyballapi.com/documentation/export-points): Every rally of every match between two days in one call (up to 14 days). Plans: Complete.
- [GET /v1/matches/{id}](https://volleyballapi.com/documentation/match): One match: teams, result, every set, duration, venue, spectators and referees. Plans: Free key, Live, Archive, Complete.
- [GET /v1/competitions](https://volleyballapi.com/documentation/competitions): Competitions, newest first, filtered by discipline, gender, season or name. Plans: Free key, Live, Archive, Complete.
- [GET /v1/competitions/{id}/matches](https://volleyballapi.com/documentation/competition-matches): A competition's matches. Plans: Free key, Live, Archive, Complete.
- [GET /v1/competitions/{id}/standings](https://volleyballapi.com/documentation/competition-standings): League tables for a competition, one per pool, worked out from its results. Plans: Free key, Live, Archive, Complete.
- [GET /v1/competitions/{id}](https://volleyballapi.com/documentation/competition): One competition, with its dates and match count. Plans: Free key, Live, Archive, Complete.
- [GET /v1/teams](https://volleyballapi.com/documentation/teams): Teams and beach pairs, found by name. Plans: Free key, Live, Archive, Complete.
- [GET /v1/teams/{id}/matches](https://volleyballapi.com/documentation/team-matches): A team's matches, newest first. Plans: Free key, Live, Archive, Complete.
- [GET /v1/teams/{id}](https://volleyballapi.com/documentation/team): One team: its name, kind, federation and players. Plans: Free key, Live, Archive, Complete.
- [GET /v1/players](https://volleyballapi.com/documentation/players): Players, found by name. Plans: Free key, Live, Archive, Complete.
- [GET /v1/players/{id}](https://volleyballapi.com/documentation/player): One player, the teams they have played for and their career, competition by competition. Plans: Free key, Live, Archive, Complete.
- [GET /v1/head-to-head](https://volleyballapi.com/documentation/head-to-head): Every meeting of two teams, with the record between them. Plans: Live, Archive, Complete.

## Guides

- [Introduction](https://volleyballapi.com/documentation)
- [Authentication](https://volleyballapi.com/documentation/authentication)
- [Responses and errors](https://volleyballapi.com/documentation/errors)
- [Pagination](https://volleyballapi.com/documentation/pagination)
- [Plans and limits](https://volleyballapi.com/documentation/plans)
- [Ids that never change](https://volleyballapi.com/documentation/ids)
- [MCP for AI agents](https://volleyballapi.com/documentation/mcp)

## Complete reference

- [Full manual, one file](https://volleyballapi.com/documentation/manual.md): every endpoint, parameter, sample response and guide in a single markdown document.
- [OpenAPI](https://volleyballapi.com/openapi.json): machine-readable API description.
- [MCP server](https://volleyballapi.com/documentation/mcp): Model Context Protocol endpoint at https://api.volleyballapi.com/mcp.

## Agent skill

- [Volleyball API agent skill](https://volleyballapi.com/.well-known/agent-skills/volleyballapi/SKILL.md): how agents use Volleyball API. Index: https://volleyballapi.com/.well-known/agent-skills/index.json

## Optional

- [OpenAPI file](https://volleyballapi.com/openapi.json)
- [Pricing](https://volleyballapi.com/pricing)
- [Support](https://volleyballapi.com/support)