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.

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

200
default

Content type

application/json

{"items": [{"authRequired": true,
"channelId": "string",
"name": "string",
"notes": "string",
"streamKey": "string",
"suspended": true,
"isLive": true,
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"transcodingProfileId": "string",
"viewerCountryLimitation": {"mode": "allow",
"limited": ["string"
]
}
}
],
"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

authRequired	boolean Default: false `true` if the channel should be protected and require a valid token to watch it.
name required	string <= 50 characters Name of the channel.
notes	string <= 500 characters Default: "" Notes for the channel.
organizationId required	string <uuid> Organization that the channel should be added to.
transcodingProfileId	string <uuid> Transcoding profile to use for this channel.

Responses

Request samples

Payload

Content type

application/json

{"authRequired": false,
"name": "string",
"notes": "",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"transcodingProfileId": "837bdf0e-3944-423b-9940-32e2c71da88b"
}

Response samples

200
default

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": {"mode": "allow",
"limited": ["string"
]
}
}

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

200
default

Content type

application/json

{"items": [{"authRequired": true,
"channelId": "string",
"name": "string",
"notes": "string",
"streamKey": "string",
"suspended": true,
"isLive": true,
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"transcodingProfileId": "string",
"viewerCountryLimitation": {"mode": "allow",
"limited": ["string"
]
}
}
],
"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

200
default

Content type

application/json

{"items": [{"authRequired": true,
"channelId": "string",
"name": "string",
"notes": "string",
"streamKey": "string",
"suspended": true,
"isLive": true,
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"transcodingProfileId": "string",
"viewerCountryLimitation": {"mode": "allow",
"limited": ["string"
]
}
}
],
"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

200
default

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": {"mode": "allow",
"limited": ["string"
]
}
}

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

authRequired	boolean `true` if the channel should be protected and require a valid token to watch it.
name	string <= 50 characters Name of the channel.
notes	string <= 500 characters Notes for the channel.
transcodingProfileId	string <uuid> Transcoding profile to use for this channel.
	object

Responses

Request samples

Payload

Content type

application/json

{"authRequired": true,
"name": "string",
"notes": "string",
"transcodingProfileId": "837bdf0e-3944-423b-9940-32e2c71da88b",
"viewerCountryLimitation": {"mode": "allow",
"limited": ["string"
]
}
}

Response samples

200
default

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": {"mode": "allow",
"limited": ["string"
]
}
}

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

204
default

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

200
default

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

Payload

Content type

application/json

{"name": "string",
"channelIds": ["string"
]
}

Response samples

200
default

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

204
default

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

200
default

Content type

application/json

{"items": [{"channelGroupId": "string",
"name": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9"
}
],
"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

Payload

Content type

application/json

{"name": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"channelIds": ["string"
]
}

Response samples

200
default

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

Payload

Content type

application/json

{ }

Response samples

200
default

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

204
default

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

200
default

Content type

application/json

{"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"notes": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"config": {"streams": [{"id": "string",
"passthrough": true,
"matchSource": {"streamId": 0
},
"type": "audio",
"renditions": [{"id": "string",
"bitRate": 8000,
"codec": "string",
"sampleRate": 0,
"channels": 1
}
]
}
]
}
}
],
"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

Payload

Content type

application/json

{"name": "string",
"notes": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"config": {"streams": [{"type": "audio",
"renditions": [{"bitRate": 96000,
"codec": "opus",
"sampleRate": 0,
"channels": 1
}
],
"passthrough": true,
"matchSource": {"streamId": 0
}
}
]
}
}

Response samples

200
default

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"notes": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"config": {"streams": [{"id": "string",
"passthrough": true,
"matchSource": {"streamId": 0
},
"type": "audio",
"renditions": [{"id": "string",
"bitRate": 8000,
"codec": "string",
"sampleRate": 0,
"channels": 1
}
]
}
]
}
}

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

200
default

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"notes": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"config": {"streams": [{"id": "string",
"passthrough": true,
"matchSource": {"streamId": 0
},
"type": "audio",
"renditions": [{"id": "string",
"bitRate": 8000,
"codec": "string",
"sampleRate": 0,
"channels": 1
}
]
}
]
}
}

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

Payload

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"notes": "string",
"config": {"streams": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"passthrough": true,
"matchSource": {"streamId": 0
},
"type": "audio",
"renditions": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"bitRate": 96000,
"codec": "opus",
"sampleRate": 0,
"channels": 1
}
]
}
]
}
}

Response samples

200
default

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"notes": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"config": {"streams": [{"id": "string",
"passthrough": true,
"matchSource": {"streamId": 0
},
"type": "audio",
"renditions": [{"id": "string",
"bitRate": 8000,
"codec": "string",
"sampleRate": 0,
"channels": 1
}
]
}
]
}
}

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

204
default

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

200
default

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"notes": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"config": {"streams": [{"id": "string",
"passthrough": true,
"matchSource": {"streamId": 0
},
"type": "audio",
"renditions": [{"id": "string",
"bitRate": 8000,
"codec": "string",
"sampleRate": 0,
"channels": 1
}
]
}
]
}
}

Profile

Get profile

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

Authorizations:

Authorization

Responses

Response samples

200
default

Content type

application/json

{"apiKey": {"name": "string",
"scope": "read"
},
"user": {"name": "string",
"email": "string"
},
"organizations": [{"name": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"role": "administrator"
}
]
}

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

200
default

Content type

application/json

{"active": true,
"playUrl": {"rtmp": "string"
}
}

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

200
default

Content type

application/json

{"viewersTotal": 0,
"ingressBps": 0,
"egressBps": 0,
"channels": [{"channelId": "string",
"viewers": 0,
"isLive": true
}
]
}

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

200
default

Content type

application/json

{"channels": [{"channelId": "string",
"viewers": 0
}
]
}

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 returned values for viewerBitrateAverage and totalIngressBytes 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` Example: `viewerSessions,viewerBitrateAverage` to only get viewer sessions and average bitrate.
from required	string Start of the time range in ISO 8601 format. Time will be rounded to nearest minute. Example: `2024-01-01T00:00:00Z`.
to required	string End of the time range in ISO 8601 format. Time will be rounded to nearest minute. Example: `2024-01-02T00:00:00Z`.

Responses

Response samples

200
default

Content type

application/json

{"viewerSessions": 0,
"viewerSeconds": 0,
"viewerSessionsAvgDurationSeconds": 0,
"viewerBitrateAverage": 0,
"totalEgressBytes": 0,
"totalIngressBytes": 0,
"timeToFirstFrameMedianMs": { },
"roundTripTimeMedianMs": { },
"browserDistribution": [{"key": "string",
"value": 100
}
],
"osDistribution": [{"key": "string",
"value": 100
}
],
"deviceDistribution": [{"key": "string",
"value": 100
}
]
}

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. By default all available time series are returned, to limit the response use the optional query parameter fields to specify which metrics to return.

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` Example: `viewers,egressBps` to only get time series for viewers and egress.
from required	string Start of the time range in ISO 8601 format. Time will be rounded to nearest minute. Example: `2024-01-01T00:00:00Z`.
to required	string End of the time range in ISO 8601 format. Time will be rounded to nearest minute. Example: `2024-01-02T00:00:00Z`.

Responses

Response samples

200
default

Content type

application/json

{"viewers": [{"timestamp": "string",
"value": 0
}
],
"egressBps": [{"timestamp": "string",
"value": 0
}
],
"ingressBps": [{"timestamp": "string",
"value": 0
}
]
}

Management API (1.0.0)

API Keys and Permissions

Channels

List channels

Authorizations:

query Parameters

Responses

Response samples

Create channel

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List channels by channel group

Authorizations:

path Parameters

query Parameters

Responses

Response samples

List channels by transcoding profile

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Get channel

Authorizations:

path Parameters

Responses

Response samples

Update channel

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete channel

Authorizations:

path Parameters

Responses

Response samples

Channel Groups

Get channel group

Authorizations:

path Parameters

Responses

Response samples

Update channel group

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete channel group

Authorizations:

path Parameters

Responses

Response samples

List channel groups

Authorizations:

query Parameters

Responses

Response samples

Create channel group

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Add channel to channel group

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Remove channel from channel group

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required