> ## 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.

# Quickstart

> Find the exact moment in a video with one request, then fetch the metadata block for one of your own videos.

This page makes two requests. The first runs now, with no account and no key. The second runs once your catalog is imported.

## 1. Find a moment

Search a public library in plain words. This one is a public sample library, `sandersaar`.

```bash curl theme={null}
curl -s "https://api.agentcdn.com/public/creators/sandersaar/ask?q=robot%20pouring%20latte%20art&max_results=1"
```

```js JavaScript theme={null}
const url = new URL("https://api.agentcdn.com/public/creators/sandersaar/ask");
url.searchParams.set("q", "robot pouring latte art");
url.searchParams.set("max_results", "1");
const results = await (await fetch(url)).json();
```

```python Python theme={null}
import requests

results = requests.get(
    "https://api.agentcdn.com/public/creators/sandersaar/ask",
    params={"q": "robot pouring latte art", "max_results": 1},
    timeout=30,
).json()
```

The response, as returned on 2026-10-28, shortened (each item also carries `description` and `creator`):

```json theme={null}
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "AgentTV results for \"robot pouring latte art\"",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "relevanceScore": 0.440559440559441,
      "matchField": "transcript",
      "item": {
        "@type": "VideoObject",
        "@id": "https://agenttv.com/creators/sandersaar#video_t82C_EYja18",
        "name": "Top 10 Tech Experiences in China - Future of Tech",
        "url": "https://www.youtube.com/watch?v=t82C_EYja18&t=38s",
        "thumbnailUrl": "https://i.ytimg.com/vi/t82C_EYja18/hqdefault.jpg",
        "uploadDate": "2026-04-08T18:20:30.000Z",
        "duration": "PT2M59S",
        "potentialAction": {
          "@type": "WatchAction",
          "target": "https://api.agentcdn.com/public/creators/sandersaar/videos/video_t82C_EYja18/watch#t=38,90",
          "startOffset": 38.071,
          "endOffset": 89.093
        }
      }
    }
  ]
}
```

The answer is at 38 seconds into a 3 minute video. `startOffset` and `endOffset` are the moment, in seconds. `url` opens the video at that second. The response holds no stream URL: search never returns one.

Set a client timeout of at least 30 seconds. When the library has no answer, the list is empty and the response carries `no_answer`.

## 2. Fetch the block for your own video

Once [your catalog is imported](https://docs.agentcdn.com/guides/import-catalog.md), fetch the page block for one video by the id your own platform uses for it. The page block is the metadata search engines and AI apps read for that video. URL-encode the id: colons become `%3A`.

```bash theme={null}
curl -s "https://api.agentcdn.com/public/creators/your-brand/page-blocks/catalog%3Avideo%3A1234"
```

A `200` returns one JSON object. This example is shortened: real blocks carry every chapter and every transcript line.

```json theme={null}
{
  "contract_version": "video-page-block/1",
  "customer_video_id": "catalog:video:1234",
  "video_id": "vid_123",
  "json_ld": {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "VideoObject",
        "name": "Building the ramp",
        "uploadDate": "2026-10-01T09:00:00.000Z",
        "duration": "PT4M0S",
        "hasPart": [
          { "@type": "Clip", "name": "The landing", "startOffset": 60, "endOffset": 120, "url": "https://agenttv.com/creators/your-brand/videos/vid_123/watch?t=60" }
        ]
      },
      { "@type": "BreadcrumbList", "itemListElement": [] }
    ]
  },
  "transcript": { "cues": [{ "start_seconds": 63, "text": "The rider lands the backflip on the second attempt." }] },
  "discovery": { "links": [{ "rel": "agent-ready-video", "type": "application/json", "href": "https://api.agentcdn.com/public/creators/your-brand/arv.json" }] },
  "head_html": "<script type=\"application/ld+json\">...</script>\n<link rel=\"agent-ready-video\" ...>",
  "body_html": "<div class=\"agentcdn-evidence\">...</div>",
  "fingerprint": "sha256:...",
  "cache_policy": { "visibility": "public", "max_age_seconds": 300, "stale_while_revalidate_seconds": 300 }
}
```

A `404` with `{"error": "owned_web_artifact_unavailable"}` means the id is not in your library, the video is not public, or its rights block citation. If your account is unlisted, send your API key. See [Listed and unlisted accounts](https://docs.agentcdn.com/concepts/accounts.md).

## Next

> [card] [Put metadata on your pages](https://docs.agentcdn.com/guides/page-metadata.md)
>
> Render the block in your page, with caching.

> [card] [Play a moment in an AI app](https://docs.agentcdn.com/guides/play-in-chat.md)
>
> Connect Claude or ChatGPT and play the cited second.

> [card] [Concepts](https://docs.agentcdn.com/concepts/crawl-and-inference.md)
>
> Crawl time, inference time, the ARV record and rights.

> [card] [API reference](https://docs.agentcdn.com/api-reference/overview.md)
>
> Every public and account endpoint.


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