Build a rail from chapters

A long event replay is hard to navigate. AgentTV already divides it into chapters. You can show those chapters as a rail of tiles on your page, one tile per match or segment. Each tile opens the same video in your own player at the chapter’s start. No editor cuts anything, and no new video files are made.

1. Get the chapters

Pick one source:

Page block
ARV record
Account API

The page block you already fetch for the video page holds the chapters, as Clip items under json_ld["@graph"][0].hasPart:

{ "@type": "Clip", "name": "Semi-final 1", "description": "...", "startOffset": 1840, "endOffset": 4210, "url": "..." }

Times are seconds. See Put metadata on your pages.

GET /public/creators/{slug}/videos/{video_id}/arv.json lists data.chapters, each with title, summary, start_ms and end_ms. Times are milliseconds. An unlisted account sends its API key.

GET /v1/videos/{video_id}/timeline returns chapters with the shots, speaker turns and on-screen text around them, 10 minutes of video per call. Use it when you want to choose the tiles yourself, for example only the chapters where two named teams are on screen.

curl -s "https://api.agentcdn.com/v1/videos/vid_123/timeline?start_ms=0" \
  -H "Authorization: Bearer $AGENTCDN_API_KEY"

When next_start_ms is not null, call again with it as start_ms.

2. Link each tile to the moment

Open your own player at the chapter’s start second, with the start parameter your player takes:

https://www.example.com/videos/1234?t=1840

Use the same rule you gave us for Start at the moment, so tiles, chapter links in your JSON-LD and AI answers all open the same way.

3. Pick a tile image

AgentTV does not return an image per chapter today. Use a frame from your own player’s thumbnail sprites at the chapter’s start second. Most players already publish a WebVTT file that maps each time range to a sprite tile. Or make your own image template, for example both team names over a still.

4. Let people jump by asking

A rail covers the matches you list. Ask covers the rest. Put Ask on the same page so a visitor can type “take me to the women’s final” and land on that second. To answer that kind of question from your own UI, call POST /v1/moments from your server. It returns the matching moments fast, with no written answer:

curl -s https://api.agentcdn.com/v1/moments \
  -H "Authorization: Bearer $AGENTCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "women'\''s final", "video_id": "vid_123", "max_results": 3}'

Each moment has its video id, title, start and end in milliseconds, and why it matched. An empty result carries no_answer. The body also takes library_id, and include_private (default true: unlisted and private videos are included). Open your player at the start.

Need a file of one range?

Linking into the full replay keeps one source video for every tile. When your team needs the picture and sound of one range as a file, for example to edit a social cut, ask for a range link:

curl -s -X POST https://api.agentcdn.com/v1/videos/vid_123/range-link \
  -H "Authorization: Bearer $AGENTCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_ms": 1840000, "end_ms": 1900000}'

The answer holds a signed MP4 url and its expires_at. Rules:

It needs a key that can make changes. It costs nothing and runs in one call, with no preview.
A range is at most 10 minutes. The file is copied from the stream without re-encoding, so the cut can land slightly off the times you asked for.
Anyone who holds the link can download the file until it expires. Share it only with people who may see the video.
It works for any video your account imported. It is the only call that returns a media file. Search and answers never do.

The account MCP offers the same as get_range_link, so an AI app can pick a range from get_video_timeline and fetch only that range.

Your videos

Playback and AI apps

Audience and members

On your site

Measure

Build a rail from chapters

1. Get the chapters

2. Link each tile to the moment

3. Pick a tile image

4. Let people jump by asking

Need a file of one range?

​1. Get the chapters

​2. Link each tile to the moment

​3. Pick a tile image

​4. Let people jump by asking

​Need a file of one range?

1. Get the chapters

2. Link each tile to the moment

3. Pick a tile image

4. Let people jump by asking

Need a file of one range?