Create Highlight Packages

Prerequisites

Before you begin, you’ll need:

An API key — create and manage keys in the API Dashboard
At least one completed project with generated highlights
A project ID from GET /v1/tasks/{task_id}/info, your dashboard, or your project management workflow

Current highlights generate otio_edit automatically. Package creation requires the matched highlights to be OTIO-ready because the package EDL is built from those source highlight edits.

Overview

Highlight packages are created from one or more project IDs. Narrative selects highlights from filters such as event type, team, or player, or you can pass exact highlight IDs when you want precise control. The basic flow is:

Get the project ID for the stream task.
Discover available package options for a project.
Create a package from project IDs and filters.
Poll the package through queued and processing until it is complete or failed.
Retrieve the EDL and rendered video URL.

Step 1: Get the Project ID

If you started from a stream task, fetch the generated project ID from task info:

curl "https://api.narrative-sports.com/v1/tasks/YOUR_TASK_ID/info" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use task.project_id in the response. If it is null, retry after the task has started producing project data.

Step 2: Discover Package Options

Use your project ID to discover available event types, teams, players, fights, highlight IDs, and OTIO readiness:

curl -X GET "https://api.narrative-sports.com/v1/projects/1234/highlight-options" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "project_id": 1234,
  "project_name": "Cup Final",
  "event_types": [
    { "value": "goal", "count": 4, "otio_ready_count": 4 },
    { "value": "missed_opportunity", "count": 3, "otio_ready_count": 3 }
  ],
  "teams": [
    { "value": "Argentina", "count": 6, "otio_ready_count": 6 }
  ],
  "players": [
    { "value": "Lionel Messi", "count": 3, "otio_ready_count": 3 }
  ],
  "fights": [],
  "highlights": [
    {
      "id": "edit-1",
      "event_type": "goal",
      "event_description": "Opening goal",
      "target_team": "Argentina",
      "target_players": ["Lionel Messi"],
      "otio_ready": true
    }
  ],
  "total_highlights": 1,
  "otio_ready_highlights": 1
}

Use these values directly in package creation:

Discovery field	Package request field
`event_types[].value`	`event_type_filter`
`teams[].value`	`team_filter`
`players[].value`	`player_filter`
`highlights[].id`	`selected_edit_ids`
`fights[].fight_number`	`fight_filter` or `selected_fights` for MMA fight-specific packages
`fights[].highlight_ids`	`selected_edit_ids` for exact MMA highlight selection

Step 3: Create a Package with Filters

Send the project ID plus the filters you want Narrative to use. name is optional; omit it if you do not need to store a display name.

curl -X POST "https://api.narrative-sports.com/v1/highlight-packages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cup Final Goals",
    "project_ids": [1234],
    "target_duration_seconds": 120,
    "event_type_filter": ["goal", "missed_opportunity"],
    "team_filter": ["Argentina"],
    "render_video": "ffmpeg"
  }'

Response:

{
  "id": 42,
  "status": "queued",
  "task_id": "abc123-def456"
}

Save the returned package id. Package creation can take up to about a minute, and status moves through queued, then usually processing, before reaching complete or failed.

Set render_video to "ffmpeg" to receive a rendered video plus the EDL, or "none" to create only the OTIO EDL.

MMA: Create a Package from Specific Fights

For MMA projects, highlight-options returns fights. To create a package from specific fights, pass project-scoped fight numbers in fight_filter:

{
  "fights": [
    {
      "fight_number": 3,
      "fight_name": "Main Event",
      "count": 12,
      "otio_ready_count": 12,
      "round_numbers": [1, 2, 3],
      "highlight_ids": ["edit-101", "edit-102", "edit-103"]
    }
  ]
}

curl -X POST "https://api.narrative-sports.com/v1/highlight-packages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Event Package",
    "project_ids": [1234],
    "target_duration_seconds": 180,
    "sport": "mma",
    "fight_filter": [
      { "project_id": 1234, "fight_numbers": [3] }
    ],
    "render_video": "ffmpeg"
  }'

selected_fights is accepted as an alias for fight_filter if your UI uses that naming. Use selected_edit_ids when you want to select exact highlights instead of asking the API to resolve the eligible highlights from fights and filters.

Step 4: Poll the Package

Poll the package ID returned by the create call:

curl -X GET "https://api.narrative-sports.com/v1/highlight-packages/42" \
  -H "Authorization: Bearer YOUR_API_KEY"

While the package is running, status may be "queued" or "processing". When status is "complete", the response includes otio_timeline and, if render_video was "ffmpeg", video_url:

{
  "id": 42,
  "status": "complete",
  "project_ids": [1234],
  "target_duration_seconds": 120,
  "video_url": "https://cdn.narrative-sports.com/packages/42/package.mp4?X-Goog-Signature=...",
  "otio_timeline": {
    "OTIO_SCHEMA": "Timeline.1",
    "name": "Multi-game highlight package (6 clips)"
  },
  "duration": 127.665,
  "num_clips": 6,
  "selected_edit_ids": ["edit-1", "edit-2", "edit-3"]
}

Step 5: Sync Packages for a Dashboard

If you are building a UI that shows all packages for an account, use the batch endpoint instead of calling GET /highlight-packages/{id} for every package:

curl -X GET "https://api.narrative-sports.com/v1/highlight-packages/batch?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Store the ETag header from a 200 response and send it back on later polls:

curl -X GET "https://api.narrative-sports.com/v1/highlight-packages/batch?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "If-None-Match: \"PREVIOUS_ETAG\""

The API returns 304 Not Modified when no package data, status, EDL, or rendered edit state changed for that account/filter/page.

Next Steps