Wowza Streaming Cloud REST API Reference Documentation (v1.5)

Download OpenAPI specification:Download

License: Terms of Use


  The current version is stable and suitable for production environments.


About the REST API


The Wowza Streaming CloudTM REST API allows you to add live streaming and playback functionality to your applications. It offers complete programmatic control over live streams, transcoders, stream sources, and stream targets. Anything you can do in the Wowza Streaming Cloud UI can also be achieved by making HTTP-based requests to cloud-based servers through the REST API.

CORS

The Wowza Streaming Cloud REST API features cross-origin resource sharing, or CORS.

CORS is a W3C specification that provides headers in HTTP requests to enable a web server to safely make a network request to another domain.

Limits

In order to protect shared resources, the Wowza Streaming Cloud REST API is subject to limits. For details, see Wowza Streaming Cloud REST API limits.

Versions

The Wowza Streaming Cloud REST API is periodically versioned. Minor updates are iterated using sequential dot numbers; major versions are iterated using sequential whole numbers. For details, see the Wowza Streaming Cloud REST API deprecation policy.

Each version is one of these types:

  • Beta: The beta version contains everything that's in the current version as well as some features and functionality that are still in development. These work-in-progress features aren't fully tested and are subject to change. When we're done testing, we'll promote the beta version to the current version and then create a new beta with new features. You're free to use the beta version for testing and evaluation, but beta versions aren't intended for use in production environments and we caution against using a beta in production. There is only one beta version available at any time.
  • Current: The current version offers the most complete, up-to-date, tested, and stable code base. We strongly recommend using the current version in your production environment. There is only one current version available at any time.
  • Supported: A supported version was current at one time but has been replaced by a newer version of the API. Supported versions don't have the newest features, and may contain features or functions that are outdated and don't offer the most efficient methods for accomplishing your streaming goals. If you're using a supported version, we recommend that you upgrade to the current version, as supported versions will ultimately be deprecated.
  • Deprecated: A deprecated version is out-of-date and isn't guaranteed to work in production environments. If you're using a deprecated version, update to the current version at your earliest convenience.
  • Sunset: A sunset version is no longer accessible. This includes all relevant documentation.

Query for version status

You can use the following GET request to fetch the current status for versions of the REST API.


curl -X GET \

-H 'wsc-api-key: ${WSC_API_KEY}' \

-H 'wsc-access-key: ${WSC_ACCESS_KEY}' \

'https://api.cloud.wowza.com/api/versions'

The response should look something like this, but it will differ according to current version status. Note that the beta version is not included in the response.


{
  "1.5": {
    "status": "current",
    "base_uri": "/api/v1.5"
     },
    "1.4": {
        "status": "supported",
        "base_uri": "/api/v1.4"
    }
    ...
}

Documentation


Reference doc

This reference documentation provides details about the operations, parameters, and request and reponse schemas for every resource and endpoint in the Wowza Streaming Cloud 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.

Release notes

Release notes are also available for each version. Release notes detail additions, changes, and deletions for each version. To learn more, see Wowza Streaming Cloud REST API release notes.

Technical articles

For additional documentation, including more detailed examples on using the Wowza Streaming Cloud REST API, see our library of Wowza Streaming Cloud REST API technical articles.

Query requirements


The Wowza Streaming Cloud REST API uses HTTP requests to retrieve data from cloud-based servers. Requests must contain proper JSON, three authentication keys, and the correct version number as the base path.

Use JSON

The Wowza Streaming Cloud REST API uses the JSON API specification to request and return data. This means requests must include the header Content-Type: application/json and must include a single resource object in JSON format as primary data.

Responses include HTTP status codes that indicate whether the query was successful. If there was an error, a description explains the problem so that you can fix it and try again.

Authenticate

Requests to the Wowza Streaming Cloud REST API must include headers for authentication.

For production environments, use the more secure HMAC method of authentication. Headers for HMAC include an access key, a timestamp, and a signature generated using the HMAC-256-Hexdigest algorithm.

For HMAC authentication, use the wsc-access-key, wsc-timestamp, and wsc-signature headers to authenticate requests, like this (in cURL):


curl -H 'wsc-access-key: [64-character-access-key]' \
     -H 'wsc-timestamp: [Unix-epoch-timestamp]' \
     -H 'wsc-signature: [signature-generated-from-HMAC-256-Hexdigest-algorithm]'

For initial testing only, you may use your API key and access key as authentication headers. Each key is a 64-character alphanumeric string that you can find on the API Access page in Wowza Streaming Cloud.

For API key and access key authentication, use the wsc-api-key and wsc-access-key headers to authenticate requests, like this (in cURL):


curl -H 'wsc-api-key: [64-character-api-key]' \
     -H 'wsc-access-key: [64-character-access-key]'

See Authentication for more detailed information about authenticating API requests.

Specify a version

You must specify the version of the Wowza Streaming Cloud REST API you're using for the base path of your request. Use the version number or beta, as in


https://api.cloud.wowza.com/api/v1.5/live_streams

or


https://api.cloud.wowza.com/api/beta/live_streams

Example query

Here is a complete example POST request, in cURL, with proper JSON syntax, headers, HMAC authentication, and version information:


curl -X POST \

-H 'wsc-access-key: [64-character-access-key]' \

-H 'wsc-timestamp: [timestamp]' \

-H 'wsc-signature: [generated-signature]' \

-H 'Content-Type: application/json' \

-d '{
    "live_stream": {
      "name": "My live Stream",
      "...": "..."
    }
  }' 'https://api.cloud.wowza.com/api/[version]/live_streams'

Authentication

wsc-api-key

Your account's secret 64-digit, alphanumeric API key. Used with API key and access key authentication for initial testing only. Used with the HMAC method of authentication to generate a signature value.

Security Scheme Type API Key
Header parameter name: wsc-api-key

wsc-access-key

A valid 64-digit, alphanumeric API access key. Used with both authentication methods.

Security Scheme Type API Key
Header parameter name: wsc-access-key

wsc-timestamp

A Unix epoch timestamp. The timestamp must be within 15 seconds of the time the server receives the request, otherwise the request will not authenticate. Used with the HMAC method of authentication.

Security Scheme Type API Key
Header parameter name: wsc-timestamp

wsc-signature

A hex string that is HMAC-encoded with SHA256 digest. Used with the HMAC method of authentication.

Security Scheme Type API Key
Header parameter name: wsc-signature
➔ Next to Live Streams