Add Ask to your site

Ask lets a visitor type a question and get a short answer with the moments behind it. It answers only from your videos. When your videos do not answer the question, it says so and does not guess. There are two ways to add it:

The Ask box. One script tag. It plays moments from YouTube. Needs a listed account.
Your own Ask. Your page calls the API and plays each moment in your own player. Works for any account. See Build your own Ask.

Suggested questions come with every library, generated from your videos. You can also set the featured questions your pages offer with PUT /v1/featured-questions.

Add the script tag

Library Ask, for an index or home page. It searches every video in your library:

<script src="https://agenttv.com/creator-ask/v1.js" data-creator="your-brand" async></script>

Video Ask, for one video’s page. It answers from that video only:

<script src="https://agenttv.com/creator-ask/v1.js" data-creator="your-brand" data-video="vid_123" async></script>

Put the tag in the page body where the box should appear. The box renders right after the tag. You can load the tag more than once on a page. Each tag gets its own box.

Attributes

Attribute	Required	Value	What it does
`data-creator`	Yes	Your account slug, for example `your-brand`	Picks the library Ask answers from.
`data-video`	No	The AgentTV video id (for example `vid_123`) or the YouTube video id	Answers from that video only. If the video is not in your library, the box answers from the whole library.
`data-target`	No	A CSS selector, for example `#video-ask`	Renders the box inside that element instead of after the tag.
`data-theme`	No	`light` (default), `dark` or `auto`	`auto` follows the visitor’s system setting.
`data-key`	No	A browser Ask key	Raises the limits and counts answers to your account. See Ask keys.

data-video takes letters, digits, _ and - only. Your own platform ids, such as catalog:video:1234, do not work there. Use the AgentTV video id. The page block’s video_id field gives it.

Example

<div id="video-ask" style="min-height:420px"></div>
<script src="https://agenttv.com/creator-ask/v1.js"
        data-creator="your-brand"
        data-video="vid_123"
        data-target="#video-ask"
        async></script>

The min-height keeps the page from moving when the box loads.

Content Security Policy

If your site sets a Content Security Policy, allow these:

script-src https://agenttv.com
connect-src https://api.agentcdn.com
frame-src https://www.youtube-nocookie.com
img-src https://i.ytimg.com

Match your look

The box renders in its own isolated area. Your CSS does not change it, and its CSS does not change your page. To use your own colors or font, set these on the box:

.agentcdn-ask {
  --agentcdn-ask-accent: #0b5cad;
  --agentcdn-ask-accent-fg: #ffffff;
  --agentcdn-ask-bg: #ffffff;
  --agentcdn-ask-fg: #20201e;
  --agentcdn-ask-muted: #62625d;
  --agentcdn-ask-border: #deded9;
  --agentcdn-ask-font: inherit;
  --agentcdn-ask-radius: 16px;
}

The box carries data-state (loading, ready or error) if you want to style it while it loads.

How moments play

The Ask box plays moments from YouTube, in the box, starting at the cited second. A moment YouTube cannot play shows a link to the source page instead. The Ask box does not play your own player or your own HLS stream. For a catalog that is not on YouTube, each moment shows a link to your page. To play moments in your own player, build your own Ask.

Build your own Ask

Your page sends the question to AgentTV and plays each moment in your own player at its start second. You own the look, the player and the tracking.

Listed account
Unlisted account

Call the Ask route from your server with a server Ask key, or from the browser with a browser Ask key:

curl -s -X POST https://api.agentcdn.com/public/creators/your-brand/managed-ask \
  -H "Authorization: Bearer $AGENTCDN_ASK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Who won the women'\''s final?", "video_id": "vid_123"}'

Leave out video_id to answer from the whole library. The body also takes youtube_video_id in place of video_id, max_results, and cursor for the next page. The answer holds a short text and the moments behind it, each with its video id and start and end time.

Call the account API from your server, with an account API key. Never from the browser.

curl -s -X POST https://api.agentcdn.com/v1/ask \
  -H "Authorization: Bearer $AGENTCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Who won the women'\''s final?", "video_id": "vid_123", "include_private": false}'

For a fast jump with no written answer, such as “take me to the second set”, use POST /v1/moments. See Build a rail from chapters.

Moments name videos by the AgentTV video_id. The page block of each video gives you both ids, so map them once when you render the page. Then open your player at the moment’s start with your start parameter.

Ask keys

Ask works without a key. A key raises your limits and counts every answer to your account, so you can see usage per key. Create Ask keys in the console on the Ask page screen, in the Ask keys card. A key looks like agcdn_ask_.... The full key shows once.

Kind	How you make it	Where it lives	Sent as
Browser key	List your sites under “Allowed websites”	In the script tag on those sites	`data-key="agcdn_ask_..."`
Server key	Leave “Allowed websites” empty	Your server or agent only. Never in a web page.	`Authorization: Bearer agcdn_ask_...`

A browser key is visible to anyone who opens your page. That is expected. It works only from the sites you list. Rules for allowed websites:

One exact origin per line, for example https://www.example.com. No paths and no wildcards.
https only. http works for localhost and 127.0.0.1, for local tests.
Up to 20 sites per key.

A server key sent from a browser is refused with access_key_requires_origin_allowlist. If you see that error, the key is exposed. Rotate it and use a browser key. Rotate makes a new key with the same settings. The old key keeps working for 24 hours, then stops. Revoke stops a key within a minute.

Limits

Caller	Ask answers
No key	A limit per visitor network
Browser key	A limit per visitor network, plus the key’s own limit
Server key	The key’s limit: 1,200 a minute, bursts of 200. Ask us to raise it.

These limits cover the Ask box and the Ask routes: managed-ask, moment-agent and ask-widget.json. Plain search (GET /public/creators/{slug}/ask) has its own limit of 60 calls a minute per caller. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers with the limits in force. Past a limit, Ask answers 429 with a Retry-After header in seconds. Your plan includes a number of Asks per calendar month. Every Ask that runs counts, also one that finds no answer. Errors and refused over-limit requests do not.

Errors

Status	Message	What to do
401	`invalid_access_key`	The key is wrong, revoked or past its rotation window.
403	`access_key_scope_denied`	Use a key with the `ask` scope.
403	`access_key_creator_mismatch`	Use the key made for this library.
403	`access_key_origin_not_allowed`	Add this site to the key’s allowed websites.
429	`public_ask_rate_limited`, `access_key_rate_limited`	Wait `Retry-After` seconds.
429	`ASK_BUDGET_EXHAUSTED`	The month’s Asks are used up and Ask is paused. This error comes in the ARV error envelope, with `retry_after_ms`.

What visitors see

A short answer, then the moments behind it, each with a Play button.
Up to three suggested questions.
If Ask is unavailable, the box says so and keeps its size. Your page keeps working.
The box fits its column, down to phone widths.

What is measured

The questions people ask show in the console on the Questions page. The box sets no cookies and loads no third-party trackers. It stores no IP addresses. Email addresses and long numbers in questions are masked. Question text is deleted after 90 days.

Your videos

Playback and AI apps

Audience and members

On your site

Measure

Add Ask to your site

Add the script tag

Attributes

Example

Content Security Policy

Match your look

How moments play

Build your own Ask

Ask keys

Limits

Errors

What visitors see

What is measured

​Add the script tag

​Attributes

​Example

​Content Security Policy

​Match your look

​How moments play

​Build your own Ask

​Ask keys

​Limits

​Errors

​What visitors see

​What is measured

Add the script tag

Attributes

Example

Content Security Policy

Match your look

How moments play

Build your own Ask

Ask keys

Limits

Errors

What visitors see

What is measured