API Overview

Version 1 of the match analysis API: video management, analysis creation and every result an analysis produces.

Base URL

https://aiontheball.nl/api/v1/

Every request carries a bearer token, see Authentication:

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

All responses are JSON. A successful request returns HTTP 200, except DELETE /videos/{id}, which returns 204.

Endpoints

Videos and analyses

Endpoint	Method	Description
/videos	GET	List all videos
/videos	POST	Create a video from a public URL
/videos/{id}	GET	Video details and status
/videos/{id}	PUT	Update video metadata
/videos/{id}	DELETE	Delete the video and every analysis on it
/videos/{id}/preview-teams	GET	Kit colours and player crops detected before analysis
/videos/{id}/meta	GET	Read the resolved game-meta envelope
/videos/{id}/embed-token	POST	Mint a token for the confirm-sides widget
/videos/{id}/analysis	POST	Create an analysis for a video
/analyses/{id}	GET	Analysis status, progress and quality
/analyses/{id}/team-mapping	GET	Resolve team_0 / team_1 to home/away, names, roles and sides

Results

Endpoint	Method	Description
/analyses/{id}/events	GET	Every detected event, as timed rows
/analyses/{id}/summary	GET	Match summary: possession, player identities and player statistics
/analyses/{id}/player-report/{player_id}	GET	Per-player report: coverage, physical, position, on-ball, interactions
/analyses/{id}/team-report	GET	Per-team report: average positions, possession, territory, kits, quality
/analyses/{id}/query-intervals	POST	Time intervals matching a filter query
/analyses/{id}/tracking/download	GET	Raw player and ball positions as Parquet or JSON
/analyses/{id}/schema	GET	Event types and metadata fields the analysis carries
/analyses/{id}/exemplar-crops	GET	Player and team appearance crops

Response format

Video and analysis endpoints wrap their records in a data envelope. team-mapping, preview-teams and embed-token return a bare object. Result endpoints return the payload unwrapped, a bare JSON array or object as shown on each endpoint page.

{ "data": { ... } }

Errors carry message for 401 and 403 on every path, for a 404 on an unknown video or analysis id, and for the 504 when a result does not arrive within 15 seconds:

{ "message": "Unauthenticated." }

Every other error from a result endpoint carries detail:

{ "detail": "Analysis not found" }

Response codes

Code	Description
200	Success
204	Video deleted
400	Request rejected by a validation rule, e.g. a video shorter than 10 minutes
401	Invalid or missing token
403	No access to this video or analysis
404	Video, analysis or result not found
409	Video cannot be deleted while an analysis on it is running
422	Invalid request body or query parameter
429	Rate limit exceeded
500	Analysis data could not be loaded
503	Analysis not finished yet, or its data is temporarily unavailable. Retry later
504	Result did not arrive in time. Retry later

Rate limits

Default limits per account. A 429 is returned when one is exceeded.

Scope	Limit
POST /videos	5 per minute, 200 per day
POST /videos/{id}/analysis	10 per 5 minutes, 300 per week