Reference#

Base URL: https://api.xonaplay.com. The endpoint list below is generated from our OpenAPI file, /openapi.json.

Authentication#

A key acts on its whole workspace. Create, list and revoke keys in the dashboard under Settings → API. A revoked key answers 401 INVALID_KEY.

Conventions#

• JSON in and out, always snake_case.
• Success: { "status": "ok", "data": … }. Lists add "meta": { "total": 120, "page": 1, "per_page": 20, "last_page": 6 }.
• Error: { "status": "error", "code": "NOT_FOUND", "message": "…" }. Codes are uppercase and stable; messages are for humans and may change.
• Validation errors are 422 with errors: [{ "field": "title", "message": "…" }].
• Ids: every {id} accepts the UUID id or the short_id.
• Timestamps: ISO 8601 in UTC.
• Pagination: ?page=1&per_page=20 (max 100).

Video and live objects#

GET /v1/videos/{id} and GET /v1/live/{id} return the same object our own dashboard uses — nothing is stripped for the public API.

• links.player is the public share page (the one you embed in an iframe). It is not a video file.
• links.hls only plays on Open; on every other level it is protected and answers 403 TOKEN_REQUIRED without a token. To play in your own player, always call /playback instead.
• custody, engine, compute_engine and storage_profile describe where XonaPlay stores and renders the video (our storage or yours, which engine did the work). Safe to ignore for most integrations.
• playback_security is the per-video override of the workspace default: inherit, open, protected, strict or maximum.
• delivery is hls (default) or original: whether XonaPlay renders HLS from the untouched original. See Original or HLS.

Rate limits#

Over the limit you get 429 RATE_LIMITED with a Retry-After header (in seconds) telling you how long to wait before the next request. The 600/min key bucket only applies to a valid secret key; an invalid or revoked one falls back to the lower anonymous-IP limit.

Webhooks#

Register an HTTPS endpoint in Settings → API → Webhooks (or with POST /v1/webhooks). We POST:

{
  "id": "evt_5c1f0e7a9b2d4c3e",
  "type": "video.ready",
  "created_at": "2026-10-09T01:30:00.000Z",
  "data": {
    "video": {
      "id": "0f8e2c7a-…",
      "short_id": "9KfR2mQx",
      "title": "Lesson 1",
      "status": "ready",
      "duration_sec": 3600
    }
  }
}

live.started and live.ended carry a different key: data.live (a live stream object — id, short_id, name, status, …), not data.video:

{
  "id": "evt_8a2d4c3e9b2d4c3e",
  "type": "live.started",
  "created_at": "2026-10-09T01:32:00.000Z",
  "data": {
    "live": {
      "id": "3b7f0c1a-…",
      "short_id": "7qLp3Zxa",
      "name": "Weekly class",
      "status": "live"
    }
  }
}

• Signed with X-Xona-Signature: t=<unix seconds>,v1=<hex> where v1 is HMAC-SHA256 of "<t>.<raw body>" with your endpoint secret (whsec_…, shown once). See the verification recipe.
• Answer any 2xx within 10 seconds. Anything else is retried after 1 min, 5 min, 30 min, 2 h and 6 h; then the delivery is marked failed.
• Deliveries can arrive more than once or out of order: use id to dedupe and re-read the video if order matters.

Videos#

List, read, update and delete videos, and get a signed playback link.

GET /v1/videos#

List videos

Videos of the authenticated workspace, merged from every engine (platform custody and BYO), newest first. Paginated.

Responses

• 200 — Paginated list of videos.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).

{
  "status": "",
  "data": [
    {
      "id": "",
      "short_id": "",
      "title": "",
      "slug": "",
      "description": "",
      "status": "",
      "visibility": "",
      "playback_security": "",
      "delivery": "",
      "source_type": "",
      "duration_sec": "",
      "width": "",
      "height": "",
      "size_original_bytes": "",
      "size_processed_bytes": "",
      "qualities": [
        ""
      ],
      "custody": "",
      "engine": "",
      "compute_engine": "",
      "storage_profile": "",
      "links": {
        "player": "",
        "hls": "",
        "poster": ""
      },
      "metadata": "",
      "created_at": "",
      "updated_at": ""
    }
  ],
  "meta": {
    "total": "",
    "page": "",
    "per_page": "",
    "last_page": ""
  }
}

GET /v1/videos/{video_id}#

Get a video

Accepts either the id (UUID) or the short_id.

Responses

• 200 — The video.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No video with that id or short_id (NOT_FOUND).

{
  "status": "",
  "data": {
    "id": "",
    "short_id": "",
    "title": "",
    "slug": "",
    "description": "",
    "status": "",
    "visibility": "",
    "playback_security": "",
    "delivery": "",
    "source_type": "",
    "duration_sec": "",
    "width": "",
    "height": "",
    "size_original_bytes": "",
    "size_processed_bytes": "",
    "qualities": [
      ""
    ],
    "custody": "",
    "engine": "",
    "compute_engine": "",
    "storage_profile": "",
    "links": {
      "player": "",
      "hls": "",
      "poster": ""
    },
    "metadata": "",
    "created_at": "",
    "updated_at": ""
  }
}

PATCH /v1/videos/{video_id}#

Update a video

Partial update. playback_security overrides the workspace default for this video only; it is rejected on BYO-engine videos (NOT_SUPPORTED_FOR_BYO) and maximum requires the staff opt-in for the workspace (MAXIMUM_NOT_ALLOWED).

Request body

• title: string
• slug: string
• visibility: object
• playback_security: object
• delivery: string
• metadata: object

Responses

• 200 — The updated video.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No video with that id or short_id (NOT_FOUND).
• 422 — Validation failed, playback_security=maximum without the workspace opt-in (MAXIMUM_NOT_ALLOWED), or an override on a BYO video (NOT_SUPPORTED_FOR_BYO).

{
  "status": "",
  "data": {
    "id": "",
    "short_id": "",
    "title": "",
    "slug": "",
    "description": "",
    "status": "",
    "visibility": "",
    "playback_security": "",
    "delivery": "",
    "source_type": "",
    "duration_sec": "",
    "width": "",
    "height": "",
    "size_original_bytes": "",
    "size_processed_bytes": "",
    "qualities": [
      ""
    ],
    "custody": "",
    "engine": "",
    "compute_engine": "",
    "storage_profile": "",
    "links": {
      "player": "",
      "hls": "",
      "poster": ""
    },
    "metadata": "",
    "created_at": "",
    "updated_at": ""
  }
}

DELETE /v1/videos/{video_id}#

Delete a video

only_original=true keeps the processed renditions and deletes only the source file.

Responses

• 200 — Deleted.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No video with that id or short_id (NOT_FOUND).

{
  "status": "",
  "data": {
    "deleted": true,
    "only_original": true
  }
}

GET /v1/videos/{video_id}/download#

Download the original file

Short-lived signed link (1 hour) to the original exactly as it was uploaded or imported — never transcoded. Requires a secret key or a session.

Responses

• 200 — Download link.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No video with that id or short_id (NOT_FOUND), or its original was deleted (ORIGINAL_NOT_AVAILABLE).
• 409 — The original is still uploading (VIDEO_NOT_READY).
• 422 — The video lives on your own server (NOT_SUPPORTED_FOR_BYO).

{
  "status": "",
  "data": {
    "url": "",
    "expires_at": "",
    "file_name": "",
    "size_bytes": ""
  }
}

GET /v1/videos/{video_id}/tracks#

List audio and subtitle tracks

Tracks that came with the original file (origin: source) plus the ones added through the API (origin: manual). supported is false when tracks cannot be added to this video, with the reason in unsupported_reason.

Responses

• 200 — Tracks.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No video with that id or short_id (NOT_FOUND).

{
  "status": "",
  "data": {
    "supported": true,
    "unsupported_reason": "",
    "tracks": [
      {
        "id": "",
        "kind": "",
        "origin": "",
        "lang": "",
        "label": "",
        "status": "",
        "error": "",
        "created_at": ""
      }
    ]
  }
}

POST /v1/videos/{video_id}/tracks/audio#

Add an audio track

Step 1 of 2. Creates the track (uploading) and returns a pre-signed PUT for the audio file (mp3, m4a, aac, wav, flac, ogg or opus; up to 1 GiB). Upload the file, then call POST /videos/{video_id}/tracks/{track_id}/complete.

Request body

• lang: string (required)
• label: string (required)
• file_name: string (required)
• size_bytes: object (required)
• content_type: string (required)

Responses

• 200 — Track and upload URL.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No video with that id or short_id (NOT_FOUND).
• 409 — The video does not accept tracks yet (TRACKS_NOT_SUPPORTED: not HLS, still processing, or on your own server), or the per-video limit was reached (TRACK_LIMIT_REACHED).
• 422 — Invalid lang/label, unsupported file type or size (UNSUPPORTED_AUDIO_FORMAT, AUDIO_TOO_LARGE).

{
  "status": "",
  "data": {
    "track": {
      "id": "",
      "kind": "",
      "origin": "",
      "lang": "",
      "label": "",
      "status": "",
      "error": "",
      "created_at": ""
    },
    "upload": {
      "url": "",
      "method": "",
      "headers": "",
      "expires_at": ""
    }
  }
}

POST /v1/videos/{video_id}/tracks/subtitles#

Add a subtitle track

Send the text of an .srt or .vtt file (max 2 MB) in content. SRT is converted to WebVTT. The track is ready immediately.

Request body

• lang: string (required)
• label: string (required)
• content: string (required)

Responses

• 200 — The new track.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No video with that id or short_id (NOT_FOUND).
• 409 — The video does not accept tracks yet (TRACKS_NOT_SUPPORTED: not HLS, still processing, or on your own server), or the per-video limit was reached (TRACK_LIMIT_REACHED).
• 413 — The subtitle file is larger than 2 MB (SUBTITLE_TOO_LARGE).
• 422 — Invalid lang, label or subtitle content (INVALID_LANG, INVALID_SUBTITLE).

{
  "status": "",
  "data": {
    "track": {
      "id": "",
      "kind": "",
      "origin": "",
      "lang": "",
      "label": "",
      "status": "",
      "error": "",
      "created_at": ""
    }
  }
}

DELETE /v1/videos/{video_id}/tracks/{track_id}#

Delete a track you added

Only origin: manual tracks can be deleted.

Responses

• 200 — Deleted.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No video or track with that id (NOT_FOUND).
• 409 — The video does not accept tracks yet (TRACKS_NOT_SUPPORTED: not HLS, still processing, or on your own server), or the per-video limit was reached (TRACK_LIMIT_REACHED).

{
  "status": "",
  "data": {
    "deleted": true
  }
}

POST /v1/videos/{video_id}/tracks/{track_id}/complete#

Complete an audio track upload

Step 2 of 2. Verifies the uploaded file and starts processing (processing → ready or failed). Safe to call twice.

Responses

• 200 — The track.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No video or track with that id (NOT_FOUND).
• 409 — The file is missing or its size does not match (UPLOAD_MISSING, UPLOAD_SIZE_MISMATCH), or the video does not accept tracks.
• 503 — No processing server is available right now (NO_ENGINE_AVAILABLE).

{
  "status": "",
  "data": {
    "track": {
      "id": "",
      "kind": "",
      "origin": "",
      "lang": "",
      "label": "",
      "status": "",
      "error": "",
      "created_at": ""
    }
  }
}

Uploads#

Open a direct upload session, PUT the parts to storage, then confirm.

POST /v1/videos/imports#

Import a video from a URL

XonaPlay downloads the file from source_url server-to-server (redirects allowed, public HTTPS only) and stores it untouched as the original — your server never handles the bytes. With delivery: "original" the video is ready as soon as the download finishes; with "hls" (default) rendering starts then. You get video.ready or video.failed.

Request body

• title: string (required)
• source_url: string (required)
• file_name: string
• delivery: object
• storage_profile_id: string
• compute_engine_id: string

Responses

• 200 — Import queued.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 402 — Plan limit reached (PLAN_LIMIT).
• 422 — Invalid or not allowed source_url (VALIDATION_FAILED).

{
  "status": "",
  "data": {
    "video_id": "",
    "import_id": "",
    "status": ""
  }
}

POST /v1/videos/uploads#

Create an upload session

Starts a multipart direct upload straight to storage: creates the video (status uploading) and returns one pre-signed PUT URL per part.

Request body

• title: string (required)
• file_name: string (required)
• size_bytes: number (required)
• content_type: string
• storage_profile_id: string
• compute_engine_id: string
• delivery: object

Responses

• 200 — Upload session created.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 422 — Validation failed (e.g. missing size_bytes).

{
  "status": "",
  "data": {
    "video_id": "",
    "session_id": "",
    "part_size": "",
    "urls": [
      ""
    ],
    "max_height": ""
  }
}

DELETE /v1/videos/uploads/{session_id}#

Abort an upload session

Cancels the multipart upload and deletes the pending video.

Responses

• 200 — Aborted.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No upload session with that id (NOT_FOUND).

{
  "status": "",
  "data": {
    "aborted": true
  }
}

POST /v1/videos/uploads/{session_id}/complete#

Complete an upload session

Closes the multipart upload (completes it in storage), verifies the total size against what was declared and the plan limits, and queues the video for processing.

Request body

• parts: array
  • part_number: number (required)
  • etag: string (required)

Responses

• 200 — The upload was completed and the video queued.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No upload session with that id (NOT_FOUND).
• 409 — The session is already closed, or the uploaded size exceeds what was declared or the plan storage limit.

{
  "status": "",
  "data": {
    "video_id": "",
    "status": ""
  }
}

Live#

List live streams and get a signed playback link for one that is on air.

GET /v1/live#

List live streams

Live streams of the authenticated workspace, merged from every engine (platform custody and BYO), newest first. Paginated.

Responses

• 200 — Paginated list of live streams.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).

{
  "status": "",
  "data": [
    {
      "id": "",
      "short_id": "",
      "name": "",
      "slug": "",
      "status": "",
      "visibility": "",
      "playback_security": "",
      "stream_key": "",
      "ingest": {
        "primary": "",
        "backup": ""
      },
      "dvr_enabled": true,
      "dvr_window_minutes": "",
      "replay_enabled": true,
      "replay_unlisted": true,
      "viewers": "",
      "total_views": "",
      "custody": "",
      "engine": "",
      "storage_profile": "",
      "links": {
        "player": "",
        "hls": "",
        "poster": ""
      },
      "last_live_at": "",
      "created_at": "",
      "updated_at": ""
    }
  ],
  "meta": {
    "total": "",
    "page": "",
    "per_page": "",
    "last_page": ""
  }
}

GET /v1/live/{stream_id}#

Get a live stream

Accepts either the id (UUID) or the short_id.

Responses

• 200 — The live stream.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No live stream with that id or short_id (NOT_FOUND).

{
  "status": "",
  "data": {
    "id": "",
    "short_id": "",
    "name": "",
    "slug": "",
    "status": "",
    "visibility": "",
    "playback_security": "",
    "stream_key": "",
    "ingest": {
      "primary": "",
      "backup": ""
    },
    "dvr_enabled": true,
    "dvr_window_minutes": "",
    "replay_enabled": true,
    "replay_unlisted": true,
    "viewers": "",
    "total_views": "",
    "custody": "",
    "engine": "",
    "storage_profile": "",
    "links": {
      "player": "",
      "hls": "",
      "poster": ""
    },
    "last_live_at": "",
    "created_at": "",
    "updated_at": ""
  }
}

Playback#

Signed HLS/embed links for a video or live stream — the only way to play content.

GET /v1/live/{stream_id}/playback#

Get signed playback links for a live stream

The ONLY way to play a live stream: returns a signed hls_url/embed_url pair whose shape depends on the workspace playback security level. No credential required for public open/protected content; otherwise a secret key or session is required. On a fatal player error, call this again (see the "Reload" rule in the guide) instead of reusing the old URL.

Responses

• 200 — Signed playback links.
• 401 — A secret key or session is required for this content (KEY_REQUIRED).
• 403 — Domain not allowed (DOMAIN_NOT_ALLOWED), workspace unavailable (WORKSPACE_UNAVAILABLE), or viewer banned (ACCESS_DENIED).
• 404 — No live stream with that id or short_id (NOT_FOUND).
• 409 — The stream is not live right now (LIVE_NOT_ACTIVE); retry later.
• 429 — Too many requests; retry after Retry-After (RATE_LIMITED).

{
  "status": "",
  "data": {
    "stream_id": "",
    "short_id": "",
    "hls_url": "",
    "poster_url": "",
    "embed_url": "",
    "expires_at": "",
    "security": "",
    "status": ""
  }
}

GET /v1/videos/{video_id}/playback#

Get signed playback links for a video

The ONLY way to play a video: returns a signed hls_url/embed_url pair whose shape depends on the workspace/video playback security level (open/protected/strict/maximum). No credential required for public open/protected content; otherwise a secret key or session is required. On a fatal player error, call this again (see the "Reload" rule in the guide) instead of reusing the old URL.

Responses

• 200 — Signed playback links.
• 401 — A secret key or session is required for this content (KEY_REQUIRED).
• 403 — Domain not allowed (DOMAIN_NOT_ALLOWED), workspace unavailable (WORKSPACE_UNAVAILABLE), or viewer banned (ACCESS_DENIED).
• 404 — No video with that id or short_id (NOT_FOUND).
• 409 — The video is still processing (VIDEO_NOT_READY); retry later.
• 429 — Too many requests; retry after Retry-After (RATE_LIMITED).

{
  "status": "",
  "data": {
    "video_id": "",
    "short_id": "",
    "hls_url": "",
    "original_url": "",
    "poster_url": "",
    "thumbnails_url": "",
    "embed_url": "",
    "expires_at": "",
    "security": "",
    "delivery": "",
    "duration_sec": ""
  }
}

Webhooks#

Register endpoints for video and live events, and inspect deliveries.

GET /v1/webhooks#

List webhook endpoints

Webhook endpoints registered for the workspace (secrets never come back in full).

Responses

• 200 — Webhook endpoints.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).

{
  "status": "",
  "data": [
    {
      "id": "",
      "url": "",
      "description": "",
      "secret_last4": "",
      "events": [
        ""
      ],
      "enabled": true,
      "disabled_by_staff": true,
      "last_success_at": "",
      "last_failure_at": "",
      "created_at": "",
      "updated_at": ""
    }
  ]
}

POST /v1/webhooks#

Create a webhook endpoint

Registers a new endpoint. The signing secret (whsec_…) is returned ONCE, in this response — store it, it cannot be retrieved again.

Request body

• url: string (required)
• description: string
• events: array (required)

Responses

• 200 — Endpoint created, with its signing secret.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 409 — Workspace already has the maximum number of endpoints (ENDPOINT_LIMIT_REACHED).
• 422 — Validation failed (bad url or events).

{
  "status": "",
  "data": {
    "endpoint": {
      "id": "",
      "url": "",
      "description": "",
      "secret_last4": "",
      "events": [
        ""
      ],
      "enabled": true,
      "disabled_by_staff": true,
      "last_success_at": "",
      "last_failure_at": "",
      "created_at": "",
      "updated_at": ""
    },
    "secret": ""
  }
}

PATCH /v1/webhooks/{id}#

Update a webhook endpoint

Partial update. An endpoint disabled by staff cannot be re-enabled by the workspace.

Request body

• url: string
• description: string
• events: array
• enabled: boolean

Responses

• 200 — The updated endpoint.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 403 — This endpoint was disabled by staff and cannot be re-enabled (DISABLED_BY_STAFF).
• 404 — No webhook endpoint with that id (NOT_FOUND).
• 422 — Validation failed (bad url or events).

{
  "status": "",
  "data": {
    "id": "",
    "url": "",
    "description": "",
    "secret_last4": "",
    "events": [
      ""
    ],
    "enabled": true,
    "disabled_by_staff": true,
    "last_success_at": "",
    "last_failure_at": "",
    "created_at": "",
    "updated_at": ""
  }
}

DELETE /v1/webhooks/{id}#

Delete a webhook endpoint

Responses

• 200 — Deleted.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No webhook endpoint with that id (NOT_FOUND).

{
  "status": "",
  "data": {
    "deleted": true
  }
}

GET /v1/webhooks/{id}/deliveries#

List delivery attempts

Delivery history for one endpoint, newest first. Paginated.

Responses

• 200 — Paginated deliveries.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No webhook endpoint with that id (NOT_FOUND).

{
  "status": "",
  "data": [
    {
      "id": "",
      "event": "",
      "status": "",
      "attempts": "",
      "last_status_code": "",
      "last_error": "",
      "created_at": "",
      "delivered_at": ""
    }
  ],
  "meta": {
    "total": "",
    "page": "",
    "per_page": "",
    "last_page": ""
  }
}

POST /v1/webhooks/{id}/test#

Send a test event

Delivers a webhook.test event to the endpoint right away, so you can check your receiver.

Responses

• 200 — The test delivery.
• 401 — Missing or invalid credential (KEY_REQUIRED, INVALID_KEY).
• 404 — No webhook endpoint with that id (NOT_FOUND).

{
  "status": "",
  "data": {
    "id": "",
    "event": "",
    "status": "",
    "attempts": "",
    "last_status_code": "",
    "last_error": "",
    "created_at": "",
    "delivered_at": ""
  }
}