API docs by Redocly

Webble Cast API (2025.04.01)

Download OpenAPI specification:Download

Last modified: 2025-11-07

This API provides functionality for managing streams, events and destinations.

Authentication

OAuth2.0 endpoints for authenticating users.

Fetch a new token to authenticate requests to the API

Fetch a new token to authenticate requests to the API

Request Body schema: application/json
required

Details required to fetch a new token

grant_type
required
string

The grant type to use authentication for. In our API Client Credentials is the only supported grant type.

client_id
required
string

The client ID to authenticate the request

client_secret
required
string

The client secret to authenticate the request

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials",
  • "client_id": "1",
  • "client_secret": "secret"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "token_type": "Bearer",
  • "expires_in": "900'"
}

Stream

Stream API Overview

The Stream API provides endpoints to manage live streaming sessions, from their creation to their archival as video-on-demand (VOD). These endpoints allow users to create, update, and manage stream states dynamically while enforcing rules for state transitions.

Key API Functionalities:

  • Creating and configuring a new stream.
  • Updating stream settings.
  • Retrieving stream details and statuses.

Stream States

A stream has different lifecycle stages. Each state determines the actions that can be performed on the stream, as well as the availability of its playback URLs.

  • Draft:
    The stream is in its initial setup phase and can be freely modified.
    URL behavior: No playback URL is generated in this state.

  • Locked:
    The stream’s configuration is locked, preventing further modifications. Streaming resources will be reserved.
    URL behavior: Still no playback URL is generated, as the stream has not yet begun previewing or broadcasting.

  • Preview:
    The stream is in a preview mode, allowing content creators to test before going live. It is not visible to the public.
    URL behavior: Internal preview URLs may be generated for testing but are not publicly distributed.

  • Live:
    The stream is actively broadcasting to viewers. Transitions to this state indicate that the stream is fully active.
    URL behavior:

    • url: Points to the live stream on the primary CDN.
    • url_cn: Points to the live stream on the China CDN (if applicable).

  • Ended:
    The stream has finished broadcasting. No further live interactions are possible, but it may transition to VOD. The recording is not yet visible.
    URL behavior: No playback URL is exposed in this state.

  • Replay:
    The stream has finished broadcasting. A recording of the session is available for instant replay, but this is not the finalized VOD asset.
    URL behavior:

    • url: Points to the instant replay recording hosted by the system.
    • url_cn: Remains empty.

  • Vod:
    The stream recording is now available as a video-on-demand (VOD) asset for playback. This includes finalized media files and subtitles.
    URL behavior:

    • url: Points to the final VOD manifest or file (with subtitles if available).
    • url_cn: Points to the China CDN copy of the VOD (if applicable).

  • Pending:
    This state indicates an operation is being performed on the stream and cannot be changed. Typically awaiting an external trigger.
    URL behavior: No playback URL is generated in this state.

Create or update a stream

Creates a new stream or updates an existing one based on the provided identifiers.

Operation Logic:

  • If id is provided and exists, the stream with that ID will be updated
  • If id is provided but not found, it will be discarded and the system will check externalId
  • If externalId exists, the stream with that external ID will be updated
  • If neither identifier matches an existing stream, a new stream will be created

Event Association:

You can associate the stream with an event in two ways:

  1. Link to existing event:

    • Provide eventId (internal ID) or externalEvent (external ID)
    • The system will verify the event exists and link it to the stream
    • Returns an error if the specified event is not found

  2. Create new event:

    • Provide an event object containing:
      • name: Event name (required)
      • startDateTimeUTC: Event start date/time in UTC (required)
      • endDateTimeUTC: Event end date/time in UTC (required)
      • externalId: External identifier for the event (optional)
      • languages: Array of language codes (optional)
    • The system will create/update the event and automatically link it to the stream

Language Handling:

Events contain a languages array with language codes that serve as defaults:

  • When an existing event is updated, its default languages will NOT be propagated to attached streams.
  • When a stream is created or updated with an empty languages array, it will inherit the default languages from its associated event
  • If a stream provides its own languages array, those values take precedence over the event's defaults
Request Body schema: application/json
required

Details required to create a stream

externalEvent
string

A way to group multiple streams per event. The externalEvent must correspond to an external_id on an event in our system.

object
externalId
string

An id to identify the resource in your system This ID can be used to refer back to the created resources

externalProvider
string
Default: ""

A string to identify which external service created the resource. Can be used for filtering.

externalVersion
string
Default: ""

A way o identify the version of the resource on the external system. Can ben changed each update to have data integrity between systems

streamName
required
string

The name of the session in the salesForce system.

startDateTimeUTC
required
string

The start date and time of the stream in UTC format

endDateTimeUTC
required
string

The end date and time of the stream in UTC format

releaseDateTimeUTC
string

used by external systems. Way to refer to the embargo of a stream

featured
boolean

Used by external systems. This indicates if a stream is featured for third parties

priority
integer
Default: 0

Used by external systems. This indicates a priority given to the stream. Used by third parties

required
Array of objects

A list of required languages (language codes) for the stream. The order determines how the audio channels are interpreted.

Array of objects

A list of required subtitles (language codes) for the stream,

Responses

Request samples

Content type
application/json
{
  • "externalEvent": "a0WTG000000SvOL2A0",
  • "event": {
    },
  • "externalId": "a0WTG000000SvOL2A0",
  • "externalProvider": "Salesforce - WEF",
  • "externalVersion": "1.1",
  • "streamName": "Social Innovation in Action",
  • "startDateTimeUTC": "2025-01-22T10:30:00.000+0000",
  • "endDateTimeUTC": "2025-01-22T11:15:00.000+0000",
  • "releaseDateTimeUTC": "2025-01-22T11:15:00.000+0000",
  • "featured": false,
  • "priority": 0,
  • "languages": [
    ],
  • "subtitles": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Stream created successfully",
  • "data": {}
}

Filter all available streams

Get the streams based on the provided query parameters.

query Parameters
external_event
any

Filter streams by external event_id

status
string
Example: status=Live

Filter streams by status (e.g., Draft, Live)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Get stream details

Retrieves details of a stream using either its internal ID or external ID.

path Parameters
type
required
string
Enum: "internal" "external"
Example: internal

Specifies whether the identifier is an internal (UUID) or external (externalId)

identifier
required
string
Example: 616ad7ec-651f-42b2-be52-618a6b06b09b

The identifier of the stream, either a UUID (internal) or an external ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update an existing stream

Updates a stream based on either the internal ID or an external ID. Updates are only allowed when the stream is in DRAFT status. Two hours beforte startDateTimeUTC the stream will automatically move to the Pending state. From then on out updates will no longer be accepted

path Parameters
type
required
string
Enum: "internal" "external"
Example: internal

Specifies whether the identifier is an internal (UUID) or external (externalId)

identifier
required
string
Example: 616ad7ec-651f-42b2-be52-618a6b06b09b

The identifier of the stream, either a UUID (internal) or an external ID

Request Body schema: application/json
required

Stream details to update. Only updatable fields should be sent.

streamId
string

The unique identifier of the stream

streamName
string

The name of the stream

startDateTimeUTC
string

The start date/time of the stream in UTC format

endDateTimeUTC
string

The end date/time of the stream in UTC format

Array of objects

A list of languages required for the stream

Responses

Request samples

Content type
application/json
{
  • "streamId": "12345",
  • "streamName": "Sample Stream",
  • "startDateTimeUTC": "2025-01-22T11:00:00.000+0000",
  • "endDateTimeUTC": "2025-01-22T12:00:00.000+0000",
  • "languages": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Stream updated successfully"
}

Delete an existing stream

Deletes a stream based on either the internal ID or an external ID. Only streams in DRAFT status can be deleted.

path Parameters
type
required
string
Enum: "internal" "external"
Example: internal

Specifies whether the identifier is an internal (UUID) or external (externalId)

identifier
required
string
Example: 616ad7ec-651f-42b2-be52-618a6b06b09b

The identifier of the stream, either a UUID (internal) or an external ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Stream deleted successfully"
}

Destination

Endpoints for managing extra streaming destinations. (RTMP)

Add a destination to a stream

Creates a new destination (RTMP output) for the given stream.

path Parameters
type
required
string
Enum: "internal" "external"
Example: internal

Specifies whether the identifier is an internal (UUID) or external (externalId)

id
required
string
Example: 616ad7ec-651f-42b2-be52-618a6b06b09b

The identifier of the stream, either a UUID (internal) or an external ID

streamId
required
string <uuid>
Example: 616ad7ec-651f-42b2-be52-618a6b06b09b

The unique identifier of the stream this destination belongs to

Request Body schema: application/json
required
rtmpUrl
required
string <uri>

The RTMP URL for streaming

streamKey
required
string

The stream key for authentication

language
required
string

The language key for this destination

Responses

Request samples

Content type
application/json
{
  • "rtmpUrl": "rtmp://live.example.com/app",
  • "streamKey": "abc123",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "id": "e72a7ec1-54b4-4f13-9c9d-8e8b06b56d3f",
  • "rtmpUrl": "rtmp://live.example.com/app",
  • "streamKey": "abc123",
  • "language": "en"
}

Get Destination Info

Return a destination .

path Parameters
type
required
string
Enum: "internal" "external"
Example: internal

Specifies whether the identifier is an internal (UUID) or external (externalId)

id
required
string
Example: 616ad7ec-651f-42b2-be52-618a6b06b09b

The identifier of the stream, either a UUID (internal) or an external ID

Responses

Response samples

Content type
application/json
{
  • "id": "e72a7ec1-54b4-4f13-9c9d-8e8b06b56d3f",
  • "rtmpUrl": "rtmp://live.example.com/app",
  • "streamKey": "abc123",
  • "language": "en"
}

Get Destination Info

Return a destination .

path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "e72a7ec1-54b4-4f13-9c9d-8e8b06b56d3f",
  • "rtmpUrl": "rtmp://live.example.com/app",
  • "streamKey": "abc123",
  • "language": "en"
}

Update a destination

Updates details for an existing destination.

path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
rtmpUrl
string
streamKey
string
language
string

Responses

Request samples

Content type
application/json
{
  • "rtmpUrl": "rtmp://live.example.com/app",
  • "streamKey": "newKey456",
  • "language": "fr"
}

Delete a destination

Removes a destination from the system.

path Parameters
id
required
string <uuid>

Responses