openapi: 3.0.2
info:
version: v2.0
title: Wowza Video REST API Reference Documentation
license:
name: Terms of Use
url: https://www.wowza.com/legal/terms-of-use
description: >
API lifecycle phase:
[Current](https://www.wowza.com/docs/wowza-video-rest-api-lifecycle-management#api-lifecycle0)
<table>
<tr style="background-color:lightgrey;"><td>
<strong>Want to take the API for a test run?</strong>
All you'll need is a [Wowza Video
subscription](https://www.wowza.com/pricing), or [free
trial](https://www.wowza.com/free-trial), for the API access token. Then,
fork [our collection in
Postman](https://www.postman.com/wowzavideo/workspace/wowza-video-rest-api)
and you'll be
making calls to our REST API in minutes!
See [Trial the Wowza Video REST API using
Postman](https://www.wowza.com/docs/trial-the-wowza-video-rest-api-using-postman)
for more information.
</td>
</tr>
</table>
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](https://wowza.com/docs/how-to-use-the-wowza-video-rest-api#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.
<blockquote><strong>Note</strong>: 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 <a
href="https://developer.wowza.com/docs/wowza-video/upgrade-to-wowza-video/">Upgrade
to the Wowza Video 2.0 REST API</a> for more information.</blockquote>
servers:
- url: https://api.video.wowza.com/api/v2.0
tags:
- name: live_streams
description: >-
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.
x-displayName: Live Streams
- name: players
description: >-
<blockquote>The <strong>player</strong> operations are deprecated in 2.0.
Create and update player configurations in the user interface. Any values
you send using the <strong>player</strong> operations will be
ignored.</blockquote>
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.
x-displayName: Players
- name: assets
description: >-
<blockquote>The <strong>assets</strong> operations are deprecated in 2.0.
Use the <strong>/videos</strong> endpoints instead.</blockquote>
Operations related to assets, which are created through the ``/assets``
resources. The Wowza Video service can store and transcode mp4 files that
you can tag, manage, and restream.
x-displayName: Assets
- name: recordings
description: >-
<blockquote>The <strong>recordings</strong> operations are deprecated in
2.0. Use the <strong>/videos</strong> endpoints instead.</blockquote>
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](https://www.wowza.com/docs/record-live-streams-and-transcoders#aboutREC)
to learn more.
x-displayName: Recordings
- name: schedules
description: >-
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](https://www.wowza.com/docs/schedule-live-streams-and-transcoders#aboutSCH)
to learn more.
x-displayName: Schedules
- name: stream_sources
description: >-
Operations related to stream sources. You can create a Wowza stream source
and associate it to a live stream or transcoder.
### Wowza Stream Sources
When you set up a Wowza stream source with a live stream or transcoder, Wowza Video can automatically detect broadcast location, automatically start a stream when the video source starts, and automatically stop a stream after the video source disconnects.
x-displayName: Stream Sources
- name: stream_targets
description: >-
Operations related to stream targets. A stream target is a destination for
a stream. Stream targets can be Wowza Video edge resources; custom,
external destinations, target destinations.
### Wowza CDN Stream Targets
Wowza CDN stream targets distribute streams to players. When you create a live stream in the API, a Wowza CDN stream target is created automatically.
In contrast, you can use ``/stream_targets/wowza_cdn`` endpoints to manually create Wowza CDN stream targets and associate them with transcoders.
With Wowza CDN stream targets, you can use geo-blocking to control locations where your stream can be viewed, and you can use token authentication to restrict access to streams. Advanced configuration properties are available for Wowza CDN stream targets.
### Custom Stream Targets
Custom stream targets connect to external CDNs to deliver streams to viewers. You manually create custom stream targets and associate them to a transcoder.
x-displayName: Stream Targets
- name: transcoders
description: >-
Operations related to transcoders, output renditions, and output stream
targets.
### Transcoders
Wowza Video transcoders allow you to customize transcoding processes by creating transcoders that are optimized for various network or streaming conditions. When you create a transcoder through the ``/transcoders`` endpoint, you must manually configure output renditions and associated output stream targets.
Transcoders, like live streams, can be adaptive bitrate or passthrough. An adaptive bitrate transcoder generates multiple output renditions of your live stream, at different bitrates. A passthrough transcoder, in contrast, sends the source video to a stream target without performing transcoding. Passthrough transcoders, which can only be created if you have a subscription plan that supports them, accrue processing time, bandwidth, and egress usage, but much less than their adaptive bitrate counterparts.
### Output Renditions
Before you can start an adaptive bitrate transcoder, you must use the ``/transcoders/{transcoder_id}/outputs`` operations to define the adaptive bitrate output renditions that you want the transcoder to create. Passthrough transcoders require only one output rendition because they send source video to a stream target without transcoding.
### Output Stream Targets
Transcoders require output stream targets before you can start them. Although you create and configure stream targets using the different ``/stream_targets`` operations, you must associate a stream target to a transcoder's output rendition using the /transcoders/{transcoder_id}/outputs/{output_id}/output_stream_targets operations. For an adaptive bitrate transcoder with multiple output renditions defined, you must create output stream targets to associate a stream target to each output rendition. For a passthrough transcoder, you only need one output stream target.
x-displayName: Transcoders
- name: vod_streams
description: >-
<blockquote>The <strong>VOD stream</strong> operations are deprecated in
2.0. Use the <strong>/videos</strong> endpoints instead.</blockquote>
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](https://www.wowza.com/docs/create-a-vod-stream#about-vod-streams)
to learn more.
x-displayName: VOD Streams
- name: real_time
description: >-
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, <a
href="https://www.wowza.com/docs/deliver-webrtc-streams-to-viewers-using-the-wowza-video-rest-api">use
our WebRTC solution</a>.
<blockquote>To enable and purchase capacity for Real-Time Streaming at
Scale for your account and access the <tt>/real_time</tt> operations,
contact 720.279.8163 or <a
href="https://www.wowza.com/professional-services#get-a-quote">schedule a
call</a>.</blockquote>
x-displayName: Real-Time Streams
- name: usage
description: >-
Operations related to stream target analytics, including CDN usage and
viewer data.
x-displayName: Stream Targets
- name: usage_transcoders
description: Operations related to transcoder analytics.
x-displayName: Transcoders
- name: usage_live_streams
description: Operations related to livestream analytics.
x-displayName: Livestreams
- name: storage
description: |-
<blockquote>The <strong>storage</strong> operations are deprecated in 2.0.
Operations related to peak and current storage for an account.
x-displayName: Storage
- name: usage_vod_streams
description: >-
<blockquote>The <strong>VOD stream</strong> operations are deprecated in
2.0.
Operations related to video on demand (VOD) stream analytics.
x-displayName: VOD Streams (Usage)
- name: usage_real_time_streams
description: Operations related to real-time streams analytics.
x-displayName: Real Time Streams
- name: usage_account
description: Operations related to stream analytics for an account.
x-displayName: Account
- name: analytics_viewers
description: Operations related to viewer analytics.
x-displayName: Viewers
- name: analytics_ingest
description: Operations related to ingest analytics for a live stream.
x-displayName: Ingest
- name: analytics_engagement
description: Operations related to engagement analytics for a VOD stream.
x-displayName: Engagement
- name: analytics_popularity
description: Operations related to popularity analytics.
x-displayName: Popularity
- name: quality_of_experience
description: Operations related to quality of experience metrics.
x-displayName: Quality of Experience
- name: videos
description: Operations related to uploading and categorizing videos.
x-displayName: Videos
- name: categories
description: Operations related to categorizing videos.
x-displayName: Categories
- name: advanced_token_authentication
description: >-
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 <a
href="https://www.wowza.com/docs/video-details-page-in-wowza-video"
target="_blank">UI</a> or <a
href="https://developer.wowza.com/docs/wowza-video/api/video/current/tag/videos/#tag/videos/operation/patchVideo"
target="_blank">Wowza Video API</a>, 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 <a href="https://www.wowza.com/docs/org-setting-page-in-wowza-video" target="_blank">Org Settings page in Wowza Video</a> article for where to set this configuration.
**Note:** You'll use the <a href="https://developer.wowza.com/docs/wowza-video/api/video/current/tag/videos/#tag/videos/operation/patchVideo" target="_blank">/videos endpoints</a> 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="<a href="https://developer.wowza.com/docs/wowza-video/api/video/current/tag/videos/#tag/videos/operation/patchVideo" target="_blank">how to embed the player and video</a>".
x-displayName: Advanced Token Authentication
- name: clipping
description: Operations related to clipping and stitching videos and live streams.
x-displayName: Clipping
paths:
/live_streams:
post:
summary: Create a live stream
description: This operation creates a live stream.
operationId: createLiveStream
tags:
- live_streams
x-codeSamples:
- lang: Shell
source: |
// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
-H "Content-Type: application/json" \
-X "POST" \
"${WV_HOST}/api/v2.0/live_streams" \
-d $'{
"live_stream": {
"name": "My New Live Stream",
"transcoder_type": "transcoded",
"billing_mode": "pay_as_you_go",
"broadcast_location": "us_west_california",
"encoder": "other_rtmp",
"delivery_method": "push",
"aspect_ratio_width": 1920,
"aspect_ratio_height": 1080
}
}'
- lang: JavaScript
source: |
// Using Node.js
const https = require('https');
const crypto = require('crypto');
var hostname = 'api.video.wowza.com'
var path = '/api/v2.0/live_streams';
//For security, never reveal API token in client-side code
var wvJWT = 'Bearer [your JWT]';
const options = {
hostname: hostname,
path: path,
method: 'POST',
headers: {
'Authorization': wvJWT,
'Content-Type': 'application/json'
}
};
const req = https.request(options, function(res) {
var body = '';
res.on('data', function(data) {
body += data;
});
res.on('end', function() {
console.log(JSON.parse(body));
});
}).on('error', function(e) {
console.log(e.message);
});
req.write(JSON.stringify({
"live_stream": {
"name": "My New Live Stream",
"transcoder_type": "transcoded",
"billing_mode": "pay_as_you_go",
"broadcast_location": "us_west_california",
"encoder": "other_rtmp",
"delivery_method": "push",
"aspect_ratio_width": 1920,
"aspect_ratio_height": 1080
}
}));
req.end();
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/live_stream_create_input'
description: >-
Provide the details of the live stream to create in the body of the
request.
required: true
responses:
'201':
description: Success
content:
application/json:
schema:
type: object
required:
- live_stream
properties:
live_stream:
$ref: '#/components/schemas/live_stream'
example:
aspect_ratio_height: 720
aspect_ratio_width: 1280
billing_mode: pay_as_you_go
broadcast_location: us_west_california
closed_caption_type: cea
connection_code: 0e15cb
connection_code_expires_at: '2020-11-30T17:16:21.956Z'
created_at: '2020-01-29T17:16:21.956Z'
delivery_method: push
delivery_protocols:
- rtmp
- rtsp
- wowz
- webrtc
description: This is my first live stream.
direct_playback_urls:
rtmp:
- name: source
url: >-
rtmp://abc123.entrypoint.video.wowza.com/app-B8P6K226/wxyz6789
- name: webrtc
output_id: dcxq5q6c
url: >-
rtmp://abc123.entrypoint.video.wowza.com/app-B8P6K226/wxyz6789_stream1
- name: V:1280x720+A:128K
output_id: 0g116zkf
url: >-
rtmp://abc123.entrypoint.video.wowza.com/app-B8P6K226/wxyz6789_stream2
- name: V:854x480+A:128K
output_id: 4qqkwndt
url: >-
rtmp://abc123.entrypoint.video.wowza.com/app-B8P6K226/wxyz6789_stream3
- name: V:640x360+A:128K
output_id: 0pv8djpg
url: >-
rtmp://abc123.entrypoint.video.wowza.com/app-B8P6K226/wxyz6789_stream4
- name: V:512x288+A:128K
output_id: b09xrxjf
url: >-
rtmp://abc123.entrypoint.video.wowza.com/app-B8P6K226/wxyz6789_stream5
- name: V:320x180+A:128K
output_id: bvkh2nsz
url: >-
rtmp://abc123.entrypoint.video.wowza.com/app-B8P6K226/wxyz6789_stream6
rtsp:
- name: source
url: >-
rtsp://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789
- name: webrtc
output_id: dcxq5q6c
url: >-
rtsp://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream1
- name: V:1280x720+A:128K
output_id: 0g116zkf
url: >-
rtsp://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream2
- name: V:854x480+A:128K
output_id: 4qqkwndt
url: >-
rtsp://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream3
- name: V:640x360+A:128K
output_id: 0pv8djpg
url: >-
rtsp://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream4
- name: V:512x288+A:128K
output_id: b09xrxjf
url: >-
rtsp://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream5
- name: V:320x180+A:128K
output_id: bvkh2nsz
url: >-
rtsp://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream6
wowz:
- name: source
url: >-
wowz://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789
- name: webrtc
output_id: dcxq5q6c
url: >-
wowz://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream1
- name: V:1280x720+A:128K
output_id: 0g116zkf
url: >-
wowz://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream2
- name: V:854x480+A:128K
output_id: 4qqkwndt
url: >-
wowz://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream3
- name: V:640x360+A:128K
output_id: 0pv8djpg
url: >-
wowz://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream4
- name: V:512x288+A:128K
output_id: b09xrxjf
url: >-
wowz://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream5
- name: V:320x180+A:128K
output_id: bvkh2nsz
url: >-
wowz://abc123.entrypoint.video.wowza.com:1935/app-B8P6K226/wxyz6789_stream6
webrtc:
- name: source
url: >-
wss://abc123.entrypoint.video.wowza.com/webrtc-session.json
application_name: app-B8P6K226
stream_name: 1722aead
- name: webrtc
output_id: dcxq5q6c
url: >-
wss://abc123.entrypoint.video.wowza.com/webrtc-session.json
application_name: app-B8P6K226
stream_name: 1722aead_stream1
- name: V:1280x720+A:128K
output_id: 0g116zkf
url: >-
wss://abc123.entrypoint.video.wowza.com/webrtc-session.json
application_name: app-B8P6K226
stream_name: 1722aead_stream2
- name: V:854x480+A:128K
output_id: 4qqkwndt
url: >-
wss://abc123.entrypoint.video.wowza.com/webrtc-session.json
application_name: app-B8P6K226
stream_name: 1722aead_stream3
- name: V:640x360+A:128K
output_id: 0pv8djpg
url: >-
wss://abc123.entrypoint.video.wowza.com/webrtc-session.json
application_name: app-B8P6K226
stream_name: 1722aead_stream4
- name: V:512x288+A:128K
output_id: b09xrxjf
url: >-
wss://abc123.entrypoint.video.wowza.com/webrtc-session.json
application_name: app-B8P6K226
stream_name: 1722aead_stream5
- name: V:320x180+A:128K
output_id: bvkh2nsz
url: >-
wss://abc123.entrypoint.video.wowza.com/webrtc-session.json
application_name: app-B8P6K226
stream_name: 1722aead_stream6
encoder: other_rtmp
flowplayer: true
hosted_page:
enabled: true
description: My Hosted Page Description
logo_image_url: >-
https://prod.s3.amazonaws.com/uploads/player/hosted_page_logo_image/23424/5bad28.jpg
sharing_icons: true
title: My Hosted Page
url: https://embed.flowplayer.com/hosted/default/e8dk5bf6
id: wdjfqvsv
name: My PAYG Transcoded WSE Live Stream
playback_stream_name: wxyz6789
player_id: 205b4e8-b160-43c2-868d-d88698a4e850
player_type: wowza_flowplayer_v2
embed_code: null
hls_playback_url: >-
https://wowzasubdomain.wowza.com/1/TWhoL3BiZnJXMFhmNzZVN3JrZDAwUT09/ZmYxSXRrTERrUlk9/hls/live/playlist.m3u8
logo_image_url: >-
https://prod.s3.amazonaws.com/uploads/player/logo_image/23424/5bad28.jpg
logo_position: top-right
video_poster_image_url: >-
https://prod.s3.amazonaws.com/uploads/player/video_poster_image/23424/5bad28.jpg
width: 640
recording: true
reference_id: mySystemID_01
save_asset: false
security:
force_ssl_playback: false
geoblock_enabled: true
geoblock_by_location: allow
geoblock_country_codes: DE, US
geoblock_ip_override: deny
geoblock_ip_addresses: 77.12.34.567, 78.23.45.678
token_auth_enabled: false
token_auth_playlist_only: false
state: stopped
stream_source_id: 5skrfpyf
stream_targets:
- id: klbmg2h8
- id: bnjtdmmc
target_delivery_protocol: hls-https
transcoder_type: transcoded
updated_at: '2020-01-31T06:12:39.956Z'
use_stream_source: true
vod_stream: true
watermark: true
watermark_height: 80
watermark_image_url: >-
https://prod.s3.amazonaws.com/uploads/transcoder/watermark_image/12345/4baa13.jpg
watermark_opacity: 75
watermark_position: top-right
watermark_width: 100
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error422'
get:
summary: Fetch all live streams
description: >-
This operation shows limited details for all of your live streams. For
detailed information, fetch a single live stream.
operationId: listLiveStreams
tags:
- live_streams
x-codeSamples:
- lang: Shell
source: |
// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
-H "Content-Type: application/json" \
-X "GET" \
"${WV_HOST}/api/v2.0/live_streams"
- lang: JavaScript
source: |
// Using Node.js
const https = require('https');
const crypto = require('crypto');
var hostname = 'api.video.wowza.com'
var path = '/api/v2.0/live_streams';
//For security, never reveal API token in client-side code
var wvJWT = 'Bearer [your JWT]';
const options = {
hostname: hostname,
path: path,
headers: {
'Authorization': wvJWT,
'Content-Type': 'application/json'
}
};
https.get(options, function(res) {
var body = '';
res.on('data', function(data){
body += data;
});
res.on('end', function() {
console.log(JSON.parse(body));
});
}).on('error', function(e) {
console.log(e.message);
});
parameters:
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/live_streams'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
/live_streams/{id}:
get:
summary: Fetch a live stream
description: This operation shows the details of a specific live stream.
operationId: showLiveStream
tags:
- live_streams
x-codeSamples:
- lang: Shell
source: |
// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
-H "Content-Type: application/json" \
-X "GET" \
"${WV_HOST}/api/v2.0/live_streams/2adffc17"
- lang: JavaScript
source: |
// Using Node.js
const https = require('https');
const crypto = require('crypto');
var hostname = 'api.video.wowza.com'
var path = '/api/v2.0/live_streams/2adffc17';
//For security, never reveal API token in client-side code
var wvJWT = 'Bearer [your JWT]';
const options = {
hostname: hostname,
path: path,
headers: {
'Authorization': wvJWT,
'Content-Type': 'application/json'
}
};
https.get(options, function(res) {
var body = '';
res.on('data', function(data){
body += data;
});
res.on('end', function() {
console.log(JSON.parse(body));
});
}).on('error', function(e) {
console.log(e.message);
});
pa
# --- truncated at 32 KB (1867 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wowza/refs/heads/main/openapi/wowza-video-openapi.yml