REST API

Broadcasts API

GET /api/v1/broadcasts (Broadcast List)
POST /api/v1/broadcasts (Create Broadcast)
GET /api/v1/broadcasts/{id} (Query Broadcast Status)
PATCH /api/v1/broadcasts/{id} (Update Broadcast Settings)
DELETE /api/v1/broadcasts/{id} (Revoke Broadcast)
DELETE /api/v1/broadcasts/batch (Batch Revoke Broadcasts)

GET /api/v1/broadcasts (Broadcast List)

Description

Query the broadcast list owned by the current API Key holder (excluding revoked channels), with pagination support.

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Parameter	Type	Required	Description
`per_page`	integer	No	Items per page (default 20)
`page`	integer	No	Page number (default 1)

Request Example

curl -X GET "https://vas-poc.vurbo.ai/api/v1/broadcasts?per_page=10&page=1" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

Success Response (HTTP 200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "token": "a3f9",
      "name": "My Broadcast Channel",
      "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
      "transcription_language": "zh-TW",
      "transcription_languages": ["zh-TW", "en-US"],
      "translation_languages": ["en-US", "ja-JP"],
      "tts_config": null,
      "speaker_diarization": false,
      "summary_template": null,
      "summary_language": null,
      "max_viewers": 100,
      "access_type": "public",
      "pass_code": null,
      "status": "pending",
      "is_live": false,
      "session_id": null,
      "current_recording_id": null,
      "recordings_count": 0,
      "peak_viewers": 0,
      "total_viewers": 0,
      "duration_ms": 0,
      "duration_formatted": "0:00",
      "started_at": null,
      "ended_at": null,
      "revoked_at": null,
      "created_at": "2026-01-03T10:00:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 10,
    "total": 50
  }
}

For response field descriptions, see the response field table under Create Broadcast.

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`auth_missing_api_key`	401	API Key not provided	Make sure the header includes the API Key
`auth_invalid_api_key`	401	Invalid API Key	Verify the API Key is correct

POST /api/v1/broadcasts (Create Broadcast)

Create a new broadcast session for real-time subtitle streaming. After creation, a share link is generated (with a 4-character short-code token from the character set a-z0-9). Viewers can use this link to receive real-time subtitles and translations.

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Parameter	Type	Required	Description
`transcription_languages`	string[]	Yes (or use the deprecated `transcription_language`)	Array of transcription language codes (max 10, distinct; e.g. `["zh-TW", "en-US"]`). Only a single language is supported when `speaker_diarization` is enabled
`transcription_language`	string	No	(Deprecated, backward compatible) Equivalent to the first element of `transcription_languages`
`translation_languages`	string[]	No	Array of translation language codes (max 12, distinct; e.g. `["en-US", "ja-JP"]`)
`name`	string	No	Channel name (max 100 characters; cannot be changed after creation and is not used as the recording name)
`access_type`	string	No	Access type: `public` (default) or `password`
`pass_code`	string	Conditional	Password (required when `access_type` is `password`, 4-12 characters; letters, digits and common punctuation only (no Chinese characters, no spaces))
`max_viewers`	integer	No	Maximum number of viewers (1 to the account viewer limit; defaults to that limit when omitted)
`speaker_diarization`	boolean	No	Speaker diarization (default `false`; when enabled, only a single transcription language is supported — providing multiple returns 422)
`tts_config`	object	No	TTS default settings (key is the language code)
`tts_config.*.voice`	string	No	TTS voice name (uses the default voice if not specified)
`summary_template`	string	No	Summary template slug (max 50 characters; must be an enabled `summary` category template, which can be queried via the Summary Templates API)
`summary_language`	string	No	Summary output language; must be a language code from the supported language list (defaults to the first transcription language — the first element of `transcription_languages` — if not specified)
`callback_url`	string	No	Webhook callback URL (notifies when broadcast recording processing completes/fails, max 2048 characters)

Webhook Notification: After setting callback_url, you receive a recording.completed event when broadcast recording processing completes, and a recording.failed event when it fails. See the Webhook Guide.

Request Example

curl -X POST "https://vas-poc.vurbo.ai/api/v1/broadcasts" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP"],
    "name": "My Broadcast Channel",
    "access_type": "public",
    "max_viewers": 50,
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "callback_url": "https://your-server.com/webhooks/vas"
  }'

Success Response (HTTP 201)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "a3f9",
    "name": "My Broadcast Channel",
    "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
    "transcription_language": "zh-TW",
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "speaker_diarization": false,
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "max_viewers": 50,
    "access_type": "public",
    "pass_code": null,
    "status": "pending",
    "is_live": false,
    "session_id": null,
    "current_recording_id": null,
    "recordings_count": 0,
    "peak_viewers": 0,
    "total_viewers": 0,
    "duration_ms": 0,
    "duration_formatted": "0:00",
    "started_at": null,
    "ended_at": null,
    "revoked_at": null,
    "created_at": "2026-01-03T10:00:00.000Z"
  }
}

Response Field Descriptions

Field	Type	Description
`id`	string	Broadcast ID (UUID)
`token`	string	Share token (4-character short code, character set a-z0-9)
`name`	string	Broadcast name
`share_url`	string	Default share URL (not an openable viewer page; see the Broadcast Guide)
`transcription_language`	string	Transcription language (backward compatible, equals the first element of `transcription_languages`)
`transcription_languages`	string[]	List of transcription languages
`translation_languages`	array	List of translation languages
`tts_config`	object	TTS default settings (key is the language code)
`speaker_diarization`	boolean	Speaker diarization toggle
`summary_template`	string	Summary template slug (`null` means not set)
`summary_language`	string	Summary output language (defaults to the first transcription language when `null`)
`max_viewers`	integer	Maximum number of viewers
`access_type`	string	Access type: `public` or `password`
`pass_code`	string	Plaintext password (has a value when `access_type` is `password`, otherwise `null`)
`status`	string	Status (see description below)
`is_live`	boolean	Whether currently live (`true` when in `active` or `paused` status)
`session_id`	string	WebSocket Session ID
`current_recording_id`	string	Current recording UUID: has a value only while live, and is the recording of this go-live (the new recording after a takeover); `null` during standby or when not live
`recordings_count`	integer	Number of historical recordings
`peak_viewers`	integer	Highest historical viewer count
`total_viewers`	integer	Cumulative viewer count
`duration_ms`	integer	Broadcast duration (milliseconds)
`duration_formatted`	string	Formatted duration (min:sec)
`started_at`	string	Start time (ISO 8601)
`ended_at`	string	End time (ISO 8601)
`revoked_at`	string	Revocation time (ISO 8601)
`created_at`	string	Creation time (ISO 8601)

Broadcast Status Descriptions

Status	Description
`pending`	Created, not yet started
`active`	In progress
`paused`	Paused
`ended`	Ended
`revoked`	Revoked

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`validation_failed`	422	Parameter validation failed	Verify the parameter format is correct
`plan_feature_not_allowed`	403	Broadcasting is not included in unlimited plans (always excluded, v1.9.0)	Broadcasting is billed by credits; use a credit-based API Key instead

Error codes for language-related violations: exceeding 12 translation languages, exceeding 10 transcription languages, duplicate languages, an empty required array, or "speaker diarization + multiple transcription languages" all return validation_failed (HTTP 422) on REST create/update. The same violations return too_many_languages or diarization_multilang_conflict (HTTP 400, see error-codes.md) on the WebSocket start path. The two paths validate at different layers, which is why the error codes differ.

GET /api/v1/broadcasts/{id} (Query Broadcast Status)

Description

Query the detailed information and current status of a specified broadcast.

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Broadcast ID (UUID, path parameter)

Request Example

curl -X GET "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

Success Response (HTTP 200)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "a3f9",
    "name": "My Broadcast Channel",
    "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
    "transcription_language": "zh-TW",
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "speaker_diarization": true,
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "max_viewers": 100,
    "access_type": "public",
    "pass_code": null,
    "status": "active",
    "is_live": true,
    "session_id": "ws_session_xyz",
    "current_recording_id": "660e8400-e29b-41d4-a716-446655440001",
    "recordings_count": 1,
    "peak_viewers": 25,
    "total_viewers": 30,
    "duration_ms": 1800000,
    "duration_formatted": "30:00",
    "started_at": "2026-01-03T10:00:00.000Z",
    "ended_at": null,
    "revoked_at": null,
    "created_at": "2026-01-03T09:55:00.000Z"
  }
}

For response field descriptions, see the response field table under Create Broadcast.

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`broadcast_session_not_found`	404	Specified broadcast not found	Verify the broadcast ID is correct

PATCH /api/v1/broadcasts/{id} (Update Broadcast Settings)

Description

Update a broadcast channel's default settings. This API can be called while the broadcast is in progress (active or paused status), and the settings are saved immediately.

Note: Broadcast settings have two layers — pick the interface that matches your intent
A broadcast is a "channel": one channel can go live many times (it returns to pending when it ends and can be started again). Settings therefore split into two layers:
Layer What it changes Interface
Channel defaults The starting configuration for every future broadcast This API (PATCH)
The in-progress session What that session actually uses Host-side WebSocket actions
This API updates the channel defaults, so transcription_languages, translation_languages, speaker_diarization, tts_config, summary_template, and summary_language take effect on the next broadcast; the in-progress broadcast keeps its current transcription, translation, speech synthesis, and end-of-session summary configuration. This lets a host adjust settings for the next broadcast while the current one is still live.
Exception: access_type, pass_code, and max_viewers are viewer access controls and are applied immediately to the in-progress broadcast as well.
To change the summary settings for the current session and have that session's summary use them, use the host-side WebSocket action set_summary instead.

Layer	What it changes	Interface
Channel defaults	The starting configuration for every future broadcast	This API (`PATCH`)
The in-progress session	What that session actually uses	Host-side WebSocket actions

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Broadcast ID (UUID, path parameter)
`transcription_languages`	string[]	No	Next broadcast only. Array of transcription language codes (max 10, distinct)
`transcription_language`	string	No	Next broadcast only. (Deprecated, backward compatible) Equivalent to the first element of `transcription_languages`
`translation_languages`	string[]	No	Next broadcast only. Array of translation language codes (max 12, distinct; e.g. `["en-US", "ja-JP"]`)
`max_viewers`	integer	No	Maximum number of viewers (1 to the account viewer limit)
`access_type`	string	No	Access type: `public` or `password`
`pass_code`	string	Conditional	Password (4-12 characters; letters, digits and common punctuation only (no Chinese characters, no spaces), required when `access_type` is `password`)
`tts_config`	object	No	Next broadcast only. TTS default settings (overwrites existing settings, `null` means clear)
`speaker_diarization`	boolean	No	Next broadcast only. Speaker diarization toggle (when enabled, only a single transcription language is supported — providing multiple returns 422)
`summary_template`	string	No	Next broadcast only. Summary template slug (max 50 characters, empty string `""` means clear). To change the summary during a live broadcast, use the WebSocket `set_summary` action
`summary_language`	string	No	Next broadcast only. Summary output language; must be a language code from the supported language list (empty string `""` means clear)

Note: If no updatable field is provided, the request returns 200 and nothing changes. The channel name cannot be changed after creation; a name field is ignored. Passing an empty string "" for summary_template and summary_language clears the setting; passing null for tts_config clears the setting; omitting a field leaves it unchanged.

Request Example

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "translation_languages": ["en-US", "ja-JP", "ko-KR"],
    "max_viewers": 200
  }'

Success Response (HTTP 200)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "a3f9",
    "name": "Tech Talk Live",
    "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
    "transcription_language": "zh-TW",
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP", "ko-KR"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "speaker_diarization": true,
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "max_viewers": 200,
    "access_type": "public",
    "pass_code": null,
    "status": "active",
    "is_live": true,
    "session_id": "ws_session_xyz",
    "current_recording_id": "660e8400-e29b-41d4-a716-446655440001",
    "recordings_count": 1,
    "peak_viewers": 25,
    "total_viewers": 30,
    "duration_ms": 1800000,
    "duration_formatted": "30:00",
    "started_at": "2026-01-03T10:00:00.000Z",
    "ended_at": null,
    "revoked_at": null,
    "created_at": "2026-01-03T09:55:00.000Z"
  }
}

For response field descriptions, see the response field table under Create Broadcast.

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`broadcast_session_not_found`	404	Specified broadcast not found	Verify the broadcast ID is correct
`validation_failed`	422	Parameter validation failed	Verify the parameter format is correct

Parameter	Type	Required	Description
`id`	string	Yes	Broadcast ID (UUID, path parameter)

Request Example

curl -X DELETE "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

Success Response (HTTP 200)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "a3f9",
    "name": "My Broadcast Channel",
    "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
    "transcription_language": "zh-TW",
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP"],
    "tts_config": null,
    "speaker_diarization": false,
    "summary_template": null,
    "summary_language": null,
    "max_viewers": 100,
    "access_type": "public",
    "pass_code": null,
    "status": "revoked",
    "is_live": false,
    "session_id": null,
    "current_recording_id": null,
    "recordings_count": 0,
    "peak_viewers": 0,
    "total_viewers": 0,
    "duration_ms": 0,
    "duration_formatted": "0:00",
    "started_at": null,
    "ended_at": null,
    "revoked_at": "2026-01-03T10:05:00.000Z",
    "created_at": "2026-01-03T10:00:00.000Z"
  }
}

For response field descriptions, see the response field table under Create Broadcast.

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`broadcast_session_not_found`	404	Specified broadcast not found	Verify the broadcast ID is correct
`broadcast_cannot_revoke`	422	Only pending status can be revoked	Check the current broadcast status

Parameter	Location	Type	Required	Description
`ids`	body	array	Yes	Array of broadcast IDs (each element is a UUID, max 100 entries)

Request Example

curl -X DELETE "https://vas-poc.vurbo.ai/api/v1/broadcasts/batch" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    ]
  }'

Success Response

HTTP 200

{
  "data": {
    "affected_count": 2
  }
}

Response Field Descriptions

Field	Type	Description
`data.affected_count`	number	Number of broadcasts actually revoked (counts only pending status)

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`validation_failed`	422	Parameter validation failed	Verify `ids` is a UUID array with no more than 100 entries

Version: V1.24.1 Last Updated: 2026-10-07

Auth Ticket API

Recording Entry API