Referência#

URL base: https://api.xonaplay.com. A lista de endpoints abaixo é gerada a partir do nosso arquivo OpenAPI, /openapi.json.

Autenticação#

Uma key atua sobre todo o seu workspace. Crie, liste e revogue keys no dashboard, em Configurações → API. Uma key revogada responde 401 INVALID_KEY.

Convenções#

• JSON de entrada e saída, sempre em snake_case.
• Sucesso: { "status": "ok", "data": … }. Listas somam "meta": { "total": 120, "page": 1, "per_page": 20, "last_page": 6 }.
• Erro: { "status": "error", "code": "NOT_FOUND", "message": "…" }. Os códigos vêm em maiúsculas e são estáveis; as mensagens são para humanos e podem mudar.
• Erros de validação são 422 com errors: [{ "field": "title", "message": "…" }].
• Ids: todo {id} aceita o id UUID ou o short_id.
• Timestamps: ISO 8601 em UTC.
• Paginação: ?page=1&per_page=20 (máximo 100).

Objetos de vídeo e de transmissão ao vivo#

GET /v1/videos/{id} e GET /v1/live/{id} retornam o mesmo objeto que o nosso próprio dashboard usa — nada é removido na API pública.

• links.player é a página pública de reprodução (a que você embute num iframe). Não é um arquivo de vídeo.
• links.hls só funciona no Open; em qualquer outro nível ele está protegido e responde 403 TOKEN_REQUIRED sem token. Para reproduzir no seu próprio player, chame sempre /playback.
• custody, engine, compute_engine e storage_profile descrevem onde a XonaPlay guarda e renderiza o vídeo (armazenamento próprio ou seu, qual engine processou). Podem ser ignorados na maioria das integrações.
• playback_security é o override por vídeo do padrão do workspace: inherit, open, protected, strict ou maximum.
• delivery é hls (padrão) ou original: se a XonaPlay renderiza HLS a partir do original intacto. Veja Original ou HLS.

Limites de uso#

Acima do limite você recebe 429 RATE_LIMITED com um header Retry-After (em segundos) dizendo quanto esperar antes do próximo pedido. O bucket de 600/min só vale para uma secret key válida; uma inválida ou revogada cai no limite mais baixo de IP anônimo.

Webhooks#

Registre um endpoint HTTPS em Configurações → API → Webhooks (ou com POST /v1/webhooks). Nós fazemos POST de:

{
  "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 e live.ended viajam sob outra chave: data.live (um objeto de transmissão ao vivo — id, short_id, name, status, …), não 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"
    }
  }
}

• Assinado com X-Xona-Signature: t=<epoch em segundos>,v1=<hex>, onde v1 é o HMAC-SHA256 de "<t>.<body bruto>" com o secret do seu endpoint (whsec_…, mostrado uma única vez). Veja a receita de verificação.
• Responda qualquer 2xx dentro de 10 segundos. Qualquer outra coisa é reenviada depois de 1 min, 5 min, 30 min, 2 h e 6 h; depois disso o envio fica marcado como falho.
• Os envios podem chegar mais de uma vez ou fora de ordem: use id para deduplicar, e leia o vídeo de novo se a ordem importar.

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