API Overview

Introduction

The Narrative Sports API provides endpoints for processing live sports streams using SRT protocol. Highlights are detected and generated in real-time.

SRT ingest requires both video and audio streams. Commentary is a separate requirement: clear spoken commentary is needed for reliable highlight detection. A stream can have audio and still underperform if it is crowd/noise-only. Also use at least 3000 kb/s source bitrate for portrait cropping. See Video Input Requirements.

Base URL

https://api.narrative-sports.com/v1

Authentication

All endpoints require Bearer token authentication via the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys can be created and managed in the API Dashboard. See the Authentication guide for details.

Endpoints Overview

Task Management

Method	Endpoint	Description
POST	`/tasks/create-task`	Create a task, launch a worker, and receive the SRT URL in one call (recommended)
GET	`/tasks/list-tasks`	List tasks with status/details (supports `state` filtering)
GET	`/tasks/{task_id}/info`	Get detailed info for a single task
POST	`/tasks/{task_id}/extend-life`	Increase the maximum lifetime of an active task
POST	`/tasks/{task_id}/kill`	Stop a task and terminate its worker
POST	`/tasks/warmup`	Deprecated. Pre-start a worker instance for a sport
POST	`/tasks/assign-task`	Deprecated. Assign work to a warmed-up instance
GET	`/tasks/{task_id}/status`	Deprecated. Poll for task readiness status (warmup flow only)

Highlights

Method	Endpoint	Description
GET	`/highlights`	List all highlights with metadata
GET	`/highlights/{highlight_id}`	Get metadata for a single highlight
GET	`/highlights/{highlight_id}/signed-url`	Generate a time-limited download URL for a rendered highlight
POST	`/highlights/batch-signed-urls`	Generate signed URLs for multiple highlights in one request

Highlight Packages

Method	Endpoint	Description
POST	`/highlight-packages`	Create a multi-game highlight package
GET	`/highlight-packages/{package_id}`	Get package details and status
GET	`/highlight-packages`	List all packages
DELETE	`/highlight-packages/{package_id}`	Delete a package

Recaps

Method	Endpoint	Description
POST	`/recaps`	Create a single-game recap
GET	`/recaps/{recap_id}`	Get recap details and status
GET	`/recaps`	List all recaps
DELETE	`/recaps/{recap_id}`	Delete a recap

Request Format

All POST requests should include:

Content-Type: application/json

Request bodies should be valid JSON.

Response Format

All responses are JSON with the following structure: Success:

{
  "success": "success",
  "task_id": "YOUR_TASK_ID",
  ...
}

Error (400/401):

{
  "detail": "Error message"
}

No usage limit (403):

{
  "detail": "Your account is not allowed to create tasks. Contact [email protected] to get started."
}

Returned by task-creation endpoints (/tasks/create-task, and the deprecated /tasks/warmup) when your account has no concurrent task limit configured. Narrative manages concurrent task limits centrally; organization members cannot change them through the API or dashboard. Rate limit exceeded (429):

{
  "detail": "Concurrent task limit reached: 2/2. If you believe this is in error, or to request a rate limit increase, contact [email protected]."
}

Returned when you have reached your maximum number of concurrent tasks. Kill a running task or wait for one to finish before creating a new one. Server Error (500):

{
  "detail": "Failed to start worker due to high traffic. Please try again later."
}

Server errors (500) indicate a transient infrastructure issue. Retry after a short delay.

Task Statuses

These values appear as task_status in task-management responses like GET /tasks/list-tasks and GET /tasks/{task_id}/info.

Status	Description
`queued`	Task created, worker launching
`running`	Worker active (booting or processing)
`ready`	SRT URL published, ready to receive stream
`completed`	Task finished successfully
`error`	Worker failed to launch (infrastructure / instance startup failure)
`failed`	Worker started but processing failed (pipeline / runtime error)
`stopped`	Task was stopped — either manually via the kill endpoint, or automatically when the `max_life_hours` limit was reached

Quick Start

Create Task

Create a task, launch a worker, and receive the SRT URL in one call (recommended)

Quickstart

End-to-end walkthrough — from API key to highlights in the dashboard

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Introduction

Base URL

Authentication

Endpoints Overview

Task Management

Highlights

Highlight Packages

Recaps

Request Format

Response Format

Task Statuses

Quick Start

Create Task

Quickstart

​Introduction

​Base URL

​Authentication

​Endpoints Overview

​Task Management

​Highlights

​Highlight Packages

​Recaps

​Request Format

​Response Format

​Task Statuses

​Quick Start

Create Task

Quickstart

Introduction

Base URL

Authentication

Endpoints Overview

Task Management

Highlights

Highlight Packages

Recaps

Request Format

Response Format

Task Statuses

Quick Start