Put metadata on your pages

​

The request

GET https://api.agentcdn.com/public/creators/{slug}/page-blocks/{customer_video_id}?format=json

​

Render it server side

// Fetch the block while rendering a video page.
const base = "https://api.agentcdn.com/public/creators/your-brand/page-blocks/";

async function pageBlock(customerVideoId) {
  const response = await fetch(base + encodeURIComponent(customerVideoId));
  if (response.status === 404) return null; // Render the page without the block.
  if (!response.ok) throw new Error(`page block ${response.status}`);
  return response.json();
}

​

One VideoObject per page

• You render no VideoObject. Put head_html (or the format=head response) in your page head as it is.
• You already render a VideoObject. Use format=json. Take the fields you lack from json_ld["@graph"][0], most of all hasPart (the chapters as Clip items), and add them to your own object. Keep your own @id, url, embedUrl, contentUrl and player fields. Then render each of discovery.links as a <link> tag in your head.

<!-- Discovery links, from discovery.links -->
<link rel="agent-ready-video" type="application/json" href="https://api.agentcdn.com/public/creators/your-brand/arv.json">
<link rel="mcp-server" href="https://mcp.agentcdn.com/c/your-brand/mcp">

​

Point chapter links at your own page

{ "@type": "Clip", "name": "The landing", "startOffset": 60, "endOffset": 120, "url": "https://www.example.com/videos/1234?t=60" }

​

WebMCP tags when you merge

<script id="agentcdn-webmcp-config" type="application/json">{"creator_slug":"your-brand","video_id":"vid_123","endpoint_base":"https://api.agentcdn.com/api/webmcp/v1/sites/your-brand"}</script>
<script type="module" src="https://agenttv.com/webmcp/v1/adapter.js?v=1.2.0"></script>

​

Chapters and the transcript

• Chapters come as Clip items in the JSON-LD, with a name, a description, and start and end offsets in seconds.
• The transcript comes as transcript.cues, each with start_seconds and text. It is never inside the JSON-LD.
• body_html is ready HTML with the chapter summaries and the transcript, with plain timestamps and no links. Put it in your page body, or build your own section from transcript.cues.

​

Parts

"parts": [
  {
    "id": "part_1",
    "title": "Semifinal: Team A against Team B",
    "description": "The first semifinal, from the walk-on to the final point.",
    "start_ms": 0,
    "end_ms": 4980000,
    "thumbnail_url": "https://api.agentcdn.com/...",
    "source_ref": null,
    "chapters": [
      { "id": "ch_1", "title": "Walk-on", "start_ms": 0, "end_ms": 240000, "thumbnail_url": "https://api.agentcdn.com/...", "source_ref": null }
    ]
  }
]

• parts is [] when the video has none.
• Times are in milliseconds from the start of the video.
• A thumbnail_url is null when your rights do not allow showing the picture.
• On a read with your account key, each thumbnail_url is a signed frame URL that is valid for about an hour. Fetch the block again for fresh URLs. Do not store them as permanent links.

​

Language

​

Caching and traffic

Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=300
ETag: "sha256:..."

• Your CDN may keep a block for 5 minutes and serve it stale for 5 more while it refreshes. A rights change reaches your pages within 10 minutes.
• Send the ETag back as If-None-Match. An unchanged block returns 304 with no body. Each format has its own ETag.
• There is no purge call. To refresh at once, listen for the video.updated webhook and fetch again.
• Every 404 is Cache-Control: private, no-store. A newly published video shows on the next request.
• An unlisted account’s key read is always private, no-store. Cache it in your own server, keyed by video id, and refresh on the webhook.
• A key read also has an ETag and answers a matching If-None-Match with 304. Its ETag changes every hour, with the signed frame URLs, so a 304 means your cached URLs are still valid. To tell a real content change from the hourly re-signing, compare the x-agentcdn-content-version header. It changes only when the content changes.

​

When there is no block

• the id is unknown, or belongs to another account,
• the video is not published, or not public on a listed account,
• the video’s rights block citation,
• the format value is not one of the three above.