SportsVisio Public API

Public RESTful API for accessing SportsVisio's computer vision-powered sports data. Schedules, stats, game insights, player leaderboards, and more.

Base URL https://api.sportsvisio.com

Version 1.0

Auth Bearer JWT

🔒

Authentication

Set up JWT bearer tokens to access the API

🏆

League Integration

Common scenario: schedules, standings, stats

🏀

Games & Stats

Game records, insights, and player statistics

📷

Devices & Upload

Authentication

All API requests require a valid JWT bearer token in the Authorization header. Tokens are issued when a user authenticates with SportsVisio.

Header Format: Include your token in every request as shown below.

HTTP Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJIYWkhIiwiaWF0IjoxNTg5OTk4MjA3fQ

Making Your First Request

Verify your token works by fetching the current user:

curl

curl -X GET "https://api.sportsvisio.com/users/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Tip: If you receive a 401 Unauthorized response, your token may be expired. Re-authenticate to get a fresh token.

League Integration Guide

The most common use case: a league displaying schedules, standings, game results, and player leaderboards using SportsVisio data. Follow these steps to build a complete league experience.

Get Your League / Program

First, retrieve your program (league) record. Use the programType filter set to league.

curl

curl -X GET "https://api.sportsvisio.com/programs/list/{accountId}?programType=league&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "items": [
    {
      "id": "a1b2c3d4-5678-9012-abcd-ef1234567890",
      "name": "BYLD Elite Northeast League",
      "programType": "league",
      "sportId": "basketball",
      "createdAt": "2025-09-15T14:00:00Z"
    }
  ],
  "meta": { "total": 1, "limit": 10, "start": 0 }
}

Get Team Rosters

For each team in a division, fetch the player roster. This gives you jersey numbers, names, and player IDs for building roster pages.

curl

curl -X GET "https://api.sportsvisio.com/teams/players/division/list/{teamId}/{programId}/{eventId}/{divisionId}?limit=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "items": [
    {
      "id": "player-uuid-001",
      "firstName": "Marcus",
      "lastName": "Williams",
      "jerseyNumber": "23",
      "position": "PG",
      "isActive": true
    },
    {
      "id": "player-uuid-002",
      "firstName": "Ciaran",
      "lastName": "Murphy",
      "jerseyNumber": "11",
      "position": "SG",
      "isActive": true
    }
  ],
  "meta": { "total": 12, "limit": 25, "start": 0 }
}

Get Game Schedule & Results

Fetch individual game records for scores, status, and team assignments. Use the scheduled game ID to get full details.

curl

curl -X GET "https://api.sportsvisio.com/scheduled-games/{scheduledGameId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "id": "game-uuid-001",
  "name": "Warriors vs Celtics",
  "scheduledDate": "2026-02-15T19:00:00Z",
  "status": "completed",
  "teams": [
    {
      "teamId": "team-uuid-001",
      "teamName": "Bay Area Warriors",
      "score": 78,
      "isHome": true
    },
    {
      "teamId": "team-uuid-002",
      "teamName": "Boston Celtics Elite",
      "score": 72,
      "isHome": false
    }
  ],
  "court": { "name": "Court 1", "arenaName": "SportsVisio Arena" }
}

Get Game Insights

Pull AI-generated game insights including trends and performance analytics from SportsVisio's computer vision engine.

curl

curl -X GET "https://api.sportsvisio.com/scheduled-games/insights/{scheduledGameId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Build Player Leaderboards

Use the game-player-rollup endpoint to get per-player stats for each game. Aggregate across games to build season leaderboards for points, rebounds, assists, and more.

curl

curl -X GET "https://api.sportsvisio.com/annotations/stats/game-player-rollup/{scheduledGameId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

[
  {
    "playerId": "player-uuid-001",
    "playerName": "Marcus Williams",
    "teamName": "Bay Area Warriors",
    "jerseyNumber": "23",
    "stats": {
      "points": 24,
      "rebounds": 8,
      "assists": 6,
      "steals": 3,
      "blocks": 1,
      "turnovers": 2,
      "fgMade": 9,
      "fgAttempted": 18,
      "fgPercentage": 50.0,
      "threePtMade": 3,
      "threePtAttempted": 7,
      "ftMade": 3,
      "ftAttempted": 4,
      "minutesPlayed": 32
    }
  },
  {
    "playerId": "player-uuid-002",
    "playerName": "Ciaran Murphy",
    "teamName": "Bay Area Warriors",
    "jerseyNumber": "11",
    "stats": {
      "points": 18,
      "rebounds": 4,
      "assists": 9,
      "steals": 2,
      "blocks": 0,
      "turnovers": 3,
      "fgMade": 7,
      "fgAttempted": 15,
      "fgPercentage": 46.7,
      "threePtMade": 2,
      "threePtAttempted": 5,
      "ftMade": 2,
      "ftAttempted": 2,
      "minutesPlayed": 34
    }
  }
]

Tip: To build season leaderboards, call this endpoint for each completed game in the division and aggregate the stats per player across all games.

API Reference

Complete reference for all available endpoints. Click any endpoint to expand details.

No endpoints match your search.

GET /users/{userId} Get User ▶

Returns User record of the currently authenticated user, unless optional userId is specified.

Parameters

Name	In	Type	Required	Description
userId	path	string	No	Optional user UUID. If omitted, returns authenticated user.

200 User found

curl

curl -X GET "https://api.sportsvisio.com/users/{userId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /programs/list/{accountId} Get Paginated List of Programs ▶

Returns paginated programs for the specified account or currently authenticated user. Supports filtering by sport, type, and more.

Parameters

Name	In	Type	Required	Description
accountId	path	string	No	Optional account UUID
column	query	string	No	Sort column (default: createdAt)
direction	query	string	No	ASC or DESC (default: DESC)
limit	query	number	No	Max records to return
start	query	number	No	Starting offset
sportId	query	string	No	Filter by sport (default: basketball)
search	query	string	No	Search by program name or id
programType	query	string	No	generic, club, association, tournament, league, or tree
assigned	query	boolean	No	Only programs assigned to current user
havingGames	query	boolean	No	Only programs with scheduled games
isApiClient	query	boolean	No	Only programs flagged as API clients

200 Paginated program list

curl

curl -X GET "https://api.sportsvisio.com/programs/list/{accountId}?programType=league&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /programs/divisions/teams/{programId}/{eventId}/{divisionId}/bulk Add Teams to Division ▶

Creates multiple division team assignment records in bulk.

Parameters

Name	In	Type	Required	Description
programId	path	string	Yes*	UUID of Program
eventId	path	string	Yes*	UUID of Event
divisionId	path	string	Yes*	UUID of Division

200 Teams added404 Division not found

curl

curl -X POST "https://api.sportsvisio.com/programs/divisions/teams/{programId}/{eventId}/{divisionId}/bulk" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"teamIds": ["team-uuid-1", "team-uuid-2"]}'

POST /teams/{programId}/{eventId}/{divisionId} Create Team ▶

Creates a new Team record within the specified program event division.

Parameters

Name	In	Type	Required	Description
programId	path	string	Yes*	UUID of Program
eventId	path	string	Yes*	UUID of Event
divisionId	path	string	Yes*	UUID of Division

200 Team created

curl

curl -X POST "https://api.sportsvisio.com/teams/{programId}/{eventId}/{divisionId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Bay Area Warriors", "abbreviation": "BAW"}'

POST /teams/players/{teamId}/{programId}/{eventId}/{divisionId} Create TeamPlayer ▶

Creates a TeamPlayer record associated with a Team.

Parameters

Name	In	Type	Required	Description
teamId	path	string	Yes*	UUID of Team
programId	path	string	Yes*	UUID of Program
eventId	path	string	Yes*	UUID of Event
divisionId	path	string	Yes*	UUID of Division

200 Player created

curl

curl -X POST "https://api.sportsvisio.com/teams/players/{teamId}/{programId}/{eventId}/{divisionId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Marcus", "lastName": "Williams", "jerseyNumber": "23"}'

GET /teams/players/division/list/{teamId}/{programId}/{eventId}/{divisionId} Get Team Players (Division Roster) ▶

Returns a paginated list of Team Players for the specified team and Program Event Division roster.

Parameters

Name	In	Type	Required	Description
teamId	path	string	Yes*	Team UUID
programId	path	string	Yes*	UUID of Program
eventId	path	string	Yes*	UUID of Event
divisionId	path	string	Yes*	UUID of Division
column	query	string	No	Sort column
direction	query	string	No	ASC or DESC
limit	query	number	No	Max records
search	query	string	No	Filter by name
hideInactive	query	boolean	No	Skip inactive players

200 Paginated player list

curl

curl -X GET "https://api.sportsvisio.com/teams/players/division/list/{teamId}/{programId}/{eventId}/{divisionId}?limit=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /teams/players/division/{teamId}/{programId}/{eventId}/{divisionId} Add TeamPlayers to Division Roster ▶

Adds existing TeamPlayers to the specified Program Event Division roster.

Parameters

Name	In	Type	Required	Description
teamId	path	string	Yes*	Team UUID
programId	path	string	Yes*	UUID of Program
eventId	path	string	Yes*	UUID of Event
divisionId	path	string	Yes*	UUID of Division

201 Players added to roster

curl

curl -X POST "https://api.sportsvisio.com/teams/players/division/{teamId}/{programId}/{eventId}/{divisionId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"teamPlayerId": "player-uuid-1"}, {"teamPlayerId": "player-uuid-2"}]'

GET /scheduled-games/{scheduledGameId} Get ScheduledGame ▶

Returns full ScheduledGame record including teams, rosters, device assignments, and game status.

Parameters

Name	In	Type	Required	Description
scheduledGameId	path	string	Yes*	Scheduled Game UUID

200 Game details

curl

curl -X GET "https://api.sportsvisio.com/scheduled-games/{scheduledGameId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /scheduled-games/{programId}/{eventId}/{divisionId} Create ScheduledGame ▶

Creates a ScheduledGame record within the specified program event division.

Parameters

Name	In	Type	Required	Description
programId	path	string	Yes*	UUID of Program
eventId	path	string	Yes*	UUID of Event
divisionId	path	string	Yes*	UUID of Division

200 Game created

curl

curl -X POST "https://api.sportsvisio.com/scheduled-games/{programId}/{eventId}/{divisionId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Warriors vs Celtics", "scheduledDate": "2026-03-15T19:00:00Z"}'

GET /scheduled-games/insights/{scheduledGameId} Get ScheduledGame Insights ▶

Returns AI-generated insights for the game including analytics, trends, and performance summaries from SportsVisio's computer vision pipeline.

Parameters

Name	In	Type	Required	Description
scheduledGameId	path	string	Yes*	Scheduled Game UUID

200 Game insights

curl

curl -X GET "https://api.sportsvisio.com/scheduled-games/insights/{scheduledGameId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /scheduled-games/assigned/{scheduledGameTeamAssnId}/roster Assign TeamPlayer to Game Roster ▶

Assigns TeamPlayers to a specific game roster via the scheduled game team assignment.

Parameters

Name	In	Type	Required	Description
scheduledGameTeamAssnId	path	string	Yes*	Game Team Assignment UUID

200 Roster assigned

curl

curl -X POST "https://api.sportsvisio.com/scheduled-games/assigned/{scheduledGameTeamAssnId}/roster" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"teamPlayerId": "player-uuid", "jerseyNumber": "23"}]'

GET /annotations/stats/game-player-rollup/{scheduledGameId} Rollup Stats for Game Players ▶

Returns aggregated rollup statistics for each player in the specified game. Includes points, rebounds, assists, steals, blocks, turnovers, shooting percentages, and minutes played -- generated by SportsVisio's AI annotation engine.

Parameters

Name	In	Type	Required	Description
scheduledGameId	path	string	Yes*	Scheduled Game UUID

200 Array of player stat summaries

curl

curl -X GET "https://api.sportsvisio.com/annotations/stats/game-player-rollup/{scheduledGameId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /devices/list/{accountId} Get a List of Devices ▶

Returns a paginated list of Device records. Supports search by device name, model, macAddress, or manufacturer.

Parameters

Name	In	Type	Required	Description
accountId	path	string	No	Optional account ID
column	query	string	No	Sort column
direction	query	string	No	ASC or DESC
limit	query	number	No	Max records
start	query	number	No	Starting offset
search	query	string	No	Filter by name, model, macAddress, manufacturer

200 Paginated device list

curl

curl -X GET "https://api.sportsvisio.com/devices/list/{accountId}?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /devices/register/{accountId} Register a New Device ▶

Creates a Device record and registers it to the specified account.

Parameters

Name	In	Type	Required	Description
accountId	path	string	No	Optional account ID

200 Device registered

curl

curl -X POST "https://api.sportsvisio.com/devices/register/{accountId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Court 1 Camera", "model": "SportsVisio Lens"}'

POST /devices/attach/{scheduledGameId} Attach Device to Game ▶

Attaches a registered device to a scheduled game for recording.

Parameters

Name	In	Type	Required	Description
scheduledGameId	path	string	Yes*	UUID of scheduled game

200 Device attached404 Not found

curl

curl -X POST "https://api.sportsvisio.com/devices/attach/{scheduledGameId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deviceId": "device-uuid"}'

GET /devices/upload-token/{scheduledGameId}/{deviceId} Get Upload Token ▶

Returns an upload token to upload source media for AI processing.

Parameters

Name	In	Type	Required	Description
scheduledGameId	path	string	Yes*	Scheduled Game UUID
deviceId	path	string	Yes*	Device UUID

200 Upload token

curl

curl -X GET "https://api.sportsvisio.com/devices/upload-token/{scheduledGameId}/{deviceId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /devices/init-upload-multipart/{scheduledGameId}/{deviceId} Initiate Multipart Upload ▶

Creates a multipart upload session for direct S3 upload of source media. Use for large video files.

Parameters

Name	In	Type	Required	Description
scheduledGameId	path	string	Yes*	Scheduled Game UUID
deviceId	path	string	Yes*	Device UUID

201 Multipart session created

curl

curl -X POST "https://api.sportsvisio.com/devices/init-upload-multipart/{scheduledGameId}/{deviceId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename": "game-2026-03-15.mp4", "contentType": "video/mp4"}'

POST /upload Upload Image to CDN ▶

Uploads an image to FileStack CDN and returns a storable URL for team logos, player images, etc.

201 Image uploaded

curl

curl -X POST "https://api.sportsvisio.com/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"imageData": "base64-encoded-data", "fileName": "team-logo.png"}'

POST /upload/multipart/{uploadId}/complete Complete Multipart Upload ▶

Completes the multipart upload and returns the final file URL. Optionally validates SHA256 checksum.

Parameters

Name	In	Type	Required	Description
uploadId	path	string	Yes*	Multipart upload ID

200 Upload completed

curl

curl -X POST "https://api.sportsvisio.com/upload/multipart/{uploadId}/complete" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sha256": "optional-checksum"}'

Changelog

Track changes and updates to the SportsVisio Public API.

February 6, 2026v1.0.0

Added Initial public API release with 18 endpoints
Added League Integration Guide with step-by-step walkthrough
Added Game player rollup stats endpoint for leaderboard support
Added Game Insights endpoint for AI-generated analytics
Added Multipart upload support for large video files
Added Device management endpoints (register, attach, upload tokens)

January 2026v0.9.0-beta

Added Beta release for partner testing (PlayHQ, BYLD Sports)
Added JWT bearer token authentication
Added Core endpoints: Users, Programs, Teams, Scheduled Games

SportsVisio Public API

Authentication

Making Your First Request

League Integration Guide

Get Your League / Program

Get Team Rosters

Get Game Schedule & Results

Get Game Insights

Build Player Leaderboards

API Reference

Users

Parameters

Programs

Parameters

Program Divisions

Parameters

Teams

Parameters

Team Players

Parameters

Parameters

Parameters

Scheduled Games

Parameters

Parameters

Parameters

Scheduled Game Team Assignment

Parameters

Annotation Statistics

Parameters

Devices

Parameters

Parameters

Parameters

Parameters

Parameters

Uploads

Multipart Uploads

Parameters

Changelog