REST API

Broadcasts

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",
      "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": "00: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_language`	string	Yes	Transcription language code (e.g. `zh-TW`)
`translation_languages`	string	No	Array of translation language codes
`name`	string	No	Channel name (max 100 characters)
`access_type`	string	No	Access type: `public` (default) or `password`
`pass_code`	string	Conditional	Password (required when `access_type` is `password`, 4-12 characters)
`max_viewers`	integer	No	Maximum number of viewers (defaults to the plan limit)
`speaker_diarization`	boolean	No	Speaker diarization (default `false`)
`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)
`tts_config.*.speaking_rate`	number	No	TTS speaking rate (0.5 ~ 2.0, default 1.0)
`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 (defaults to `transcription_language` 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_language": "zh-TW",
    "translation_languages": ["en-US", "ja-JP"],
    "name": "My Broadcast Channel",
    "access_type": "public",
    "max_viewers": 50,
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "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",
    "translation_languages": ["en-US", "ja-JP"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "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	Share link
`transcription_language`	string	Transcription language
`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 `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 (only has a value while 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

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",
    "translation_languages": ["en-US", "ja-JP"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "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

Dynamically update the broadcast settings. This API can be called while the broadcast is in progress (active or paused status) to adjust settings in real time.

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Broadcast ID (UUID, path parameter)
`transcription_language`	string	No	Transcription language code (e.g. `zh-TW`)
`translation_languages`	string	No	Array of translation language codes
`max_viewers`	integer	No	Maximum number of viewers (1 ~ system limit)
`access_type`	string	No	Access type: `public` or `password`
`pass_code`	string	Conditional	Password (4-12 characters, required when `access_type` is `password`)
`tts_config`	object	No	TTS default settings (overwrites existing settings, `null` means clear)
`speaker_diarization`	boolean	No	Speaker diarization toggle
`summary_template`	string	No	Summary template slug (max 50 characters, empty string `""` means clear)
`summary_language`	string	No	Summary output language (empty string `""` means clear)

Note: At least one updatable field must be provided. 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",
    "translation_languages": ["en-US", "ja-JP", "ko-KR"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "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
`broadcast_cannot_update`	422	Only pending/active/paused can be updated	Check the current broadcast status
`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",
    "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.5.7 Last Updated: 2026-05-20

Auth Ticket

Entries