Categories API

Use categories and groups to organize streams in playlists and the web interface, and to control which streams a user can watch. A category contains an ordered list of groups, such as News and Movies in Genre. A stream can belong to at most one group in each category.

All category and group changes use the set-category command. See How to call API methods for authentication and custom control paths.

Get categories

Use the load command to read the configuration and look at its categories array. The order in this array is the display order.

admin gets the running configuration; observer gets the saved copy without sensitive fields. Details.

POST/control/

admin, observer

Request body

{ "cmd": "load" }

ResponseHTTP 200

The response is the configuration object itself. Example, showing only categories:

{
    "categories": [
        {
            "name": "Genre",
            "groups": [
                { "name": "News" },
                { "name": "Movies" }
            ]
        },
        {
            "name": "Language",
            "groups": [
                { "name": "ENG" },
                { "name": "RUS" }
            ]
        }
    ]
}

The request id is the category’s array index, starting at 0. In the example, Genre has id: 0 and Language has id: 1. Streams and user settings reference categories by name.

Read the current list before editing: removing a category shifts the indexes after it. An outdated index may select a different category or return category not found.

Add a category with groups

Create Genre with two groups. The category name must be unique. Send the name and groups without id. Assign streams separately.

POST/control/

admin

Request body

{
    "cmd": "set-category",
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "News" },
            { "name": "Movies" }
        ]
    }
}

ResponseHTTP 200

{ "set-category": "ok" }

The category is added to the end of categories.

Update a category

Send its current id and the complete category object. Use this for the category name and for all group changes below.

Caution

An update replaces the category object. Always include the groups you want to keep. Omitting groups clears the list and removes stream assignments to its defined groups.

Groups are matched by position: changing a name renames the group at that position. To change only the display order, use reorder.

Rename a category

Rename Genre (id: 0) to Content and keep its groups. See Version compatibility for differences in older versions.

POST/control/

admin

Request body

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Content",
        "groups": [
            { "name": "News" },
            { "name": "Movies" }
        ]
    }
}

ResponseHTTP 200

{
    "set-category": "ok",
    "streams": [{ "id": "a001", "name": "Channel 1" }]
}

Stream assignments and references in settings.playlist_arrange, users[*].packages and users[*].interface.arrange move to Content. The response lists the changed stream a001.

Add a group

Append Sport to Genre (id: 0). New groups go at the end to keep existing positions. To place it elsewhere, use reorder.

POST/control/

admin

Request body

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "News" },
            { "name": "Movies" },
            { "name": "Sport" }
        ]
    }
}

ResponseHTTP 200

{ "set-category": "ok" }

The group is added. No streams change.

Rename a group

Rename News in Genre (id: 0) to Headlines:

POST/control/

admin

Request body

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "Headlines" },
            { "name": "Movies" }
        ]
    }
}

ResponseHTTP 200

{
    "set-category": "ok",
    "streams": [{ "id": "a001", "name": "Channel 1" }]
}

Streams in News move to Headlines. The response lists the changed stream a001.

Remove a group

Remove Movies from Genre (id: 0) with a marker at its position:

POST/control/

admin

Request body

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "News" },
            { "remove": true },
            { "name": "Sport" }
        ]
    }
}

ResponseHTTP 200

{
    "set-category": "ok",
    "streams": [{ "id": "a001", "name": "Channel 1" }]
}

Streams in Movies lose their Genre assignment. The response lists the changed stream a001.

Sending just News, Sport in this example would rename Movies to Sport and remove assignments to the original third group. The marker keeps the later groups at their original positions while the update is applied.

To remove the last group, omit its entry. To remove all groups, send "groups": []. Removing an assignment preserves the stream itself.

Reorder groups

Move Sport to the front of Genre (id: 0). Keep category.groups in its stored order and put the new order in reorder:

POST/control/

adminSince 260922

Request body

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "News" },
            { "name": "Movies" },
            { "name": "Sport" }
        ]
    },
    "reorder": [
        "Sport",
        "News",
        "Movies"
    ]
}

ResponseHTTP 200

{ "set-category": "ok" }

Only the group order changes. Stream assignments stay the same.

reorder must contain every submitted group name exactly once.

Remove a category

Remove Genre (id: 0). The streams themselves are kept:

POST/control/

admin

Request body

{
    "cmd": "set-category",
    "id": 0,
    "category": { "remove": true }
}

ResponseHTTP 200

{
    "set-category": "ok",
    "streams": [{ "id": "a001", "name": "Channel 1" }]
}

The category, stream assignments to it and references in settings.playlist_arrange, users[*].packages and users[*].interface.arrange are removed. The response lists the changed stream a001. Categories after it move up by one index.

Remove a category used in user packages

A user’s packages list contains category names. An empty list allows access to every stream. If removing the category would empty a user’s package list, the request is rejected:

POST/control/

admin

Request body

{
    "cmd": "set-category",
    "id": 0,
    "category": { "remove": true }
}

ResponseHTTP 200

{
    "set-category": "er",
    "error": "package list would be left empty",
    "users": ["operator"]
}

Nothing is changed.

Update the listed users’ packages before retrying, or, if unrestricted access is intended, repeat the removal with force at the top level:

POST/control/

admin

Request body

{
    "cmd": "set-category",
    "id": 0,
    "category": { "remove": true },
    "force": true
}

ResponseHTTP 200

{
    "set-category": "ok",
    "users": ["operator"]
}

The category is removed. User operator now has "packages": [] and can watch every stream.

Assign a stream to a group

Assignments are stored in the stream’s groups field, which maps category names to group names. To add stream a001 to News in Genre:

1. Read the stream with get-stream.
2. In the returned stream object, set groups.Genre to News. Keep all other fields, including version fields, and existing assignments.
3. Send the complete object with set-stream.

POST/control/

admin

Request body

{
    "cmd": "set-stream",
    "id": "a001",
    "stream": {
        "id": "a001",
        "name": "Channel 1",
        "type": "spts",
        "enable": true,
        "input": ["udp://239.255.1.1:1234"],
        "output": ["udp://239.255.2.1:1234"],
        "pmt_version": 1,
        "sdt_version": 1,
        "groups": {
            "Language": "ENG",
            "Genre": "News"
        }
    }
}

ResponseHTTP 200

{ "set-stream": "ok" }

Stream a001 is assigned to News. If the stream is enabled, it is restarted.

To unassign the stream from Genre, remove that key from groups and send the complete stream again. If no assignments remain, omit the groups field.

Request parameters

Parameter reference for POST /control/ with "cmd": "set-category":

cmdstringRequired

Use set-category for all category and group changes.

idnumberConditional

Current category index, starting at 0. Required to update or remove a category. Omit to add a category.

categoryobjectRequired

Complete category object. To remove it, send an object with remove set to true.

category.namestringConditional

Category name. Required to add or update a category. Follow the name rules below.

category.groupsarrayOptional

Complete group list. Omitting it clears all groups of the category.

category.groups[i].namestringConditional

Group name. Required for every entry except a removal marker.

category.groups[i].removebooleanOptional

Set to true instead of name to remove the group at this position. Later groups keep their positions.

category.removebooleanOptional

Set to true to remove the category addressed by id.

reorderstring[]Optional

Desired group order. Include every submitted group name exactly once. Since 260922.

forcebooleanOptional

Allow category removal even if it leaves a user's package list empty. Default: false.

Name rules

The same rules apply to category and group names:

• Letters, digits, spaces and - _ . & + /. Letters of any script count, so Кино is a name like any other.
• 1 to 64 characters, with no space at the start or at the end.
• Group names must be unique within a category, and category names unique in the list.

Valid examples: News, Sport 24, HD-Channels, Movies_EN, News & Sport, 24/7, Кино.

Response

A successful command returns HTTP 200 with "set-category": "ok". If streams or user records changed, the response also lists them:

{
    "set-category": "ok",
    "streams": [{ "id": "a001", "name": "Channel 1" }],
    "users": ["operator"]
}

Field	When present
streams	Lists the id and name of changed streams. Omitted when there are no reportable stream changes.
users	Lists logins of changed user records. Only category renaming or removal can change users. With the package list would be left empty error, lists the users that block the removal.

Errors

A rejected set-category command also returns HTTP 200. Check the JSON body for "set-category": "er":

{ "set-category": "er", "error": "category not found" }

Validation happens before changes are applied. A rejected command changes nothing.

Error	How to fix it
category is required	Include a category object.
id must be a number	Send a numeric category index.
id is required to remove a category	Include the category’s current index.
category not found	Read the current categories and use an index that exists.
category name is required	Include a string category.name when adding or updating. Removal needs no name.
category name is not valid	Follow the name rules.
category name already exists	Give the category a name no other category in the list holds.
group name is not valid (groups[i])	Correct the indicated group’s name using the name rules.
duplicate group name (groups[i])	Give each group a distinct name within the category.
reorder must be an array of group names	Send reorder as an array of strings.
reorder must name every group of the category once	Include each submitted group name exactly once, with no extra names.
package list would be left empty	Update the listed users’ packages, or explicitly allow unrestricted access with force: true.

For authentication and HTTP errors, see API replies.

Configuration updates and events

The configuration is saved after a successful change. WebSocket clients receive set-stream for each stream whose assignment changed, then set-category.

Version compatibility

reorder requires version 260922 or later. Earlier versions ignore it; the reorder example above leaves their group order and assignments unchanged.

Older versions also differ in these ways:

• force is ignored, so clients cannot rely on the package-list protection described above.
• Responses omit streams and users.
• Names rejected by the validation described above may be accepted.
• Category renaming and removal update stream assignments but leave references in settings and user records unchanged.