Get started querying a live stream using the Wowza Streaming Cloud REST API

Learn how to use the Wowza Streaming Cloud™ service's REST API to gather information about an existing live stream and its associated player, to update the live stream and player, and to delete the live stream. 

Note: For information on the Wowza Streaming Cloud free trial and its feature limitations, see Wowza Streaming Cloud free trial.

Start the live stream


Before using the Wowza Streaming Cloud REST API to query and update a live stream, create and start a live stream with the user interface. 

  1. If you haven't already added a live stream, see Get started with Wowza Streaming Cloud to learn how to add one. 
  2. To start the live stream in Wowza Streaming Cloud, select the stream on the Live Streams page, and then click Start Live Stream at the top of the live stream detail page.

Prepare authentication for your request


Note: The Wowza Streaming Cloud REST API uses hash-based message authentication code (HMAC) for secure authentication in production environments. In this form of authentication, the API key is a private, secret key. It is known to you and the Wowza Streaming Cloud service but never sent directly in an API request. To learn more, see HMAC Authentication.

For initial Wowza Streaming Cloud REST API testing only, you can use API key and access key authentication.

Both the API key and the access key can be found in the Wowza Streaming Cloud user interface.

  1. In the menu bar, click your user name and choose API Access.

Your API key appears in the middle of the Wowza Streaming Cloud REST API page.
Access keys are listed in the Access Keys panel on the left side of the page.

  1. To generate a new access key, click Add Access Key.
  2. Leave Enabled selected so that the key is immediately available, and provide an optional Description. Then, click Add.

Wowza Streaming Cloud generates the key.

You can disable and re-enable the access key at any time, and edit the description.

Query for information about the live stream


Now that you have your API key and access key and a live stream that's started, use the following example requests to find information about the live stream. Example requests are presented in curl using environment variables, but you can also use a GUI REST client for API testing such as Postman or Paw.

If you have basic questions about using a REST API, start with About the Wowza Streaming Cloud REST API.

Notes:

  • Query for all live streams in your account to find the details of your existing live stream. You'll need the ID of your live stream and the ID of the player to do additional requests.

    Fetch all live streams:
    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams"
  • View a live stream's state:

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/state"

    Possible live stream states are starting, stopping, started, stopped, and resetting.

  • View the details of a running live stream:

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/stats"
  • View a live stream's preview image:

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/thumbnail_url"

Update the live stream


Use the following example request to update the name of the live stream. You don't have to stop the live stream to update its configuration.

  • Update a live stream's configuration:

    curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    -d '{
       "live_stream": {
         "name": "MyDifferentLiveStreamName"
       }
    }' "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]"

Query for information about the player


Use the following example requests to find information about the player associated with the live stream. 

  • Get the details of a player:

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "${WSC_HOST}/api/${WSC_VERSION}/players/[player_id]"
  • View a player's state:

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "${WSC_HOST}/api/${WSC_VERSION}/players/[player_id]/state"

    Possible player states are requested and activated.

Update the player


Use the following example request to update the player associated with the live stream by giving it a specific width instead of being responsive. You don't have to stop the live stream to update the player configuration.

  • Update a player:

    curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    -d '{
       "player": {
         "width": "800",
         "responsive": false
       }
    }' "${WSC_HOST}/api/${WSC_VERSION}/players/[player_id]"

View data and health metrics for a live stream


You can use the Wowza Streaming Cloud REST API to view stream health metrics, usage, and viewer data for a live stream. See these articles for more information:

Delete the live stream


When you are done viewing information about a live stream, you can stop it and delete it.

  • Stop the live stream:

    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/stop"
  • Delete the live stream:

    curl -X DELETE \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]"

More resources