Category Requests

Warning: The Category REST API is currently on version 0, which means it has not been finalised yet and may still change significantly.

Categories in Pulse are used to organise your video content in a tree structure, by creating categories and subcategories. This means there is one root node representing your whole account, and multiple branch or leaf nodes coming out of it and representing the multiple account categories. Each category can also have multiple subcategories. Categories are used for reporting and targeting purposes, but you can also target insertion policies against categories, this way controlling how many and what type of ads are returned.

Getting Started

  • Base URL: https://api.videoplaza.com/v0/categories.
  • Requests: GET requests are used. You pass parameters by using common REST parameters like PATH, as well as HTTP HEADERS. The body of the requests should be provided in JSON format and encoded using UTF-8.
  • Responses: All responses contain an HTTP status code in the header and the body is in JSON format.
  • Swagger documentation: Category API
  • Related user documentation:
The Category API allows you to:
Note: Only successful responses are shown in the examples. Details about unsuccessful responses are found in the swagger documentation.

List All Categories

Method GET
URL https://api.videoplaza.com/v0/categories
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body:

[
    {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "enabled": "<boolean>",
        "aliases": [
            "<string>",
            "<string>"
        ],
        "parents": [
            "<string>",
            "<string>"
        ]
    },
    {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "enabled": "<boolean>",
        "aliases": [
            "<string>",
            "<string>"
        ],
        "parents": [
            "<string>",
            "<string>"
        ]
    }
]

Example

Request header:

GET /v0/categories HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

[
    {
        "id": "c3368339-d184-4265-b04e-21fef69e92d2",
        "name": "Basketball",
        "enabled": true,
        "parents": [
            "ae823a6e-8818-4f96-a4ef-b9c9204d88c0",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "07796065-6833-448d-8308-35623bdfeda4",
        "name": "Dancing with the Stars",
        "enabled": true,
        "parents": [
            "9c039f86-4eba-42d3-b3ad-8336fea843a8",
            "43c4646e-496d-43df-b894-16a74339bc0a",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "9ef4d7fc-0473-48f5-a5ce-b64e555e497b",
        "name": "DocsTV",
        "enabled": true,
        "parents": []
    },
    {
        "id": "43c4646e-496d-43df-b894-16a74339bc0a",
        "name": "Entertainment",
        "description": "All entertainment content.",
        "enabled": true,
        "aliases": [
            "entertainment"
        ],
        "parents": [
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "0e34a70d-c467-4a70-9d7a-555c686d7718",
        "name": "Evening news",
        "enabled": true,
        "parents": [
            "d1caaa01-ca17-43d1-b0a5-adfdd06a72e0",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "00fe90dd-86f0-43f3-b383-207bb8a50eab",
        "name": "Football",
        "enabled": true,
        "parents": [
            "ae823a6e-8818-4f96-a4ef-b9c9204d88c0",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "1aad19e9-81b3-4c62-b3cf-4a660edc424c",
        "name": "Game of Thrones",
        "enabled": true,
        "parents": [
            "35edb3f1-536a-4b18-a5ab-264d581fb121",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "30768655-d9af-4714-9bb5-e2d1cceb0162",
        "name": "Hockey",
        "enabled": true,
        "parents": [
            "ae823a6e-8818-4f96-a4ef-b9c9204d88c0",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "ea8350c3-92b5-4cf4-8a4a-00e2e6de39b8",
        "name": "Idol",
        "enabled": true,
        "parents": [
            "43c4646e-496d-43df-b894-16a74339bc0a",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "58157696-8e87-4671-80df-69a22f92a76a",
        "name": "Kids TV",
        "enabled": true,
        "parents": [
            "43c4646e-496d-43df-b894-16a74339bc0a",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "fcbf28c0-9499-4544-9f9f-636cf8bb2d09",
        "name": "Morning news",
        "enabled": true,
        "parents": [
            "d1caaa01-ca17-43d1-b0a5-adfdd06a72e0",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "d1caaa01-ca17-43d1-b0a5-adfdd06a72e0",
        "name": "News",
        "description": "All daily news content.",
        "enabled": true,
        "aliases": [
            "news",
            "news*"
        ],
        "parents": [
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "9c039f86-4eba-42d3-b3ad-8336fea843a8",
        "name": "Reality shows",
        "enabled": true,
        "parents": [
            "43c4646e-496d-43df-b894-16a74339bc0a",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "ae823a6e-8818-4f96-a4ef-b9c9204d88c0",
        "name": "Sport",
        "enabled": true,
        "aliases": [
            "sport",
            "sport*"
        ],
        "parents": [
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "44452a41-da2d-4616-9d67-f009ec2c65c3",
        "name": "Sport-Live",
        "description": "All live sport events.",
        "enabled": true,
        "aliases": [
            "live",
            "live*",
            "sport-live",
            "sport-live*"
        ],
        "parents": [
            "ae823a6e-8818-4f96-a4ef-b9c9204d88c0",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "35edb3f1-536a-4b18-a5ab-264d581fb121",
        "name": "TV shows",
        "enabled": true,
        "parents": [
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "482dc533-3c46-4855-b2d9-394354845874",
        "name": "The Bachelorette",
        "enabled": true,
        "parents": [
            "9c039f86-4eba-42d3-b3ad-8336fea843a8",
            "43c4646e-496d-43df-b894-16a74339bc0a",
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    },
    {
        "id": "6b23a9f9-66a5-4408-86ea-60477cfea99f",
        "name": "Unassigned",
        "enabled": true,
        "parents": [
            "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
        ]
    }
]

Get Category by Category ID

Method GET
URL https://api.videoplaza.com/v0/categories/{id)
Header Authentication header (x-o-api-key)
Content type application/json
URL params Category ID
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body:

{
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "enabled": "<boolean>",
    "aliases": [
        "<string>",
        "<string>"
    ],
    "parents": [
        "<string>",
        "<string>"
    ]
}

Example

Request header:

GET /v0/categories/44452a41-da2d-4616-9d67-f009ec2c65c3 HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

{
    "id": "44452a41-da2d-4616-9d67-f009ec2c65c3",
    "name": "Sport-Live",
    "description": "All live sport events.",
    "enabled": true,
    "aliases": [
        "sport-live",
        "sport-live*",
        "live*",
        "live"
    ],
    "parents": [
        "ae823a6e-8818-4f96-a4ef-b9c9204d88c0",
        "9ef4d7fc-0473-48f5-a5ce-b64e555e497b"
    ]
}

Was this article helpful?