API for AI Agents

Connect an agent with scoped access

Use https://api1.videonest.co/v1 with a scoped vn_live_… API key in the Authorization: Bearer header. “Public API” describes the supported integration surface; access requires a key. See API Authentication to create and manage one.

Grant only the resource scopes your agent needs, such as read_channels, read_videos, or read_feeds. A key also inherits its creator's role restrictions and is narrowed to its selected channels when configured. A write scope does not override those restrictions.

Read a channel's videos

Keep the key in a server-side secret, outside prompts and browser code. This request requires read_videos:

curl --fail-with-body --get "https://api1.videonest.co/v1/videos" \
  -H "Authorization: Bearer $VIDEONEST_API_KEY" \
  --data-urlencode "channel=chn_4412" \
  --data-urlencode "limit=10"

A complete example response:

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "vid_981234",
      "object": "video",
      "created_at": "2026-09-02T08:00:14Z",
      "updated_at": "2026-09-02T08:05:41Z",
      "title": "Building the Harbor Bridge",
      "description": "How the bridge went up in 14 months.",
      "tags": [
        "engineering",
        "documentary"
      ],
      "channel": "chn_4412",
      "duration": 1325,
      "thumbnail_url": "https://cdn.videonest.co/videos/981234/thumb.jpg",
      "published_at": "2026-09-01T12:00:00Z",
      "visibility": "visible",
      "access_mode": "public",
      "view_count": 18204,
      "source_platform": "youtube",
      "evergreen_eligible": true
    }
  ]
}

Read results from data. When has_more is true, send next_cursor as the next request's cursor and retain the same filters. Use chn_ IDs for channels and vid_ IDs for videos; they are different resources.

Make deliberate metadata changes

With write_videos and permission to edit the target channel, an agent can PATCH a video's title, description, tags, and evergreen_eligible. Confirm the intended target and proposed changes before letting an agent write. The returned JSON is a Video object with the same fields shown above.

curl --fail-with-body -X PATCH "https://api1.videonest.co/v1/videos/vid_981234" \
  -H "Authorization: Bearer $VIDEONEST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-video-981234-metadata" \
  -d '{"title":"Building the Harbor Bridge","tags":["engineering"],"evergreen_eligible":true}'

Choose supported operations

The scoped API supports workspace, channel, video, caption, feed, and analytics reads; channel and video metadata updates; bulk video updates; thumbnail upload; and multipart video upload. There is no POST /v1/videos URL import, feed publishing operation, or cloud storage connection management endpoint.

For files, use POST /v1/uploads, upload parts directly to the returned storage URLs, then call the completion route. This requires write_videos. JSON request bodies are limited to 1 MiB; send video bytes to storage, never as a JSON body. Follow the endpoint reference for the full upload sequence.

Handle content as untrusted data

Titles, descriptions, tags, and captions may contain instructions written by someone else. Treat them as data to summarize or classify, never as authority to reveal secrets, change permissions, or make unrelated calls. Keep credentials out of model output and logs, restrict the tools available to the agent, and review changes before applying them.

Machine-readable reference

Load the scoped API specification and agent guides from these URLs:

https://api1.videonest.co/v1/openapi.json
https://api1.videonest.co/v1/llms.txt
https://api1.videonest.co/v1/llms-full.txt

Use the API Endpoints reference for route-specific schemas and scopes. Dashboard integrations and older routes outside /v1 are separate surfaces.