Operations related to live streams. A live stream is a single, linear video broadcast. You broadcast a live stream by receiving encoded source video into the Wowza Video service and letting Wowza Video transcode the stream and deliver it to viewers. A live stream is essentially a one-stop method for creating a transcoder, output renditions, stream targets, and associated players.
Wowza Video
/- Reference
- REST API
- Delete a Wowza CDN stream target
Wowza CDN Stream Targets
Custom Stream Targets
Fetch all stream targets
Fetch a stream target
Create a custom stream target
Fetch all custom stream targets
Fetch a custom stream target
Update a custom stream target
Delete a custom stream target
Create a Wowza CDN stream target
Fetch all Wowza CDN stream targets
Fetch a Wowza CDN stream target
Update a Wowza CDN stream target
Regenerate the connection code for any stream target
Configure a property for a stream target
Fetch all properties of a stream target
Fetch a property of a stream target
Delete a stream target property
Delete a Wowza CDN stream...
Wowza Video REST API Reference Documentation (v2.0)
API lifecycle phase: Current
| Want to take the API for a test run? All you'll need is a Wowza Video subscription, or free trial, for the API access token. Then, fork our collection in Postman and you'll be making calls to our REST API in minutes! See Trial the Wowza Video REST API using Postman for more information. |
This reference documentation provides details about the operations, parameters, and request and response schemas for every resource and endpoint in the Wowza Video REST API. Samples appear in the right column. Sample requests are presented in cURL (Shell) and JavaScript; some samples also include just the JSON object. Response samples are all JSON. Examples in cURL use environment variables so you can easily copy and paste them. To learn more, see Using cURL.
Reference documentation is available for every version of the API. Use the Version menu at the top of the page to access the reference doc for a different version of the API.
Note: If you haven't moved over to the new Wowza Video UI experience, you won't be able to access v2.0 of the API. We're migrating customers iteratively. See Upgrade to the Wowza Video 2.0 REST API for more information.
Download OpenAPI description
Overview
License
Languages
Servers
Mock server
https://developer-m.wowza.com/_mock/docs/wowza-video/api/video/openapi
https://api.video.wowza.com/api/v2.0
Bodyapplication/jsonrequired
Provide the details of the Wowza CDN stream target to update in the body of the request.
Example: {"name":"My Updated Wowza CDN Stream Target"}
A descriptive name for the stream target. Maximum 255 characters.
Example: "name": "My Updated Stream Target"
Example: "My Updated Wowza CDN Stream Target"
The region where your Wowza Streaming Engine instance is located. Available from version 1.6.
Valid values:
- us - United States
- eu - Europe
- asia - Asia
- sa - South America
- india - India
Example: "custom_origin_region": "us"
The Wowza Streaming Engine instance's domain or IP address starting with http:// or https://. Available from version 1.6.
Note: You can find the Host - Server address on the home page of Wowza Streaming Engine under Application Connection Settings.
The path to append to the end of the playback url to make it a valid URL, to have playback through the Wowza Video Flowplayer. This is available for HLS playback only and necessary for stream targets with a custom origin.
You must have a url_suffix to enable the Share Stream feature for this stream target. The Share Stream feature enables you to host the player and use the Wowza Video player for your viewers to view your stream.
Example: "custom_origin/cW8JTDFr"
Specifies the protocols sent to the stream target. Valid values are hls and dash (MPEG-DASH). The default is hls. Available from version 1.7.
Note: If you enable more than one protocol, you'll incur egress charges for each protocol you select.
See Protect streams for Google Widevine and Microsoft PlayReady devices with EZDRM and the Wowza Video REST API for an example of setting MPEG-DASH as a delivery protocol for digital rights management (DRM) use.
Example: See response body sample
If true, requires users to play the stream over HTTPS. If false, the default, users can play the stream over HTTPS or HTTP.
Example: "force_ssl_playback": true
Example: ""
If true, controls access to the stream from specific locations and, optionally, IP addresses. The default is false.
Example: "geoblock_enabled": true
Example: ""
Specifies whether to allow or deny access to the stream from specific locations. The default is disabled.
Example: "geoblock_location": "allow"
Enum"allow""deny""disabled"
Example: ""
Required when geoblock_by_location is allow or deny. The locations affected by the geo-blocking. Enter a comma-separated list of capitalized two-letter ISO 3166-1 country codes. For a list, see ISO 3166-1 on Wikipedia.
Example: "geoblock_country_codes": "CA, DE"
Example: ""
Specifies whether specific IP addresses can override the locations that are allowed or restricted. allow permits access from IP addresses within a location that's been blocked, while deny restricts access from IP addresses within locations that are allowed. The default is disabled.
Example: "geoblock_ip_override": "allow"
Enum"allow""deny""disabled"
Example: ""
Required when geoblock_ip_override is allow or deny. Addresses that can access or restrict the stream even if they're within a specified geo-blocked location. Enter a comma-separated list of up to about 40 IPv4 and IPv6 IP addresses that always allow or deny streaming based on the geoblock_ip_override value.
Troubleshooting: The limit of 40 IP addresses is approximate because all the security information (SSL playback, geoblocking countries and IP addresses, referer header, and token auth) count toward an overall metadata limit. If you have fewer than 40 IP addresses and still receive a 422: Invalid Record (Geoblock IP addresses) error, see Geo-block Wowza CDN on Fastly stream targets with the Wowza Video REST API for more ways to lower the character count.
Example: "geoblock_ip_addresses": "77.12.34.567, 78.23.45.678"
Example: ""
Configures one or more stream target properties. The property configuration consists of a key/value pair and the section of the stream target configuration table the key/value pair is stored in. Available from version 1.7.
Example: See response body sample
Example: [{"key":"chunkSize","section":"hls","value":6}]
If true, controls access to the stream from specific domains. The client or player requesting access to the stream must send the Referer header so the origin of the request can be validated. The default is false.
Note: If you change referer_enabled to false after configuring the referer policy, then later re-enable it, you'll need to re-configure the other referer policy values as well.
Available from version 1.7. For more information about the Referer header, see the HTTP specification.
Example: "referer_enabled": true
Example: ""
The Referer header sent by the client or player can be empty and not identify the origin of the request. The default is false when referer_enabled is true. While less secure, if you know you'll have viewers with a client or player that won't send a Referer header, you can specify true to allow an empty Referer header so those viewers can still access the stream.
Available from version 1.7.
Example: "referer_allow_empty": true
Example: ""
Specifies whether to allow or deny access to the stream from specific domains. The default is allow when referer_enabled is true. Specify the domains to allow or deny in referer_domains.
Available from version 1.7.
Example: "referer_policy": "allow"
Enum"allow""deny"
Example: ""
Domains that are either allowed or blocked from accessing the stream. Enter a comma-separated list of domains that are always allowed or denied access based on the referer_policy value. Required when referer_enabled is true.
We recommend you enter the simplest form of the domain as possible, but you do need to build out the domain to the level of subdomains you want to allow or deny. You can fully express to the subdomain (mysubdomain.example.com) to specify that single, specific subdomain or you can use a wildcard (*) to cover all subdomains at a specific level (*.example.com).
Example: example.com, *.example.com, *.mysubdomain.example.com
If you entered the above example value for referer_domains, and referer_policy is allow, the following domains are allowed access to the stream:
- https://example.com
- https://subdomain.example.com, https://subdomain2.example.com, etc.
- https://subdomainA.mysubdomain.example.com, https://subdomainB.mysubdomain.example.com, etc.
Example: "referer_domains": "example.com, example2.com"
Example: ""
If true, token authentication protects the stream by ensuring that it's delivered only to authorized viewers and can't be shared by unauthorized links or player hijacking attacks. The default is false.
Example: "token_auth_enabled": true
Example: ""
The shared secret of the token authentication. Must contain only hexadecimal characters and be an even number of total characters not exceeding 32.
Example: "token_auth_shared_secret": "12345678ABCDEF"
Example: ""
If true, Wowza Video uses token authentication to protect the master playlist only and leaves individual media playlists and media segments unprotected. This feature enables playback compatibility with media players that don’t support the withCredentials property. It may also be useful when addressing token auth compatibility issues with specific browsers. The default is false.
Note: If you've enabled MPEG-DASH on your stream target, token_auth_playlist_only applies to both the playlist.m3u8 for HLS and manifest.mpd for MPEG-DASH.
Example: "token_auth_playlist_only": true
Example: ""
- Mock serverhttps://developer-m.wowza.com/_mock/docs/wowza-video/api/video/openapi/stream_targets/wowza_cdn/{id}
- https://api.video.wowza.com/api/v2.0/stream_targets/wowza_cdn/{id}
- curl
- Java
- Python
- JavaScript
curl -i -X PATCH \
'https://developer-m.wowza.com/_mock/docs/wowza-video/api/video/openapi/stream_targets/wowza_cdn/{id}' \
-H 'Content-Type: application/json' \
-d '{
"stream_target_wowza_cdn": {
"name": "My Updated Wowza CDN Stream Target"
}
}'Success
Example: {"id":"abc45lfyz","name":"My Updated Wowza CDN Stream Target","state":"activated","stream_name":"9a00105a","delivery_protocols":["hls"],"playback_urls":{"hls":[{"name":"default","url":"https://wowzasubdomain.wowza.com/1/TWhoL3BiZnJXMFhmNzZVN3JrZDAwUT09/ZmYxSXRrTERrUlk9/hls/live/playlist.m3u8"}]},"token_auth_enabled":false,"token_auth_playlist_only":false,"geoblock_enabled":false,"referer_enabled":false,"force_ssl_playback":false,"created_at":"2020-01-28T17:16:22.086Z","updated_at":"2020-01-30T18:13:55.087Z"}
The date and time that the stream target was created.
Example: "2020-01-28T17:16:22.086Z"
The region where your Wowza Streaming Engine instance is located. Available from version 1.6.
Example: ""
The Wowza Streaming Engine instance's domain or IP address. Available from version 1.6.
Example: ""
The path appended to the end of the playback url to make it a valid URL, to have playback throuogh the Wowza Video Flowplayer. This is available for HLS playback only and necessary for stream targets with a custom origin.
You must have a url_suffix to enable the Share Stream feature for this stream target. The Share Stream feature enables you to host the player and use the Wowza Video player for your viewers to view your stream.
Example: "custom_origin/cW8JTDFr"
Example: ""
An array of the delivery protocols available for this stream target. Available from version 1.7.
Example: ["hls"]
If true, requires users to play the stream over HTTPS. If false, the default, users can play the stream over HTTPS or HTTP.
Example: ""
If true, controls access to the stream from specific locations and, optionally, IP addresses. The default is false.
Example: ""
Specifies whether to allow or deny access to the stream from specific locations. The default is disabled.
Enum"allow""deny""disabled"
Example: ""
Required when geoblock_by_location is allow or deny. The locations affected by the geo-blocking. Enter a comma-separated list of capitalized two-letter ISO 3166-1 country codes. For a list, see ISO 3166-1 on Wikipedia.
Example: ""
Specifies whether specific IP addresses can override the locations that are allowed or restricted. allow permits access from IP addresses within a location that's been blocked, while deny restricts access from IP addresses within locations that are allowed. The default is disabled.
Enum"allow""deny""disabled"
Example: ""
Required when geoblock_ip_override is allow or deny. Addresses that can access or restrict the stream even if they're within a specified geo-blocked location. Enter a comma-separated list of IPv4 and IPv6 IP addresses that always allow or deny streaming based on the geoblock_ip_override value.
Example: ""
The unique alphanumeric string that identifies the stream target.
Example: "abc45lfyz"
A descriptive name for the stream target. Maximum 255 characters.
Example: "My Updated Wowza CDN Stream Target"
Web addresses that the target uses to play streams.
Example: {"hls":[{"name":"default","url":"https://wowzasubdomain.wowza.com/1/TWhoL3BiZnJXMFhmNzZVN3JrZDAwUT09/ZmYxSXRrTERrUlk9/hls/live/playlist.m3u8"}]}
If true, controls access to the stream from specific domains. The client or player requesting access to the stream must send the Referer header so the origin of the request can be validated. The default is false.
Note: If you change referer_enabled to false after configuring the referer policy, then later re-enable it, you'll need to re-configure the other referer policy values as well.
Available from version 1.7. For more information about the Referer header, see the HTTP specification.
Example: ""
The Referer header sent by the client or player can be empty and not identify the origin of the request. The default is false when referer_enabled is true. While less secure, if you know you'll have viewers with a client or player that won't send a Referer header, you can specify true to allow an empty Referer header so those viewers can still access the stream.
Available from version 1.7.
Example: ""
Specifies whether to allow or deny access to the stream from specific domains. The default is allow when referer_enabled is true. Specify the domains to allow or deny in referer_domains.
Available from version 1.7.
Enum"allow""deny"
Example: ""
Domains that are either allowed or blocked from accessing the stream. Enter a comma-separated list of domains that are always allowed or denied access based on the referer_policy value. Required when referer_enabled is true.
We recommend you enter the simplest form of the domain as possible, but you do need to build out the domain to the level of subdomains you want to allow or deny. You can fully express to the subdomain (mysubdomain.example.com) to specify that single, specific subdomain or you can use a wildcard (*) to cover all subdomains at a specific level (*.example.com).
Example: example.com, *.example.com, *.mysubdomain.example.com
If you entered the above example value for referer_domains, and referer_policy is allow, the following domains are allowed access to the stream:
- https://example.com
- https://subdomain.example.com, https://subdomain2.example.com, etc.
- https://subdomainA.mysubdomain.example.com, https://subdomainB.mysubdomain.example.com, etc.
Available from version 1.7.
Example: ""
The state of the stream target.
Enum"activated""archived"
Example: "activated"
The name of the stream being ingested into the target.
Example: "9a00105a"
If true, token authentication protects the stream by ensuring that it's delivered only to authorized viewers and can't be shared by unauthorized links or player hijacking attacks. The default is false.
Example: ""
The shared secret of the token authentication. Must contain only hexadecimal characters and be an even number of total characters not exceeding 32.
Example: ""
If true, Wowza Video uses token authentication to protect the master playlist only and leaves individual media playlists and media segments unprotected. This feature enables playback compatibility with media players that don’t support the withCredentials property. It may also be useful when addressing token auth compatibility issues with specific browsers. The default is false.
Note: If you've enabled MPEG-DASH on your stream target, token_auth_playlist_only applies to both the playlist.m3u8 for HLS and manifest.mpd for MPEG-DASH.
Example: ""
Response
application/json
{ "stream_target_wowza_cdn": { "id": "abc45lfyz", "name": "My Updated Wowza CDN Stream Target", "state": "activated", "stream_name": "9a00105a", "delivery_protocols": [ … ], "playback_urls": { … }, "token_auth_enabled": false, "token_auth_playlist_only": false, "geoblock_enabled": false, "referer_enabled": false, "force_ssl_playback": false, "created_at": "2020-01-28T17:16:22.086Z", "updated_at": "2020-01-30T18:13:55.087Z" } }
- Mock serverhttps://developer-m.wowza.com/_mock/docs/wowza-video/api/video/openapi/stream_targets/wowza_cdn/{id}
- https://api.video.wowza.com/api/v2.0/stream_targets/wowza_cdn/{id}
- curl
- Java
- Python
- JavaScript
curl -i -X DELETE \
'https://developer-m.wowza.com/_mock/docs/wowza-video/api/video/openapi/stream_targets/wowza_cdn/{id}?force=string'- Mock serverhttps://developer-m.wowza.com/_mock/docs/wowza-video/api/video/openapi/stream_targets/{id}/regenerate_connection_code
- https://api.video.wowza.com/api/v2.0/stream_targets/{id}/regenerate_connection_code
- curl
- Java
- Python
- JavaScript
curl -i -X PUT \
'https://developer-m.wowza.com/_mock/docs/wowza-video/api/video/openapi/stream_targets/{id}/regenerate_connection_code'Response
application/json
{ "stream_target": { "connection_code": "0cd2e8" } }
Operations related to schedules. Schedules allow you to automatically start or stop a live stream or transcoder at a predetermined date and time. You can configure a schedule to start and/or stop a live stream or transcoder just once, or you can configure it to repeat the behavior on a regular basis. See About schedules to learn more.
Operations
Operations related to Real-Time Streaming at Scale. If your audience is fewer than 300 viewers or you want to deliver a stream in near real time alongside other delivery protocols, use our WebRTC solution.
To enable and purchase capacity for Real-Time Streaming at Scale for your account and access the /real_time operations, contact 720.279.8163 or schedule a call.
Operations
Operations related to using advanced token authentication, known in Wowza Video as a default playback token behavior option, with videos.
Use token authentication when distributing valuable or sensitive video content to audiences to ensure that only authorized users can access the content within the intended application. This allows for protection of intellectual property, compliance with regulations, and the ability to maintain control over content distribution. The token is embedded in the videos' embed URLs.
Through the UI or Wowza Video API, you can choose one of the following options for token authentication of a video:
NO_TOKEN - Video files are accessible and can be downloaded and played by anyone at any time. This is the default.
BASIC_TOKEN - The platform automatically creates tokenized video URLs. This setting makes it hard for a viewer to extract the video URL and store it for usage in unintended applications over time since the embed URL, which has the token as part of the URL, will only be playable for 48 hours. The token auto renews after 48 hours when used in the intended application.
ADVANCED_TOKEN - You add the stream's JS embed code (Share Stream) and a token to your site to provide tokenization. The protections are similar to those for the Basic Token option except you customize the time limit, geographical limits, etc. during token creation.
FOLLOW_DEFAULT: - The token behavior is based on the Default Playback Token Behavior setting you selected for your Wowza account. See the Org Settings page in Wowza Video article for where to set this configuration.
Note: You'll use the /videos endpoints to update and review the token authentication enums bulleted above.
Before selecting to use the ADVANCED_TOKEN, you must, first, either:
- Generate a key id via the Wowza Video API, then customize and generate a token via the Wowza Video 2.0 API to add to your site. You'll need the key id to create and sign the token.
- Generate a key id and key via the Wowza Video 2.0 API, then customize and generate a standard common access token (CAT) through the means you usually use to create tokens to add to your site. You'll need the key id and key to create and sign the token.
After you have your playback token, you add the video JS-embed and the playback token to your site if you're going to use the ADVANCED_TOKEN option. The JS-embed code automatically adds the player and related video to your site. See the section on <a href="how to embed the player and video".
Operations
The player operations are deprecated in 2.0. Create and update player configurations in the user interface. Any values you send using the player operations will be ignored.
Operations related to players, which are created through the /live_streams resource. Players created through Wowza Video live streams can be embedded into your own web page or played through a web page hosted by Wowza Video.
Operations
The recordings operations are deprecated in 2.0. Use the /videos endpoints instead.
Operations related to recordings, which are created through the /live_streams or /transcoders resources. The Wowza Video service can create MP4 recordings of your live streams and transcoded output. Recordings can be downloaded and saved locally. They're based on the highest-bitrate output rendition that Wowza Video generates from your video source. See About recordings to learn more.
Operations
The VOD stream operations are deprecated in 2.0. Use the /videos endpoints instead.
Operations related to video on demand (VOD) streams, which are created through the /live_streams or /transcoders resources. A VOD stream is a recording of a live stream that viewers can replay at a later date. After the broadcast is over and the live stream or transcoder is stopped, Wowza Video creates the VOD stream and generates a playback URL. See About VOD Streams to learn more.
Operations