Videos

Manage video uploads for analysis. Videos must be uploaded before an analysis can be created.

List Videos

Retrieve all videos belonging to your organization.

Request

GET /videos

Response

{
  "data": [
    {
      "id": 789,
      "status": "available",
      "game_name": "happy-dolphin-42",
      "title": "Team A vs Team B - League Match",
      "created_at": "2025-01-15T10:00:00Z",
      "home_team_name": "Team A",
      "away_team_name": "Team B",
      "duration": 5400,
      "analyses": [
        {
          "id": 1246,
          "status": "done"
        }
      ]
    }
  ],
  "links": { ... },
  "meta": { ... }
}

Response Fields

Field	Type	Description
id	integer	Video ID
status	string	Processing status (see below)
game_name	string	Unique human-readable identifier
title	string	Display title
duration	integer	Video duration in seconds
home_team_name	string	Home team name
away_team_name	string	Away team name
analyses	array	Related analyses

---

Create Video

Upload a new video for analysis.

Request

POST /videos

Request Body

{
  "video_file_url": "https://example.com/match-video.mp4",
  "title": "Team A vs Team B - League Match",
  "home_team_name": "Team A",
  "away_team_name": "Team B",
  "date": "2025-01-15",
  "start_offset_seconds": 0,
  "end_offset_seconds": 5400
}

Parameters

Parameter	Type	Required	Description
video_file_url	string	Yes	Public URL to video file (must be directly accessible)
title	string	No	Human-readable title
home_team_name	string	No	Home team name
away_team_name	string	No	Away team name
date	date	No	Match date (YYYY-MM-DD)
start_offset_seconds	integer	No	Start offset in seconds (trim beginning)
end_offset_seconds	integer	No	End offset in seconds (trim end)
left_start_team	string	No	Which team starts on the left: home or away. Setting this will change the labels that are returned in the query engine and summary

Video Requirements

• Video must be accessible via public URL
• Minimum duration: 10 minutes
• Supported formats: MP4
• Resolution must be 1080p or lower (1080p is recommended)
• FPS must be 25

Response

{
  "data": {
    "id": 790,
    "status": "init",
    "game_name": "swift-eagle-43",
    "title": "Team A vs Team B - League Match",
    "created_at": "2025-01-16T14:30:00Z"
  }
}

Example

cURLPythonJavaScript

curl -X POST "https://aiontheball.nl/api/v1/videos" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "video_file_url": "https://example.com/match-video.mp4",
    "title": "Team A vs Team B",
    "home_team_name": "Team A",
    "away_team_name": "Team B"
  }'

import requests

response = requests.post(
    'https://aiontheball.nl/api/v1/videos',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'video_file_url': 'https://example.com/match-video.mp4',
        'title': 'Team A vs Team B',
        'home_team_name': 'Team A',
        'away_team_name': 'Team B'
    }
)
video = response.json()['data']
print(f"Created video {video['id']} with status: {video['status']}")

const response = await fetch('https://aiontheball.nl/api/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    video_file_url: 'https://example.com/match-video.mp4',
    title: 'Team A vs Team B',
    home_team_name: 'Team A',
    away_team_name: 'Team B'
  })
});
const { data: video } = await response.json();

---

Get Video

Retrieve details for a specific video.

Request

GET /videos/{id}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The video ID

Response

{
  "data": {
    "id": 789,
    "status": "available",
    "game_name": "happy-dolphin-42",
    "title": "Team A vs Team B - League Match",
    "created_at": "2025-01-15T10:00:00Z",
    "home_team_name": "Team A",
    "away_team_name": "Team B",
    "duration": 5400,
    "mp4_source": "https://cdn.example.com/videos/789.mp4",
    "analyses": [
      {
        "id": 1246,
        "status": "done"
      }
    ]
  }
}

---

Update Video

Update video metadata.

Request

PUT /videos/{id}

Request Body

{
  "title": "Updated Match Title",
  "home_team_name": "Team A",
  "away_team_name": "Team B"
}

Parameters

All parameters are optional:

Parameter	Type	Description
title	string	Human-readable title
home_team_name	string	Home team name
away_team_name	string	Away team name
date	date	Match date (YYYY-MM-DD)
start_offset_seconds	integer	Start offset in seconds
end_offset_seconds	integer	End offset in seconds

---

Delete Video

Delete a video and all associated analyses.

Request

DELETE /videos/{id}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The video ID

Response

Returns 204 No Content on success.

Irreversible

Deleting a video also deletes all associated analyses. This action cannot be undone.

---

Video Status

Videos progress through these statuses:

Status	Description
init	Video record created, download pending
downloading	Video is being downloaded from source URL
locally_available	Video downloaded, processing in preparation for analysis
available	Video ready for analysis
error	Download or processing failed
no_match_detected	System did not detect a soccer match, and will not run analyses on video

Polling for Status

After creating a video, you can directly create an analysis without waiting for completion.