Skip to main content
The catalog import reads your video ids from your video sitemap or JSON Feed, reads each video’s details from your metadata API, and stores each video under your own id. That id is what your page template uses later to fetch the page block. Videos keep playing from your stream. AgentTV copies one rendition, the tallest at or under 1080p, into private storage for analysis only: transcript, chapters, moments and the rest. It remuxes and never re-encodes. It never serves that copy to viewers. Every play uses your player or your stream. The only file that leaves it is a range link your own team asks for with its key. To start, AgentTV needs only your video ids and a way to read each video. Everything else, from chapters to people on screen, is derived from the video.

​
Two ways to connect

For a brand with its own video platform and metadata API. You send us the details below, and AgentTV sets up the mapping for your account. The mapping is configuration, not custom code.

​
What you provide

The import reads a list of your videos (a video sitemap or a JSON Feed) plus your metadata API.

​
1. Your video sitemap

A standard video sitemap, or a sitemap index of them. Tell us:
  • The sitemap URL. It must be https. Child sitemaps must be on the same host.
  • Where the id sits. Either in the page URL (<loc>) or in the player URL (<video:player_loc>).
  • A pattern for the id. A regular expression with one capture group that pulls your id out of that URL. Entries it does not match are skipped.
From each entry, AgentTV reads the title, description, publish date (video:publication_date), lastmod, duration and thumbnail when present. Publish dates help AI apps judge how fresh a video is, so include them. Large sitemaps are fine. AgentTV reads the sitemap in the background into a stored index and reads it again every 12 hours. Nothing waits on a live sitemap read. If your sitemap gives each video a video:title, search in the console covers your whole catalog at once.

​
A JSON Feed instead of a sitemap

In place of a sitemap, the list can be a JSON Feed 1.1. AgentTV tells the two apart by the document. Each item is one video: Three optional fields go under an _agentcdn object on the item:
  • default_audio_language is the language the video is spoken in (BCP 47). It holds until the transcript detects the language. It can differ from language: an English page for a video spoken in Spanish. See Languages.
  • window is the one time range of the video to import, in seconds of the source. The feed owns it: an item with a window imports only that range, and a console pick cannot change it. An item with no window imports whole.
  • expires is when your licence for the video ends. After it, the video is not played, listed or used in answers. A changed or removed expires moves or clears the end on the next read. An expires that is not a time keeps the item out of the list.
A feed of several pages names the next one in next_url, on the same host. An item with no usable id or page URL is skipped. Caption tracks come from the HLS stream’s subtitle renditions.

​
2. Read access to your metadata API

AgentTV reads one item per video from your API. Tell us:
  • The API origin, for example https://api.example.com. Every request and redirect stays on this origin.
  • The item path with {id} where your id goes, for example /v3/videos/{id}.
  • Any headers the API needs, and an optional token step: one call at the start of each run that returns a token for the item reads.
  • Where each field sits in the response, as a dot path such as data.attributes.title:

​
3. The playback URL

Pick one:
  • A field in the API answer that holds the HLS master playlist URL.
  • A manifest URL template when your playback URL follows from the id. It is an https URL with {id} in the path or query, for example https://play.example.com/{id}/master.m3u8. The id is URL-encoded. The host is fixed in the template, so an id can never pick the host.
HLS (HTTP Live Streaming) is the streaming format that uses .m3u8 playlists.

​
4. Your stream hosts

AgentTV plays and reads streams only from hosts on your account’s allow list. Send us each stream host, and each caption host if it differs. Rules:
  • https only. No ports, no credentials, no private addresses.
  • One account’s list never serves another account’s video.
  • To remove a host later, tell us. Videos on that host stop importing and playing through AgentTV.
AgentTV reads your API and plays your streams only after you give your written OK.

​
Pick what to import

Nothing from your back catalog imports on its own. In the console, open Imports and the Video catalog card. You browse your catalog newest first, search it, and pick videos. One pick takes up to 100 videos. AgentTV copies and processes them in the background. The account MCP tool import_catalog_items (POST /v1/catalog-source/imports) does the same. See Account tools. Each video shows a status:

​
New videos and the daily sync

The day you connect the catalog sets the baseline. Every video listed then is back catalog. A video that first appears after that is a new video. Once a day, AgentTV reads your catalog again. It refreshes imported videos whose lastmod moved, and it handles new videos by your new video policy: Under automatic and review_first, videos you already imported still refresh.

​
What is refused

A video does not import when its stream is:
  • Encrypted or DRM protected. AgentTV cannot read the media.
  • Live. Only finished video on demand imports. A live slot with no replay shows as “stream not found”.
  • Byte-range. Playlists that address segments by byte range.
  • On a host that is not on your list.
  • Too large. The largest copy is 40 GB, enough for a 14 hour replay at 6 Mbps.
AgentTV also refuses a child sitemap on another host, and an API redirect off your API origin. AgentTV also skips a feed item past its expires (item_expired) and a feed item whose window is not two numbers with the start before the end (window_malformed). The reason shows on the video in the console, for example media_encrypted, live_playlist, media_byterange, stream_host_not_allowed or media_too_large. A few reasons can pass on their own (stream_unreachable, copy_failed, metadata_unreadable). Pick those videos again to retry.

​
Long videos

The import handles event replays of 4 to 14 hours and several GB. A copy that stops halfway resumes where it stopped. Transcription takes at most 10 hours of audio per file. For a longer replay, import one time range of it.

​
Import one time range

You can import only part of a video, for example one day of a multi-day replay. In the console, set the range on the video before you pick it. With import_catalog_items, send windows: one start_seconds and end_seconds per picked video, in seconds of the video as your source plays it.
  • The imported video is that range. Its times start at 0 at the range’s start.
  • HLS is cut on whole segments, so the range widens to the segment edges.
  • A range can be at most window_max_seconds long. get_catalog_source returns that limit.
  • A video your JSON Feed gives a window keeps the feed’s range.