Quickstart

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.

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

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();

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):

{
  "@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, 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.

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.

{
  "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.

Put metadata on your pages

Render the block in your page, with caching.

Play a moment in an AI app

Connect Claude or ChatGPT and play the cited second.

Concepts

Crawl time, inference time, the ARV record and rights.

API reference

Every public and account endpoint.

Get started

1. Find a moment

2. Fetch the block for your own video

Next

Put metadata on your pages

Play a moment in an AI app

Concepts

API reference

​1. Find a moment

​2. Fetch the block for your own video

​Next

Put metadata on your pages

Play a moment in an AI app

Concepts

API reference

1. Find a moment

2. Fetch the block for your own video

Next