Organize videos using categories in Wowza Video using the Wowza Video REST API

Categories and subcategories in Wowza Video help organize and manage your video content more efficiently. For example, create a comedy category with slapstick, standup, and dry humor subcategories your viewers can choose from. Once created, use them to add as metadata to videos.

This article demonstrates:

  • Creating a new category or subcategory.
  • Uploading a video and adding the subcategory.
  • Updating the subcategory of an existing video in Wowza Video.
Info

This topic only applies to version 2.0 and later of the REST API.

Before you start

  • API authentication methods - We use JSON web tokens for API authentication. See Authentication for more information.
  • Environment variables - We use environment variables for the API version and your JWT in the cURL API request examples in this topic to make it easier for you to copy, paste, and run commands in your Terminal or Command Prompt window. If you don't set environment variables for these values, you'll need to manually enter the correct values in the code samples throughout this tutorial. See Tools for testing the API for instructions.

Create a category or subcategory in Wowza Video

To create a category or subcategory, send a POST request to the /categories endpoint.

You can use the following sample request, making sure to:

  • Set the name of the category.
  • Set the description of the category.
  • If you are creating:
    • A subcategory, set parent_id to the identifier of the parent category. You can fetch the category IDs by calling the GET /categories endpoint. The response includes all the categories present for an organization. Choose the category you want as the parent and use its ID as the parent_id .
    • A new category at the top level can either be set with parent_id as an empty string (““) or no parent_id included in the body.

Sample request
Endpoint Reference

Copy
Copied
curl -X POST \ 
-H "Content-Type: application/json" \ 
-H "Authorization: Bearer ${WV_JWT}" \ 
-d '{ 
      "category": { 
        "name": "My Category", 
        "description": "A description of my category"
      }
}' "${WV_HOST}/api/${WV_VERSION}/categories"

Sample response

The response includes:

  • An id for the category that you'll use to categorize your videos.
  • The parent_id which is the category ID of the top-level category.
Copy
Copied
{
  "category": { 
    "id": "e7a9d8a1-9e1a-4b2b-9c59-8f0c9a5a5c1b", 
    "name": "My Category", 
    "description": "A description of my category"
  } 
}

Add a category to a video in Wowza Video

Once you've created a category, you can use the id from the response to categorize your videos by:

  • Passing the category id that you obtained during video creation.
  • Or, through an update video request.

Upload a video and assign a category in Wowza Video

Upload a video to Wowza Video by sending a POST request to the videos endpoint and set the category_id to the identifier of the category you want the video to be assigned to.

In Wowza Video REST API 2.0 version, you can upload a video in two ways:

  • DIRECT – A video is uploaded from your local storage using the upload_url parameter.
  • FETCH – A video is fetched from external storage through a URL specified in the request, and a copy is made in Wowza Video.

Here, we’ll upload a video from external storage. Send a POST request to the /videos endpoint with the video’s URL to create a copy of the video in Wowza Video.

You can use the following sample request, making sure to:

  • Specify FETCH for the input or upload method. Wowza Video will fetch the video from the external storage URL you specify and then create a copy of the video in Wowza Video.
  • Set category_id to the identifier of the category you want the uploaded video to be assigned to.
  • Set any other information you'd like to, like the video name and description. You can always set these values later using PATCH /video/{id} .

Sample request
Endpoint Reference

Copy
Copied
curl -X POST \ 
-H "Content-Type: application/json" \ 
-H "Authorization: Bearer ${WV_JWT}" \ 
-d '{ 
      "video": { 
        "input": { 
          "method": "FETCH", 
          "fetch_url": "https://storage.googleapis.com/myorg/test_files/myvideo.mp4" 
        }, 
        "name":"My video" 

        "category_id": "1c789ff7-0f73-4bc9-b253-5b3f1dd2b78e", 
      } 
}' "${WV_HOST}/api/${WV_VERSION}/videos"

Sample response

The response includes:

  • An id for the video that you'll use to complete other actions on the video.
  • The category_id of the category you want the video to be assigned to.
  • Information like the video name and description you sent in the request.
Copy
Copied
{ 
    "video": { 
        "id": "96ba1709-7367-4e33-b34f-66a364d5e2e8", 
        "name": "My video", 
        "description": "", 
        "duration_in_ms": 0, 
        "unpublish": true, 
        "unpublished_at": "2025-01-01T12:33:22+0000", 
        "published": false, 
        "published_at": "2024-01-01T12:33:22+0000", 
        "tags": [ 
            "bar", 
            "foo"
        ],
        "remote": false,
        "category_id": "1c789ff7-0f73-4bc9-b253-5b3f1dd2b78e",
        "no_ads": true,
        "ad_keywords": "",
        "created_at": "2024-10-25T04:09:26+0000",
        "updated_at": "2024-10-25T04:09:26+0000",
        "state": "UPLOADING",
        "encoding_progress": 0.0,
        "upload_progress": 0.0,
        "error_message": "",
        "deactivated": false,
        "images": [
            {
                "type": "image_0",
                "url": "https://wv-cdn-00-00.flowplayer.com/7bb18344-08f9-4c1e-84a7-80c1007aa99b/i/v-i-96ba1709-7367-4e33-b34f-66a364d5e2e8-0.jpg"
            },
            {
                "type": "image_1",
                "url": "https://wv-cdn-00-00.flowplayer.com/7bb18344-08f9-4c1e-84a7-80c1007aa99b/i/v-i-96ba1709-7367-4e33-b34f-66a364d5e2e8-1.jpg"
            },
            {
                "type": "image_2",
                "url": "https://wv-cdn-00-00.flowplayer.com/7bb18344-08f9-4c1e-84a7-80c1007aa99b/i/v-i-96ba1709-7367-4e33-b34f-66a364d5e2e8-2.jpg"
            },
                   ],
        "encodings": [],
        "shallow_copy": false,
        "multiple_audio_tracks": false,
        "audio_only": false,
        "version": 1,
           }
}

For more information on how to upload a video with the Wowza Video REST API, see Upload a video from local storage and Upload a video from external storage.

Update a video’s metadata by assigning a category in Wowza Video

To update an existing video by assigning a category, send a PATCH request to the videos/id endpoint.

You can use the following sample request, making sure to:

  • Add the id of the video you want to update as a path parameter.
  • Set category_id to the id of the category you want the video to be assigned to.

Sample request
Endpoint Reference

Copy
Copied
curl -X PATCH \ 
-H "Content-Type: application/json" \ 
-H "Authorization: Bearer ${WV_JWT}" \ 
-d '{ 
     "name": "My video", 
     "description": "A new video for my business.", 
     "unpublish": true, 
     "unpublished_at": "2025-01-01T12:33:22Z", 
     "published": true, 
     "published_at": "2024-01-01T12:33:22Z", 
     "tags": [ 
       "foo", 
       "bar" 
     ], 
     "category_id": "e7a9d8a1-9e1a-4b2b-9c59-8f0c9a5a5c1b", 
     "no_ads": true, 
     "ad_keywords": "" 
}' "${WV_HOST}/api/${WV_VERSION}/categories/2aa3343e-2fb5-42c3-8671-b52c24b7c3e2"

The response includes:

  • category_id , identifier of the category to which you assigned the video.

Sample response

Copy
Copied
{ 

  "video": { 
    "id": "2aa3343e-2fb5-42c3-8671-b52c24b7c3e2", 
    "name": "My video", 
    "description": "A new video for my business.", 
    "duration_in_ms": 0, 
    "unpublish": true, 
    "unpublished_at": "2025-01-01T12:33:22Z", 
    "published": true, 
    "published_at": "2024-01-01T12:33:22Z",
    "tags": [
      "foo",
      "bar"
    ],
    "category_id": "e7a9d8a1-9e1a-4b2b-9c59-8f0c9a5a5c1b",
    "no_ads": true,
    "ad_keywords": "",
    "created_at": "2024-01-01T12:33:22Z",
    "updated_at": "2024-01-01T12:33:22Z",
    "state": "FINISHED",
    "encoding_progress": 0,
    "upload_progress": 0,
    "error_message": "string",
    "deactivated": false,
    "images": [
      {
        "type": "thumbnail",
        "url": "https://example.com/image.jpg"
      }
    ],
    "encodings": [
      {
        "audio_bitrate_in_kbps": 2300,
        "audio_channel": 2,
        "audio_codec": "aac",
        "audio_sample_rate": 44100,
        "height": 1080,
        "width": 1920,
        "video_file_url": "https://flowplayer.com/video.mp4",
        "video_container": "mp4",
        "video_codec": "h264",
        "total_bitrate_in_kbps": 1023,
        "created_at": "2019-08-24T14:15:22Z",
        "size_in_bytes": 8325555
      }
    ],
    "drm": {
      "com.widevine.alpha": {
        "license_server": "string",
        "certificate": "string"
      },
      "com.apple.fps.1_0": {
        "license_server": "string",
        "certificate": "string"
      },
      "com.microsoft.playready": {
        "license_server": "string",
        "certificate": "string"
      }
    },
    "shallow_copy": true,
    "shallow_copy_source_id": "string",
    "multiple_audio_tracks": true,
    "audio_only": true,
    "version": 0,
    "thumbnails": {
      "src": "string"
    },
    "animated_previews": [
      {
        "url": "string",
        "type": "string",
        "height": 1080,
        "width": 1920
      }
    ],
    "origin": {
      "id": "wqrs0k75",
      "type": "live_stream",
      "uptime_id": "hvpcp3kn"
    }
  }
}

Related API requests

© 2007-2025 Wowza Media Systems, ™ LLC. All rights reserved.   Security & Privacy Policy | Legal | System Status