Batch Signed URLs

Overview

Use this endpoint to fetch signed download URLs for multiple highlights at once, reducing the number of API calls needed when displaying a page of highlights. This is the batched version of Get Signed URL — instead of one call per highlight, you can request all URLs in a single request.

Request

curl -X POST "https://api.narrative-sports.com/v1/highlights/batch-signed-urls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "highlight_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901"],
    "expiry": 3600
  }'

Request Body

Parameter	Type	Required	Description
`highlight_ids`	string[]	Yes	List of edit IDs to generate signed URLs for
`expiry`	integer	No	Seconds until the signed URLs expire. Default: `900`. Min: `900` (15 minutes), max: `86400` (24 hours).

Response

{
  "signed_urls": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": "https://cdn.narrative-sports.com/task-id/refined_000_goal.mp4?X-Goog-Signature=...",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901": "https://cdn.narrative-sports.com/task-id/refined_001_shot.mp4?X-Goog-Signature=..."
  },
  "signed_poster_urls": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": "https://cdn.narrative-sports.com/task-id/refined_000_goal.jpg?X-Goog-Signature=...",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901": "https://cdn.narrative-sports.com/task-id/refined_001_shot.jpg?X-Goog-Signature=..."
  },
  "expires_in_seconds": 3600
}

Response Fields

Field	Type	Description
`signed_urls`	object	Map of edit ID to pre-signed video download URL. Only includes IDs that were found and have a video available.
`signed_poster_urls`	object	Map of edit ID to pre-signed poster image (.jpg) URL. Use these as lightweight thumbnail images instead of loading the video.
`signed_portrait_urls`	object	Mapping of highlight IDs to signed portrait (9:16) video download URLs. Only present for highlights that have a portrait video.
`signed_portrait_poster_urls`	object	Mapping of highlight IDs to signed portrait thumbnail (JPG) URLs.
`signed_square_urls`	object	Mapping of highlight IDs to signed square (1:1) video download URLs. MMA only — only present for highlights that have a square variant.
`signed_square_poster_urls`	object	Mapping of highlight IDs to signed square thumbnail (JPG) URLs. MMA only.
`expires_in_seconds`	integer	Number of seconds until the signed URLs expire (matches the requested `expiry` value).

IDs that are not found, do not belong to the authenticated customer, or do not have a video URL are silently omitted from the response (no error is returned for them).

Errors

Status	Description
`401`	Invalid or missing API key
`422`	Invalid request body (e.g. expiry out of range)

Typical Flow

Use GET /highlights to list highlights and collect their IDs
Collect all IDs and call POST /highlights/batch-signed-urls
Use the returned signed_urls map to display or download the videos
If the URLs expire, call the endpoint again to get fresh ones

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Request

Request Body

Response

Response Fields

Errors

Typical Flow

​Overview

​Request

​Request Body

​Response

​Response Fields

​Errors

​Typical Flow

Overview

Request

Request Body

Response

Response Fields

Errors

Typical Flow