# 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](/docs/wowza-video/about-the-rest-api/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](/docs/wowza-video/about-the-rest-api/api-overview#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 ```json 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. ```json { "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 ```json 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. ```json { "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](https://developer.wowza.com/docs/wowza-video/guides/videos/upload-a-video-external/). ### 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 ```json 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** ```json { "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 - GET /categories - Fetches details for all categories available in an account. - GET /categories/{id} - Fetches details for a specific category. - DELETE /categories/{id} - Deletes a category.