Assign Task

Deprecated. This endpoint is part of the legacy Warmup flow and is retained for backward compatibility. New integrations should use Create Task, which combines worker launch and assignment into a single call and returns the SRT URL synchronously.

Overview

Assign a processing task to a previously warmed-up instance. This endpoint is used after calling Warmup to provide the actual stream details and begin processing. This call only succeeds when the worker has both generated an SRT URL and finished initializing the SRT listener.

Request Parameters

Parameter	Type	Required	Description
`narrative_task_id`	string	Yes	Task ID from the warmup response
`srt_zero_relative_smpte_timecode`	string	No	Starting SMPTE timecode for the stream (`HH:MM:SS:FF` or drop-frame `HH:MM:SS;FF`). Defaults to `"00:00:00:00"`. Used to interpret ingest timing; it is not automatically added to OTIO `start_time.value`.
`framerate`	string	No	Framerate in ffprobe rational format (e.g., `"30000/1001"`, `"30/1"`, `"25/1"`, `"60000/1001"`). Used both for interpreting the SMPTE timecode during SRT ingest and for any rendered videos/results returned by the API. If omitted the framerate is inferred from the stream, but this can be inconsistent — especially with VFR encoding. If provided, it is your responsibility to ensure the value is accurate.
`webhook_id`	string	No	Organization webhook endpoint ID. See the Webhooks Quickstart.
`render_videos`	object	No	Video rendering options
`team_names`	object	No	Team name metadata
`otio`	object	No	Optional OTIO metadata/timing override. OTIO edit generation is automatic; this object is not required to enable it. See OTIO Format.
`webhook_schema`	string	No	Deprecated — legacy OTIO field. Do not use for new integrations; OTIO edit generation is automatic.
`wh_schema_config`	object	No	Deprecated — legacy OTIO configuration paired with `webhook_schema="otio"`. Use `otio` only for metadata/timing overrides.

Input Stream Requirements

When streaming to the srt_url returned by this endpoint, your input must meet these requirements:

Requirement	Details
Video + audio streams are required	SRT ingest expects both (`-map 0:v` and `-map 0:a`). Audio-less streams can fail ingest.
Commentary audio is required	Clear spoken commentary is required for detection. Commentary is not the same as having any audio stream; crowd/noise-only audio can ingest but won’t produce highlights.
Minimum bitrate for portrait cropping	Use at least 3000 kb/s source video bitrate for stable portrait crop quality.

See Video Input Requirements for validation commands and FFmpeg examples.

Render Videos Object

Field	Type	Description
`render_video`	string	Rendering method: `ffmpeg` or `none` (use `none` to skip video output)
`retention_seconds`	integer	How long to retain rendered videos in seconds (default: 86400, min: 3600, max: 2592000 — approximately 1 month)

When render_video is set to "ffmpeg", rendered highlight clips are automatically uploaded to a project in your dashboard at app.narrative-sports.com. You can review, download, and manage your clips there. See Dashboard Integration for details.

Team Names Object

For soccer, baseball, and American football, use team names. For MMA, use individual fighter names.

Field	Type	Description
`home_team_name`	string	Name of the home team, or the first fighter’s name for MMA
`away_team_name`	string	Name of the away team, or the second fighter’s name for MMA

Example Request

curl -X POST "https://api.narrative-sports.com/v1/tasks/assign-task" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "narrative_task_id": "YOUR_TASK_ID",
    "srt_zero_relative_smpte_timecode": "01:00:00:00",
    "framerate": "30000/1001",
    "render_videos": {
      "render_video": "ffmpeg",
      "retention_seconds": 86400
    },
    "team_names": {
      "home_team_name": "Barcelona",
      "away_team_name": "Real Madrid"
    }
  }'

Example Response

{
  "success": "success",
  "status": "Task assigned - stream to SRT URL",
  "task_id": "YOUR_TASK_ID",
  "srt_url": "srt://<host>:9000?passphrase=SRT_PASSPHRASE"
}

Response Fields

Field	Type	Description
`success`	string	Result status: `success` or `failure`
`status`	string	Human-readable status message
`task_id`	string	The assigned task ID
`srt_url`	string	Complete SRT URL for this task (per-task host + encryption passphrase)

SRT Stream Configuration

URL Format

The srt_url includes everything needed to connect:

srt://<host>:9000?passphrase=<passphrase>

Parameter	Description
`<host>`	The per-task worker address that ingests your stream. Returned in the `srt_url`; valid only for this task.
`passphrase`	SRT encryption passphrase (the AES key for the connection).

Connect in SRT caller mode (the default for FFmpeg/OBS) over UDP 9000. SRT latency is negotiated automatically (the server uses 5 seconds); you may also set &latency=5000000 on your encoder.

Use the complete srt_url exactly as returned by the API. It contains the per-task host and encryption passphrase and is valid only for that task — don’t rebuild or modify it.

SMPTE Timecode

The srt_zero_relative_smpte_timecode field specifies the timecode that corresponds to the start of the stream. Format: HH:MM:SS:FF (hours:minutes:seconds:frames) or drop-frame HH:MM:SS;FF. If framerate is provided, it is used to interpret the timecode. Otherwise, the framerate is inferred from the stream (note: inference can be inconsistent with VFR encoding). Drop-frame timecodes are only valid with 29.97 (30000/1001) or 59.94 (60000/1001) framerates; incompatible combinations cause the task to fail fast. For OTIO output, srt_zero_relative_smpte_timecode does not by itself shift source_range.start_time.value. Use otio.source_start_offset when you need a fixed frame offset in OTIO.

Error Responses

Status	Description
`Task not found`	The narrative_task_id doesn’t exist or wasn’t created by you
`Task is no longer running (status: stopped)`	The task was killed before assignment. Create a new task.
`Worker has not generated SRT URL yet (status: ...)`	The worker is still booting. Poll `GET /tasks/{task_id}/status` until `ready` is `true`.
`SRT listener not ready yet (status: ...)`	The URL exists but listener initialization is still in progress. Continue polling `GET /tasks/{task_id}/status` until `ready` is `true`.

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Request Parameters

Input Stream Requirements

Render Videos Object

Team Names Object

Example Request

Example Response

Response Fields

SRT Stream Configuration

URL Format

SMPTE Timecode

Error Responses

​Overview

​Request Parameters

​Input Stream Requirements

​Render Videos Object

​Team Names Object

​Example Request

​Example Response

​Response Fields

​SRT Stream Configuration

​URL Format

​SMPTE Timecode

​Error Responses

Overview

Request Parameters

Input Stream Requirements

Render Videos Object

Team Names Object

Example Request

Example Response

Response Fields

SRT Stream Configuration

URL Format

SMPTE Timecode

Error Responses