Applies to: Wowza Video REST API v2.0 (current) and v1.x (legacy)
The Wowza Video REST API lets you build live streaming and playback functionality into your applications with complete programmatic control over live streams, transcoders, stream sources, and stream targets. This article covers the fundamentals: how to format HTTP requests, authenticate with a JSON Web Token (JWT), understand API versioning, and test calls with cURL or a GUI client.
The Wowza Video REST API uses Hypertext Transfer Protocol (HTTP) to request data from Wowza Video servers through calls to API endpoints. Anything you can do in the Wowza Video UI can also be achieved by making HTTP requests to cloud-based servers through the REST API: live streams, transcoders, stream sources, and stream targets.
Requests in the Wowza Video REST API use JSON (JavaScript Object Notation) syntax for the request body and response. The examples throughout this documentation use cURL commands executed in a terminal or command prompt. For cURL setup instructions and alternatives, see Testing the Wowza Video REST API with cURL and GUI clients.
cURL commands use the following general format:
cURL command: general syntax for Wowza Video REST API requests
curl -[HTTP method] --[headers] -[parameters] "[resource]"HTTP method is the action you're requesting of the resource. Wowza Video uses these HTTP methods:
| HTTP method | Description |
|---|---|
| POST | Creates records in the resource's database. Returns a response confirming success and the values of any newly created records. |
| GET | Retrieves records from the resource's database. Returns detailed information about the queried object or objects. Some endpoints return a cached response for duplicate GET requests within a specified period. See Wowza Video REST API server response caching for details. |
| PATCH | Updates records in the resource's database. Certain attributes can't be updated in a PATCH request and must be defined in the initial POST request. Returns a response confirming success and the values of updated records. |
| PUT | Starts or stops an entity such as a live stream or transcoder. Returns information about the affected entity. |
| DELETE | Removes the record from the resource's database. Returns a response with no content. |
Headers are key:value pairs that precede the HTTP request body.
| Key | Value | Where used |
|---|---|---|
| Authorization | Bearer [your JWT]. Authenticates the request. See Wowza Video REST API authentication. | All requests |
| Content-Type | application/json. Specifies that the request body is JSON-formatted. | POST and PATCH requests only |
Parameters refine the request and correspond to options in the Wowza Video UI. In JSON syntax, define a value for each parameter in key:value pairs.
JSON: example parameters object for POST /transcoders (API v1.11)
{
"transcoder": {
"billing_mode": "pay_as_you_go",
"broadcast_location": "us_central_iowa",
"delivery_method": "push",
"name": "MyPassthruTranscoder",
"protocol": "rtmp",
"transcoder_type": "passthrough"
}
}Resource, or base URL, is the location of the server receiving the request:
https://api.video.wowza.com/api/[version]/
cURL request: full example POST /transcoders (API v1.11)
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
"transcoder": {
"billing_mode": "pay_as_you_go",
"broadcast_location": "us_central_iowa",
"delivery_method": "push",
"name": "MyPassthruTranscoder",
"protocol": "rtmp",
"transcoder_type": "passthrough"
}
}' "https://api.video.wowza.com/api/v1.11/transcoders"The Wowza Video REST API publishing and playback endpoints use dynamic IP addresses. Wowza cannot provide IP addresses for allowlisting from behind a firewall.
The Wowza Video REST API is periodically versioned. Minor updates use sequential dot numbers; major versions use sequential whole numbers. To learn more about the API lifecycle and what to expect at each stage (beta, current, deprecated), see Wowza Video REST API lifecycle management.
- See the Wowza Video REST API deprecation policy for the deprecation schedule and timeline.
- See Wowza Video REST API release notes for a detailed changelog of updates to each version.
The Wowza Video REST API supports cross-origin resource sharing (CORS), a World Wide Web Consortium (W3C) specification that adds HTTP response headers enabling a web server to safely accept requests from a different domain.
Resource limits are in place to prevent excessive usage of streams and stream targets. See Wowza Video REST API limits for details.
For limitations specific to the Wowza Video free trial, see Wowza Video free trial limitations.
All requests to the Wowza Video REST API must include authentication information in the header. Wowza Video uses JSON Web Token (JWT)-based authentication, an open standard (RFC 7519) for securely transmitting information in JSON format. Generate an access token in the Token Management portal and include it in the Authorization header of each request. See Wowza Video REST API authentication for step-by-step instructions on creating and using JWT access tokens.
The Wowza Video REST API documentation examples use cURL commands. cURL is a command-line tool for executing HTTP requests. It is built into the Terminal on macOS and Linux. On Windows, installation is required; see the cURL Download Wizard for a Windows download.
For a reference of cURL command syntax, see How to format a Wowza Video REST API request.
This documentation uses environment variables in cURL examples so you can copy, paste, and run commands without manually substituting values each time. Variable syntax differs by operating system:
| Description | macOS/Linux variable (used in examples) | Windows variable |
|---|---|---|
| JSON Web Token | ${WV_JWT} | %WV_JWT% |
| Host | ${WV_HOST} | %WV_HOST% |
| API version | ${WV_VERSION} | %WV_VERSION% |
Set the environment variables for your operating system before running examples:
Shell: set Wowza Video API environment variables (macOS/Linux)
export WV_JWT="your token here"
export WV_HOST="https://api.video.wowza.com"
export WV_VERSION="v2.0"Shell: set Wowza Video API environment variables (Windows)
set WV_JWT=your token here
set WV_HOST=https://api.video.wowza.com
set WV_VERSION=v2.0After setting the environment variables, copy and paste API request examples directly into your terminal or command prompt. You'll still need to substitute resource IDs and update parameter values where appropriate.
Postman, Paw, and Insomnia are graphical user interface (GUI)-based REST API clients that display responses in formatted JSON. For installation and usage, refer to the documentation for your chosen client.
Configure your client with these settings:
| Setting | Value |
|---|---|
| Authorization | No Auth |
| Headers | Authorization: Bearer [your JWT], Content-Type: application/json |
| Body | JSON-formatted request body with parameters and their assigned values |
Example POST request configuration in a GUI-based REST API client:
| Headers |
|---|
 |
| Body |
|---|
 |
Browse the Wowza Video REST API community forum for answers from other users and Wowza experts.
To open a support ticket, contact Wowza Support. When reporting an API error, include the following information:
- The API request that caused the error
- The
request_idfrom the error response - The
request_timestampfrom the error response
JSON response: example 401 error with request_id and request_timestamp
{
"meta": {
"status": 401,
"code": "ERR-401-InvalidSignature",
"title": "Invalid Signature Error",
"message": "Invalid signature.",
"description": ""
},
"request_id": "12a6c19ad7fa49dc9126e6ce6c7ca9d7",
"request_timestamp": "2019-11-04T15:38:47.198Z"
}