Videos API Endpoints

Overview

Endpoints for video content management, streaming, and video-related features.

Endpoint Summary

Endpoint Method Auth Description
/v1/videos GET None Get video list
/v1/videos/{videoId} GET None Get video details
/v1/videos POST JWT Upload video
/v1/videos/{videoId} PUT JWT Update video metadata
/v1/videos/{videoId} DELETE JWT Delete video
/v1/videos/{videoId}/views POST None Increment view count
/v1/videos/stream/{videoId} GET None Stream video

Video Listing

GET /v1/videos

Description: Retrieves list of videos.

Query Parameters:

Parameter Type Default Description
page int 1 Page number
pageSize int 20 Items per page
category string Filter by category
sportId int Filter by sport
leagueId int Filter by league
search string Search videos
sortBy string "date" Sort: "date", "views", "title"
sortOrder string "desc" "asc" or "desc"

Response: VideosResponse

{
  "videos": [
    {
      "id": 12345,
      "title": "NFL Week 13 Breakdown",
      "description": "Expert analysis of all Week 13 matchups",
      "thumbnail": "https://cdn.example.com/thumbnails/12345.jpg",
      "duration": 1845,
      "views": 15234,
      "category": "analysis",
      "sport": {
        "id": 1,
        "name": "Football"
      },
      "league": {
        "id": 1,
        "name": "NFL"
      },
      "author": {
        "id": "user-123",
        "username": "expert_analyst"
      },
      "publishedAt": "2025-11-28T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 523,
    "totalPages": 27
  }
}

GET /v1/videos/{videoId}

Description: Retrieves detailed video information.

Path Parameters:

Response: Video

{
  "id": 12345,
  "title": "NFL Week 13 Breakdown",
  "description": "Expert analysis of all Week 13 matchups including injury updates and betting trends",
  "longDescription": "<p>Full markdown description...</p>",
  "thumbnail": "https://cdn.example.com/thumbnails/12345.jpg",
  "poster": "https://cdn.example.com/posters/12345.jpg",
  "videoUrl": "https://cdn.example.com/videos/12345.mp4",
  "streamUrl": "https://cdn.example.com/stream/12345/master.m3u8",
  "duration": 1845,
  "resolution": "1080p",
  "fileSize": 524288000,
  "views": 15234,
  "likes": 523,
  "category": "analysis",
  "tags": ["nfl", "week-13", "betting", "picks"],
  "sport": {
    "id": 1,
    "name": "Football"
  },
  "league": {
    "id": 1,
    "name": "NFL"
  },
  "author": {
    "id": "user-123",
    "username": "expert_analyst",
    "displayName": "Expert Analyst",
    "avatar": "https://..."
  },
  "relatedGames": [
    {"id": 67890, "name": "Chiefs vs Raiders"}
  ],
  "chapters": [
    {"time": 0, "title": "Introduction"},
    {"time": 120, "title": "AFC East Preview"},
    {"time": 480, "title": "NFC West Preview"}
  ],
  "publishedAt": "2025-11-28T10:00:00Z",
  "updatedAt": "2025-11-28T12:00:00Z"
}

Video Upload & Management

POST /v1/videos

Description: Uploads a new video.

Authentication: JWT required

Request: Multipart form data

Field Type Required Description
file file Yes Video file (mp4, webm, mov)
title string Yes Video title
description string Yes Short description
longDescription string No Full markdown description
category string Yes Category code
sportId int No Associated sport
leagueId int No Associated league
tags string[] No Video tags
thumbnail file No Custom thumbnail

Response: CreateVideoResponse

{
  "id": 12346,
  "title": "My Video",
  "status": "processing",
  "uploadedAt": "2025-11-29T12:00:00Z",
  "processingProgress": 0,
  "estimatedCompletion": "2025-11-29T12:15:00Z"
}

PUT /v1/videos/{videoId}

Description: Updates video metadata.

Authentication: JWT required (owner or admin)

Path Parameters:

Request Body:

{
  "title": "Updated Title",
  "description": "Updated description",
  "longDescription": "Full updated markdown...",
  "category": "picks",
  "tags": ["nfl", "picks", "expert"],
  "visibility": "public"
}

Visibility Values:

Response: UpdateVideoResponse

DELETE /v1/videos/{videoId}

Description: Deletes a video.

Authentication: JWT required (owner or admin)

Path Parameters:

Response: 204 No Content

Video Streaming

GET /v1/videos/stream/{videoId}

Description: Streams video content.

Path Parameters:

Headers:

Query Parameters:

Parameter Type Description
quality string "auto", "1080p", "720p", "480p", "360p"
format string "hls", "dash", "mp4"

Response: Video stream

Response Headers:

POST /v1/videos/{videoId}/views

Description: Increments video view count.

Path Parameters:

Request Body (Optional):

{
  "watchTime": 120,
  "source": "embed"
}

Response: 204 No Content

Video Categories

Category Description
analysis Game and matchup analysis
picks Pick breakdowns and explanations
highlights Game highlights
tutorial How-to and educational content
interview Interviews and podcasts
live Live streams (recorded)
news Sports news updates

Examples

Get Video List

curl -X GET "https://api.example.com/v1/videos?sportId=1&category=analysis&page=1"

Get Video Details

curl -X GET "https://api.example.com/v1/videos/12345"

Upload Video

curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer eyJ..." \
  -F "file=@my-video.mp4" \
  -F "title=My Analysis Video" \
  -F "description=Expert picks breakdown" \
  -F "category=analysis" \
  -F "sportId=1"

Update Video

curl -X PUT "https://api.example.com/v1/videos/12345" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title", "tags": ["nfl", "picks"]}'

Stream Video

# HLS stream
curl -X GET "https://api.example.com/v1/videos/stream/12345?format=hls"

# Direct MP4 with range
curl -X GET "https://api.example.com/v1/videos/stream/12345" \
  -H "Range: bytes=0-1024"

Increment View Count

curl -X POST "https://api.example.com/v1/videos/12345/views" \
  -H "Content-Type: application/json" \
  -d '{"watchTime": 120}'

Related Endpoints