API Endpoints
Complete reference for all VideoNest REST API endpoints including videos, channels, and distribution.
Base URL
All VideoNest REST API requests are made to:
https://api.videonest.co/v1
Authentication
All requests require a Bearer token in the Authorization header. See API Authentication for how to generate and use your API key.
Available resource areas
- Videos — list, retrieve, update, and delete videos in your library
- Channels — read and update channel settings
- Feeds — list and manage distribution feeds
- Analytics — retrieve view and performance data
Videos
GET /videos
Returns a paginated list of videos in your library.
GET /videos?page=1&per_page=25&channel_id=ch_abc123
Query parameters: page (default 1), per_page (default 25, max 100), channel_id (filter by channel), status (filter by processing, ready, or failed).
{
"data": [
{
"id": "vid_abc123",
"title": "My Video Title",
"status": "ready",
"duration": 142,
"created_at": "2026-03-01T12:00:00Z",
"thumbnail_url": "https://cdn.videonest.co/thumbnails/vid_abc123.jpg",
"embed_url": "https://embed.videonest.co/v/vid_abc123"
}
],
"meta": { "page": 1, "per_page": 25, "total": 84 }
}GET /videos/:id
Returns a single video by ID.
GET /videos/vid_abc123
POST /videos
Creates a new video record and returns an upload URL. Upload the video file directly to the returned upload_url using a PUT request with the file as the request body.
POST /videos
Content-Type: application/json
{
"title": "My Video Title",
"description": "Optional description",
"channel_id": "ch_abc123",
"tags": ["news", "sports"]
}{
"id": "vid_newxyz",
"upload_url": "https://upload.videonest.co/...",
"status": "pending"
}PATCH /videos/:id
Updates metadata for an existing video. All fields are optional.
PATCH /videos/vid_abc123
Content-Type: application/json
{
"title": "Updated Title",
"description": "Updated description",
"tags": ["finance", "markets"]
}DELETE /videos/:id
Permanently deletes a video and all associated assets. This action cannot be undone.
DELETE /videos/vid_abc123
Deleting a video removes it from all distribution feeds and embed URLs immediately. Embed iframes on external pages will display a "video not found" state.
Channels
GET /channels
Returns all channels on your account.
GET /channels
{
"data": [
{
"id": "ch_abc123",
"name": "My Channel",
"slug": "my-channel",
"video_count": 84,
"created_at": "2025-01-15T09:00:00Z"
}
]
}PATCH /channels/:id
Updates channel settings. Supports updating name, description, and default_player_settings.
PATCH /channels/ch_abc123
Content-Type: application/json
{
"name": "Updated Channel Name",
"description": "New channel description"
}Feeds
GET /feeds
Returns all active distribution feeds for your account, including MRSS, podcast, and CTV feeds.
GET /feeds
{
"data": [
{
"id": "feed_xyz789",
"name": "MSN News Feed",
"type": "mrss",
"channel_id": "ch_abc123",
"url": "https://feeds.videonest.co/mrss/feed_xyz789",
"last_published_at": "2026-03-28T14:00:00Z"
}
]
}POST /feeds/:id/publish
Triggers an immediate publish of the specified feed, refreshing it with the latest eligible videos.
POST /feeds/feed_xyz789/publish
{
"feed_id": "feed_xyz789",
"status": "published",
"published_at": "2026-03-30T10:15:00Z",
"video_count": 12
}Analytics
GET /analytics/videos
Returns view and engagement metrics for videos. Supports filtering by video ID, channel, and date range.
GET /analytics/videos?video_id=vid_abc123&from=2026-03-01&to=2026-03-30
{
"video_id": "vid_abc123",
"period": { "from": "2026-03-01", "to": "2026-03-30" },
"views": 14230,
"unique_viewers": 11800,
"avg_watch_time_seconds": 87,
"completion_rate": 0.61
}GET /analytics/overview
Returns aggregate metrics for the full account or a specified channel across a date range.
GET /analytics/overview?channel_id=ch_abc123&from=2026-03-01&to=2026-03-30
{
"period": { "from": "2026-03-01", "to": "2026-03-30" },
"total_views": 284500,
"unique_viewers": 198000,
"top_videos": [
{ "id": "vid_abc123", "title": "My Video Title", "views": 14230 }
]
}A client SDK with type definitions and example code is available. See the API Authentication page for a link to the GitHub repository.