Skip to main content
API docs by Redocly

Management API (1.0.0)

Download OpenAPI specification:Download

Test the API with Swagger at https://api.cdn.vindral.com/api-docs

API Keys and Permissions

The API key used for authentication is tied to a user and shares the permissions of that user which is configured in the Vindral Portal. In addition to the user level permissions each API key has a scope of either read-only or read-write.

Read more about permissions here

Channels

List channels

Get a list of channels that the provided api key has access to.

Authorizations:
Authorization
query Parameters
skip
number
Default: 0

Omits the specified number of returned records. This is useful, for example, to paginate responses.

take
number
Default: 100

Specifies how many records to include in the response.

orderBy
string
Default: "name"
Enum: "channelId" "name" "streamKey"

Specifies which column to sort the response by.

string or string
Default: "asc"

How to sort the response records, either in ascending or descending order.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Create channel

Create a new channel. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
Request Body schema: application/json
required
name
required
string [ 2 .. 50 ] characters

Name of the channel.

authRequired
boolean
Default: false

true if the channel should be protected and require a valid token to watch it.

notes
string <= 500 characters
Default: ""

Notes for the channel.

transcodingProfileId
required
string <uuid>

Transcoding profile to use for this channel.

object
object

Recording configuration.

Array of objects

Restreaming configuration.

organizationId
required
string <uuid>

Organization that the channel should be added to.

channelId
string

ChannelId (public id) for the channel, required as: ${normalizedOrganizationName}_${normalizedName}_ci_${uuid}. If not provided, this will be generated.

streamKey
string

Stream key (private id) for the channel, required as: ${normalizedOrganizationName}_${normalizedName}_sk_${uuid}. If not provided, this will be generated.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "authRequired": false,
  • "notes": "",
  • "transcodingProfileId": "837bdf0e-3944-423b-9940-32e2c71da88b",
  • "viewerCountryLimitation": {
    },
  • "recording": {
    },
  • "restreaming": [
    ],
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "channelId": "string",
  • "streamKey": "string"
}

Response samples

Content type
application/json
{
  • "authRequired": true,
  • "channelId": "string",
  • "name": "string",
  • "notes": "string",
  • "streamKey": "string",
  • "suspended": true,
  • "isLive": true,
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "transcodingProfileId": "string",
  • "viewerCountryLimitation": {
    },
  • "restreaming": [
    ],
  • "recording": {
    }
}

List channels by channel group

Get a list of channels belonging to a specific channel group.

Authorizations:
Authorization
path Parameters
channelGroupId
required
string

The channel group id to get channels for.

query Parameters
skip
number
Default: 0

Omits the specified number of returned records. This is useful, for example, to paginate responses.

take
number
Default: 100

Specifies how many records to include in the response.

orderBy
string
Default: "name"
Enum: "channelId" "name" "streamKey"

Specifies which column to sort the response by.

string or string
Default: "asc"

How to sort the response records, either in ascending or descending order.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

List channels by transcoding profile

Get a list of channels with a specific transcoding profile.

Authorizations:
Authorization
path Parameters
transcodingProfileId
required
string <uuid>

The transcoding profile id to get channels for.

query Parameters
skip
number
Default: 0

Omits the specified number of returned records. This is useful, for example, to paginate responses.

take
number
Default: 100

Specifies how many records to include in the response.

orderBy
string
Default: "name"
Enum: "channelId" "name" "streamKey"

Specifies which column to sort the response by.

string or string
Default: "asc"

How to sort the response records, either in ascending or descending order.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Get channel

Get a channel by channel id.

Authorizations:
Authorization
path Parameters
channelId
required
string

ID of the channel to get.

Responses

Response samples

Content type
application/json
{
  • "authRequired": true,
  • "channelId": "string",
  • "name": "string",
  • "notes": "string",
  • "streamKey": "string",
  • "suspended": true,
  • "isLive": true,
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "transcodingProfileId": "string",
  • "viewerCountryLimitation": {
    },
  • "restreaming": [
    ],
  • "recording": {
    }
}

Update channel

Update a channel by channel id. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
path Parameters
channelId
required
string

ID of the channel to update.

Request Body schema: application/json
required
name
string [ 2 .. 50 ] characters

Name of the channel.

authRequired
boolean

true if the channel should be protected and require a valid token to watch it.

notes
string <= 500 characters

Notes for the channel.

transcodingProfileId
string <uuid>

Transcoding profile to use for this channel.

object
object

Recording configuration.

Array of objects

Restreaming configuration.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "authRequired": true,
  • "notes": "string",
  • "transcodingProfileId": "837bdf0e-3944-423b-9940-32e2c71da88b",
  • "viewerCountryLimitation": {
    },
  • "recording": {
    },
  • "restreaming": [
    ]
}

Response samples

Content type
application/json
{
  • "authRequired": true,
  • "channelId": "string",
  • "name": "string",
  • "notes": "string",
  • "streamKey": "string",
  • "suspended": true,
  • "isLive": true,
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "transcodingProfileId": "string",
  • "viewerCountryLimitation": {
    },
  • "restreaming": [
    ],
  • "recording": {
    }
}

Create or update channel

Creates or updates a channel by channelId.

If the channelId exists, it will be updated - otherwise created.

channelId, streamKey or organizationId will not be changed on an existing channel, but are required to match.

Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
path Parameters
channelId
required
string

ChannelId (public id) for the channel, required as: ${normalizedOrganizationName}_${normalizedName}_ci_${uuid}.

Request Body schema: application/json
required
name
required
string [ 2 .. 50 ] characters

Name of the channel.

transcodingProfileId
required
string <uuid>

Transcoding profile to use for this channel.

authRequired
boolean
Default: false

true if the channel should be protected and require a valid token to watch it.

notes
string <= 500 characters
Default: ""

Notes for the channel.

organizationId
required
string <uuid>

Organization that the channel should be added to. Will not update on existing channel.

required
object
required
object or (any or null)

Recording configuration, passing null will remove saved configuration.

required
Array of objects

Restreaming configuration.

streamKey
required
string

Stream key (private id) for the channel, required as: ${normalizedOrganizationName}_${normalizedName}_sk_${uuid}.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "transcodingProfileId": "837bdf0e-3944-423b-9940-32e2c71da88b",
  • "authRequired": false,
  • "notes": "",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "viewerCountryLimitation": {
    },
  • "recording": {
    },
  • "restreaming": [
    ],
  • "streamKey": "string"
}

Response samples

Content type
application/json
{
  • "authRequired": true,
  • "channelId": "string",
  • "name": "string",
  • "notes": "string",
  • "streamKey": "string",
  • "suspended": true,
  • "isLive": true,
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "transcodingProfileId": "string",
  • "viewerCountryLimitation": {
    },
  • "restreaming": [
    ],
  • "recording": {
    }
}

Delete channel

Delete a channel by channel id. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
path Parameters
channelId
required
string

ID of the channel to delete.

Responses

Response samples

Content type
application/json
null

Channel Groups

Get channel group

Get one channel group by id.

Authorizations:
Authorization
path Parameters
channelGroupId
required
string

ID of the channel group to get.

Responses

Response samples

Content type
application/json
{
  • "channelGroupId": "string",
  • "name": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9"
}

Update channel group

Update a channel group with by channel group id. If the channel array is passed in the whole array will be updated with the new array. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
path Parameters
channelGroupId
required
string

ID of the channel group to update.

Request Body schema: application/json
required
name
string <= 50 characters

Name of the channel group.

channelIds
Array of strings

List of channel IDs that should be part of the group.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "channelIds": [
    ]
}

Response samples

Content type
application/json
{
  • "channelGroupId": "string",
  • "name": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9"
}

Delete channel group

Delete channel group by id. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
path Parameters
channelGroupId
required
string

ID of the channel group to remove.

Responses

Response samples

Content type
application/json
null

List channel groups

Get a list of channel groups that the provided api key has access to.

Authorizations:
Authorization
query Parameters
skip
number
Default: 0

Omits the specified number of returned records. This is useful, for example, to paginate responses.

take
number
Default: 100

Specifies how many records to include in the response.

orderBy
string
Default: "name"
Enum: "name" "channelGroupId"

Specifies which column to sort the response by.

string or string
Default: "asc"

How to sort the response records, either in ascending or descending order.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Create channel group

Create a new channel group for a specified name and organization. Optionally add a list of channel ids that should belong to the new channel group. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
Request Body schema: application/json
required
name
required
string <= 50 characters

Name of the channel group.

organizationId
required
string <uuid>

Organization that the channel group should be added to.

channelIds
Array of strings

List of channel IDs that should be part of the group.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "channelIds": [
    ]
}

Response samples

Content type
application/json
{
  • "channelGroupId": "string",
  • "name": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9"
}

Add channel to channel group

Add one channel to a channel group. Specify a channelGroupId and a channelId you wish to add to the channel group. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
path Parameters
channelGroupId
required
string

ID of the channel group to add channel to.

channelId
required
string

ID of the channel that should be added to the channel group.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Remove channel from channel group

Remove one channel from a channel group. Specify a channelGroupId and a channelId you wish to remove from the channel group. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
path Parameters
channelGroupId
required
string

ID of the channel group to remove channel from.

channelId
required
string

ID of the channel to remove from the channel group.

Responses

Response samples

Content type
application/json
null

Transcoding Profiles

List transcoding profiles

Get a list of transcoding profiles that the provided api key has access to.

Authorizations:
Authorization
query Parameters
skip
number
Default: 0

Omits the specified number of returned records. This is useful, for example, to paginate responses.

take
number
Default: 100

Specifies how many records to include in the response.

orderBy
string
Default: "name"
Value: "name"

Specifies which column to sort the response by.

string or string
Default: "asc"

How to sort the response records, either in ascending or descending order.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Create transcoding profile

Create a new transcoding profile. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
Request Body schema: application/json
required
name
required
string
notes
required
string
organizationId
required
string <uuid>
required
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "notes": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "notes": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "config": {
    }
}

Get transcoding profile

Get a transcoding profile by id.

Authorizations:
Authorization
path Parameters
transcodingProfileId
required
string <uuid>

ID of the transcoding profile to get.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "notes": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "config": {
    }
}

Update transcoding profile

Update a transcoding profile by id. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
path Parameters
transcodingProfileId
required
string <uuid>
Request Body schema: application/json
required
id
string <uuid>
name
string
notes
string
object

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "notes": "string",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "notes": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "config": {
    }
}

Delete transcoding profile

Delete a transcoding profile by id. Channels that referenced the deleted transcoding profile will be unusable until assigned a new transcoding profile. Requires a read-write scoped API key with sufficient permissions.

Authorizations:
Authorization
path Parameters
transcodingProfileId
required
string <uuid>

Responses

Response samples

Content type
application/json
null

Get transcoding profile by channel

Get the transcoding profile configured for the specific channel.

Authorizations:
Authorization
path Parameters
channelId
required
string

ID of the channel to get the transcoding profile for.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "notes": "string",
  • "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  • "config": {
    }
}

Profile

Get profile

Get profile info based on the api token used to make the request.

Authorizations:
Authorization

Responses

Response samples

Content type
application/json
{
  • "apiKey": {
    },
  • "user": {
    },
  • "organizations": [
    ]
}

Ingest

Get ingest information

Get ingest information for a channel.

Authorizations:
Authorization
path Parameters
channelId
required
string

ID of the channel to get.

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "playUrl": {
    }
}

Drop ingest

Drop ingest for a channel.

Authorizations:
Authorization
path Parameters
channelId
required
string

ID of the channel to drop.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "status": "Drop requested"
}

Status

Get channel status

Get live status and viewers for all channels in an organization.

Authorizations:
Authorization
query Parameters
organizationId
required
string <uuid>

ID of the organization to get analytics data for.

Responses

Response samples

Content type
application/json
{
  • "viewersTotal": 0,
  • "ingressBps": 0,
  • "egressBps": 0,
  • "channels": [
    ]
}

Analytics

Get current viewers

Get current number of viewers for an organization. Use the optional query parameters channelId, countryCode and continent to filter the results. Use the optional query parameter groupBy to group the results by country or channel.

Authorizations:
Authorization
query Parameters
organizationId
required
string <uuid>

ID of the organization to get analytics data for.

channelId
string

Filters for the specific channel.

any or string

Country code (ISO 3166-1 alpha-2) to filter the data on a specific country. Special code unknown is used when a lookup was not possible.

Example: SE to filter for Sweden.

any or string

Continent code to filter the data for a specific continent. Valid continent codes:

  • AF: Africa
  • AN: Antarctica
  • AS: Asia
  • EU: Europe
  • NA: North America
  • OC: Oceania
  • SA: South America
  • unknown: Unknown continent. Special code unknown is used when a lookup was not possible.

Example: EU to filter for Europe.

groupBy
string
Enum: "channel" "country"

Optionally group by channel or country. Default is no grouping. Valid values: channel, country.

Responses

Response samples

Content type
application/json
{
  • "channels": [
    ]
}

Get metrics

Get metrics. Use the optional query parameters channelId, countryCode and continent to filter the results. Metrics are calculated for the time range between from and to. By default all available metrics are returned, to limit the response use the optional query parameter fields to specify which metrics to return.

Note that viewerBitrateAverage, totalIngressBytes, restartCount, hlsEgressBytes, clippingBytes, rtmpEgressBytes and restreamBytes disregards country and continent filters!

Authorizations:
Authorization
query Parameters
organizationId
required
string <uuid>

ID of the organization to get analytics data for.

channelId
string

Filters for the specific channel.

any or string

Country code (ISO 3166-1 alpha-2) to filter the data on a specific country. Special code unknown is used when a lookup was not possible.

Example: SE to filter for Sweden.

any or string

Continent code to filter the data for a specific continent. Valid continent codes:

  • AF: Africa
  • AN: Antarctica
  • AS: Asia
  • EU: Europe
  • NA: North America
  • OC: Oceania
  • SA: South America
  • unknown: Unknown continent. Special code unknown is used when a lookup was not possible.

Example: EU to filter for Europe.

fields
string

Limit the response by selecting specific fields as a comma separated list. Available fields are:

  • viewerSessions
  • viewerSeconds
  • viewerSessionsAvgDurationSeconds
  • viewerBitrateAverage
  • totalEgressBytes
  • totalIngressBytes
  • timeToFirstFrameMedianMs
  • roundTripTimeMedianMs
  • browsers
  • os
  • devices
  • restartCount
  • hlsEgressBytes
  • clippingBytes
  • rtmpEgressBytes
  • restreamBytes

Example: viewerSessions,viewerBitrateAverage to only get viewer sessions and average bitrate.

groupBy
string
Enum: "channel" "country"

Optionally group by channel or country. Default is no grouping. Valid values: channel, country.

from
required
string

Date in ISO 8601 format.

Example: 2024-01-01T00:00:00Z.

to
required
string

Date in ISO 8601 format.

Example: 2024-01-01T00:00:00Z.

Responses

Response samples

Content type
application/json
{
  • "viewerSessions": 0,
  • "viewerSeconds": 0,
  • "viewerSessionsAvgDurationSeconds": 0,
  • "viewerBitrateAverage": 0,
  • "totalEgressBytes": 0,
  • "totalIngressBytes": 0,
  • "restartCount": 0,
  • "hlsEgressBytes": 0,
  • "clippingBytes": 0,
  • "rtmpEgressBytes": 0,
  • "restreamBytes": 0,
  • "timeToFirstFrameMedianMs": { },
  • "roundTripTimeMedianMs": { },
  • "browserDistribution": [
    ],
  • "osDistribution": [
    ],
  • "deviceDistribution": [
    ]
}

Get time series

Get time series. Use the optional query parameters channelId, countryCode and continent to filter the results. Time series are calculated for the time range between from and to (rounded to the nearest minute). By default all available time series are returned, to limit the response use the optional query parameter fields to specify which metrics to return.

Note that ingressBps, keyframeDelta, averagePacketArrivalTime and highestPacketArrivalTime disregards country and continent filters and is not returned when grouped by country!

Authorizations:
Authorization
query Parameters
organizationId
required
string <uuid>

ID of the organization to get analytics data for.

channelId
string

Filters for the specific channel.

any or string

Country code (ISO 3166-1 alpha-2) to filter the data on a specific country. Special code unknown is used when a lookup was not possible.

Example: SE to filter for Sweden.

any or string

Continent code to filter the data for a specific continent. Valid continent codes:

  • AF: Africa
  • AN: Antarctica
  • AS: Asia
  • EU: Europe
  • NA: North America
  • OC: Oceania
  • SA: South America
  • unknown: Unknown continent. Special code unknown is used when a lookup was not possible.

Example: EU to filter for Europe.

fields
string

Limit the response by selecting specific fields as a comma separated list. Available fields are:

  • viewers
  • egressBps
  • ingressBps
  • keyframeDeltaVideo
  • averagePacketArrivalTimeVideo
  • highestPacketArrivalTimeVideo
  • keyframeDeltaAudio
  • averagePacketArrivalTimeAudio
  • highestPacketArrivalTimeAudio

Example: viewers,egressBps to only get time series for viewers and egress.

from
required
string

Date in ISO 8601 format.

Example: 2024-01-01T00:00:00Z.

to
required
string

Date in ISO 8601 format.

Example: 2024-01-01T00:00:00Z.

Responses

Response samples

Content type
application/json
{
  • "viewers": [
    ],
  • "egressBps": [
    ],
  • "ingressBps": [
    ],
  • "keyframeDeltaVideo": [
    ],
  • "averagePacketArrivalTimeVideo": [
    ],
  • "highestPacketArrivalTimeVideo": [
    ],
  • "keyframeDeltaAudio": [
    ],
  • "averagePacketArrivalTimeAudio": [
    ],
  • "highestPacketArrivalTimeAudio": [
    ]
}

Clipping

Generate a clip from a recording

Creates a custom clip of a recorded live stream.

This endpoint will return a m3u8 playlist which can be used in any HLS-compatible video player.

Please note that the response will be a 302 redirect, with the Location header set to the URL of your clip.

Authorizations:
Authorization
path Parameters
channelId
required
string

ID of the channel

query Parameters
from
required
string

Date in ISO 8601 format.

Example: 2024-01-01T00:00:00Z.

to
required
string

Date in ISO 8601 format.

Example: 2024-01-01T00:00:00Z.

Responses

Response samples

Content type
application/json
null

Generate a clip from a recording

Creates a custom clip of a recorded live stream.

This endpoint will return a mp4 which can be used in any compatible video player.

Please note that the response will be a 302 redirect, with the Location header set to the URL of your clip.

Authorizations:
Authorization
path Parameters
channelId
required
string

ID of the channel

query Parameters
from
required
string

Date in ISO 8601 format.

Example: 2024-01-01T00:00:00Z.

to
required
string

Date in ISO 8601 format.

Example: 2024-01-01T00:00:00Z.

Responses

Response samples

Content type
application/json
null