Batch Highlight Packages

Early Beta — Highlight Packages is in early beta. Behavior, request/response shapes, and error semantics may change without notice. Not recommended for production use.

Overview

Retrieve detailed highlight package records for account-level dashboard sync. Unlike the lightweight list endpoint, this response includes package metadata, otio_timeline EDLs, and rendered edit URLs when available. Use this endpoint when you need many full package records in one request. For example, a dashboard can fetch the first 50 packages for an account instead of calling GET /highlight-packages/{id} for each package. The endpoint supports ETag and If-None-Match. Store the ETag from a 200 response and send it on the next poll; the API returns 304 Not Modified when package status, EDL, rendered edit state, and metadata for that exact account/filter/page have not changed.

The ETag includes the stable rendered asset state, such as whether a render exists and the stored rendered edit URL. It does not change just because the API regenerates an expiring signed URL.

Request

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

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Page size, default `50`, max `100`
`cursor`	string	No	Opaque cursor returned as `next_cursor` from a previous page
`created_after`	string	No	ISO timestamp lower bound
`created_before`	string	No	ISO timestamp upper bound
`status`	string	No	Public status filter: `queued`, `processing`, `complete`, or `failed`

Response

{
  "packages": [
    {
      "id": 42,
      "status": "complete",
      "project_ids": [1, 2, 3],
      "target_duration_seconds": 120,
      "render_video": "ffmpeg",
      "fight_filter": [
        { "project_id": 1, "fight_numbers": [3] }
      ],
      "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 (5 clips)"
      },
      "duration": 115.3,
      "num_clips": 5,
      "selected_edit_ids": ["edit-1", "edit-2", "edit-3"],
      "created_at": "2025-01-15T12:30:00Z"
    }
  ],
  "next_cursor": null
}

Polling with ETags

On a 200 response, save both the response body and the ETag header:

ETag: "4dc058f2b7c9..."

On the next poll with the same query parameters, send that value back:

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

If nothing changed for that account/filter/page, the API responds:

HTTP/1.1 304 Not Modified
ETag: "4dc058f2b7c9..."

When you receive 304, keep using the package data from your cached 200 response. The API sends 304 only when the page’s package data is unchanged, including statuses, EDLs, rendered edit state, selected highlights, and metadata.

Endpoint Differences

Endpoint	Use case	Includes full EDLs
`GET /highlight-packages`	Lightweight account package list	No
`GET /highlight-packages/{id}`	Full details for one package	Yes
`GET /highlight-packages/batch`	Full details for many packages in a dashboard sync	Yes

Errors

Status	Description
`304`	No package data changed for the requested filtered page
`400`	Invalid status filter
`401`	Invalid or missing API key
`500`	Server error

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Request

Query Parameters

Response

Polling with ETags

Endpoint Differences

Errors

​Overview

​Request

​Query Parameters

​Response

​Polling with ETags

​Endpoint Differences

​Errors

Overview

Request

Query Parameters

Response

Polling with ETags

Endpoint Differences

Errors