REST API

Base URL

All paths are relative to:

https://api.vidiyo.com

Authentication

Pass your token in the Authorization header. For automation, use a creator API key. Generate one in Studio → Account → API Keys.

Authorization: Bearer vk_live_...

Scopes

API keys are scoped. Requests from a key missing a required scope receive 403 forbidden. Session-authenticated callers (browser or TV) are not scope-restricted.

Errors

Every non-2xx response uses this envelope:

{
  "error": {
    "code": "schedule.overlap",
    "message": "That time slot already has a block.",
    "details": { "conflictingBlockId": "01936f4e-..." },
    "requestId": "req_01HJ..."
  }
}

Pagination

List endpoints page by cursor. Send limit for the page size and pass the response's nextCursor back as cursor for the next page. nextCursor is null on the last page. A cursor belongs to one sort and filter set. Change either and start again without it.

GET /v1/creator/content?sort=title&limit=50
GET /v1/creator/content?sort=title&limit=50&cursor=eyJ2IjoiRXBpc29kZSA5IiwiaWQiOiIwMTkzLi4uIn0

{ "items": [...], "meta": { "limit": 50, "nextCursor": "eyJ2Ijo...", "has_more": true } }

The older page and per_page parameters still work until 4 March 2027. Responses that use them carry Deprecation and Sunset headers. After that date they are ignored and every list answers in the cursor form.

API Keys — /v1/creator/api-keys

Create and revoke long-lived API keys for automated access. The plaintext token is returned once on creation. List and create operations require a session (browser or TV token). API keys cannot create other keys.

Create a key — request body

{
  "name": "My video agent",           // required, 1–100 chars
  "scopes": ["content:write", "schedule:write"],  // required, at least one
  "expiresInDays": 90                 // optional; omit for non-expiring
}

Create a key — response

{
  "key": {
    "id": "01936f4e-...",
    "name": "My video agent",
    "keyPrefix": "vk_live_Ab1cD2",   // first 16 chars, safe to display
    "scopes": ["content:write", "schedule:write"],
    "expiresAt": "2026-08-01T00:00:00.000Z",
    "createdAt": "2026-05-03T09:00:00.000Z",
    "token": "vk_live_Ab1cD2..."     // full plaintext — shown ONCE
  }
}

Uploads — /v1/creator/uploads

Two-step direct-to-R2 upload. Init returns a presigned URL; your client PUTs the bytes directly to R2 (no Vidiyo server in the upload path), then calls complete to trigger transcoding.

Init request body

{
  "filename": "episode-1.mp4",
  "title": "Episode 1",
  "contentType": "video/mp4",
  "sizeBytes": 52428800,
  "channelId": "01936f4e-..."         // optional — attach immediately
}

Init response

{
  "contentItemId": "01936f4e-...",
  "objectKey": "uploads/.../episode-1.mp4",
  "uploadUrl": "https://r2.vidiyo.com/...?X-Amz-Signature=...",
  "expiresInSeconds": 900
}

Content — /v1/creator/content

Manage content items in your library. Filter by status to find ready-to-schedule videos.

List query parameters

Content status lifecycle

uploading → pending_transcode → transcoding → [pending_moderation →] ready
                                           ↘ failed (retry / cancel-and-retry via POST /:id/retry)

Only ready items can be placed on a schedule. Poll until the status field equals ready.

Schedule — /v1/creator/schedule

Manage the EPG (electronic programme guide) for your channels. Blocks are non-overlapping; the API returns 409 with conflictingBlockId if you try to place a block in an occupied slot.

GET parameters

GET /v1/creator/schedule?channelId=UUID&from=2026-05-03T00:00:00Z&to=2026-05-04T00:00:00Z

POST body (create block)

{
  "channelId": "01936f4e-...",
  "contentItemId": "01936f4e-...",   // must have status "ready"
  "startsAt": "2026-05-03T14:00:00Z",
  "kind": "content",
  "durationSeconds": 1800             // optional; defaults to content's transcoded duration
}

GET response

{
  "channelId": "01936f4e-...",
  "from": "2026-05-03T00:00:00.000Z",
  "to": "2026-05-04T00:00:00.000Z",
  "blocks": [
    {
      "id": "01936f4e-...",
      "startsAt": "2026-05-03T14:00:00.000Z",
      "endsAt": "2026-05-03T14:30:00.000Z",
      "durationSeconds": 1800,
      "kind": "content",
      "content": { "id": "...", "title": "Episode 1", "status": "ready", ... }
    }
  ],
  "gaps": [
    { "from": "2026-05-03T00:00:00.000Z", "to": "2026-05-03T14:00:00.000Z" }
  ],
  "total": 1
}

Channels — /v1/creator/channels

Analytics — /v1/creator/analytics

Brand Kits / Your brand: /v1/brands

Branded viewer surfaces scoped to a channel allowlist. Pass X-Vidiyo-Brand or ?brand= on discovery endpoints to scope the catalog. Product overview: Your brand. MCP tools: Brand Kit MCP.

Rate limits

Limits apply per user (authenticated) or per IP (anonymous). All limits use a sliding window. Responses include Retry-After when limited.