Handball.ai APIs
Plug directly into the most complete handball dataset in the world. Games, players, lineups, event-based positioning, xG, xS and live scoring — all through a single, consistent API.
What you can build with
Games & Schedules
Create and query scheduled, live and ended games filtered by team, season or competition.
- Game scheduling
- Search ended & scheduled games
- Full game details
Teams, Players & Staff
Full CRUD over the team roster: manage players, technical staff and seasons participation.
- Team & roster management
- Players & staff CRUD
- Seasons & users
Real-time Stats
Pull live game statistics and trigger webhooks for in-match events as they happen.
- Live game stats
- Webhook triggers
- In-match updates
Post-Game Analytics
Aggregated post-match stats per player and team, plus AI-generated lineups and rotations.
- Player & team stats
- Best lineup (offense/defense)
- Player generation
Authentication
Secure access via API key. Optional Use-External-Ids header to map your own identifiers
- API key auth
- External ID mapping
- Per-environment scopes
System & Health
Lightweight ping endpoint to verify connectivity, latency and service availability.
- Health check
- Status monitoring
- Uptime visibility
How you connect
Three simple steps to get your full match analysis delivered within 24 hours.
REST API
OpenAPI 3.0 endpoints over HTTPS with JSON payloads. Single base URL at external.api.handball.ai.
Webhooks
Trigger and receive real-time game events via /game/{gameId}/webhook_trigger for live stats and updates.
External ID Mapping
Use the Use-External-Ids header to query and write data with your own team, player and game identifiers.
A glimpse of the endpoints
/game/schedule
/game/search/ended
/game/search/scheduled
/game/{gameId}/details
/game/{gameId}/stats
/game/{gameId}/webhook_trigger
/team/{teamId}/players
/team/{teamId}/player
/team/{teamId}/stats
/team/{teamId}/best-lineup/{offense_defense}
/player/{playerId}/stats
/seasons
- -H “Authorization: YOUR_API_TOKEN” \
- -H “Use-External-Ids: false” \
- -H “Accept: application/json”
Secured with API keys, scoped tokens and per-environment rate limits.
const res = await fetch(
“https://external.api.handball.ai/game/12345/stats”,
{
headers: {
Authorization: API_TOKEN,
“Use-External-Ids”: “false”,
},
}
);
const stats = await res.json();
Secured with API keys, scoped tokens and per-environment rate limits.
import requests
r = requests.get(
“https://external.api.handball.ai/game/12345/stats”,
headers={
“Authorization”: API_TOKEN,
“Use-External-Ids”: “false”,
},
)
stats = r.json()
Secured with API keys, scoped tokens and per-environment rate limits.
Interactive API tester
Pick an endpoint, tweak the parameters and run a sample request against our sandbox to see exactly what your integration will receive.
Request
Sandbox mode — responses are simulated from real schemas. No live data is fetched.