> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcdn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Ask to your site

> Add an Ask box with one script tag, or build your own Ask that plays moments in your own player.

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](https://docs.agentcdn.com/concepts/accounts.md).
* **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](#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:

```html theme={null}
<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:

```html theme={null}
<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](#ask-keys). |

> [!NOTE]
>
> `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

```html theme={null}
<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:

```text theme={null}
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:

```css theme={null}
.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.

> [tab] Listed account
>
> Call the Ask route from your server with a server Ask key, or from the browser with a browser Ask key:
>
> ```bash theme={null}
> 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.

> [tab] Unlisted account
>
> Call the account API from your server, with an account API key. Never from the browser.
>
> ```bash theme={null}
> 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](https://docs.agentcdn.com/guides/moment-rails.md#4-let-people-jump-by-asking).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.