Sessions API

Sessions are the active client connections to HTTP MPEG-TS and HLS outputs and to SRT outputs in listener mode. They are not the login sessions of the web interface: those are created and revoked by the Authentication API.

Get session list

Request: GET /api/sessions or POST /control/. Control on the path entry point; control and observer on the command entry point. An observer calling GET /api/sessions receives 404.

{
    "cmd": "sessions"
}

The path form takes no body. A second path segment (/api/sessions/anything) is ignored.

Response:

{
    "sessions": [
        {
            "client_id": 47311928,
            "channel_id": "a001",
            "channel_name": "Channel Name",
            "addr": "192.168.1.10",
            "login": "viewer",
            "ua": "VLC/3.0.20 LibVLC/3.0.20",
            "uptime": 128
        }
    ]
}

• client_id - number, the session identifier: a random integer between 10000000 and 99000000, unique among the running sessions. The id of close-session.
• channel_id - string, optional. The id of the stream the client plays.
• channel_name - string, optional. The name of the stream.
• addr - string, optional. For HTTP clients the client IP address: the peer address, or the X-Real-IP header when the HTTP authentication option x_real_ip or the allow_real_ip setting is enabled (a header value that is not an IP address falls back to the peer address). For SRT clients the peer address:port.
• login - string, optional. The login the authorization chain granted the session to, for example the user matched by its token or ip. Absent when the channel has no authorization or the client was granted without a user.
• ua - string, optional. The User-Agent header of an HTTP client; srt for an SRT client.
• uptime - number, seconds since the session started.

An optional field is left out of the object when it has no value. An HTTP session is listed from the moment the request arrives, before its authorization completes, so a row may appear a moment before its login does. The order of the list is not defined.

Example:

curl --user login:password http://server:8000/api/sessions

Close session

Request: POST /control/. Control only.

{
    "cmd": "close-session",
    "id": 47311928
}

• id - number or numeric string, required. The client_id from the session list.

Response:

{ "close-session": "ok" }

The reply is ok whether or not a session with that id existed; an id that is not a number closes nothing. An HTTP MPEG-TS connection is closed, an HLS session is removed from its channel and its next media playlist request is answered 404. SRT client sessions are listed but cannot be closed with this command.

Example:

curl \
    -X POST \
    --user login:password \
    -d '{"cmd":"close-session","id":47311928}' \
    http://server:8000/control/