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

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 (retryable 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

Rate limits

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