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.

• To read categories, download the configuration and look at its categories array. The order in this array is the display order.
• To assign a stream to a group, set its groups field, which maps category names to group names, and send the complete stream with set-stream.
• To add, change or remove categories and groups, use set-category.

See How to call API methods for authentication and custom control paths.

Set category

Add, update or remove a category with its groups.

POST/control/set-category

admin

Request

idnumber

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

categoryobjectrequired

Complete category object. To remove the category, send {"remove": true}.

category.namestring

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

category.groupsarray

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

category.groups[i].namestring

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

category.groups[i].removeboolean

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

category.removeboolean

Set to true to remove the category addressed by id.

reorderstring[]Since 260922

New group order. Include every submitted group name exactly once.

forceboolean

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

Response

set-categorystring

ok on success, er if the command is rejected.

errorstring

Present with er. See Errors.

streamsarray

id and name of changed streams. Omitted when there are no reportable stream changes.

usersstring[]

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.

Category index

id is the category’s index in the categories array, starting at 0. With Genre and Language in this order, 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.

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, Кино.

Errors

A rejected command also returns HTTP 200, with "set-category": "er" and the reason in error:

{ "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.

Add a category

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

Request

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

Response

{ "set-category": "ok" }

The category is added to the end of categories. To fill its groups, assign streams to them.

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.

Request

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

Response

{
    "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.

Request

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

Response

{ "set-category": "ok" }

The group is added. No streams change.

Rename a group

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

Request

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

Response

{
    "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:

Request

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

Response

{
    "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. Requires version 260922 or later.

Request

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

Response

{ "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:

Request

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

Response

{
    "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:

Request

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

Response

{
    "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:

Request

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

Response

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

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

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.