Process API

Check the state of an Astra instance, monitor system resources, read logs and restart the instance. See How to call API methods for authentication and custom control paths.

Get status

Read the version, uptime, license and detected hardware. The response example shows the main fields; hardware fields are described below.

POST/control/

admin, observer

Request body

{ "cmd": "status" }

Response excerptHTTP 200

{
    "status": "ok",
    "version": "Astra 260918 (commit:c109858f)",
    "uptime": 3600,
    "hostname": "streamer-1",
    "license": {
        "id": "ABCDEF",
        "type": 2,
        "expire": 1790000000
    }
}

Field	Description
`status`	`"ok"`
`version`	Astra build version
`uptime`	Runtime uptime in seconds. Resets after Restart
`hostname`	The `instance_name` setting, or the system host name
`license`	License details. Fields depend on the license state; see License fields
`dvb_list`	Detected DVB frontends. Omitted when none are found
`if_list`	Names of network interfaces that are up, for example `["lo", "eth0"]`
`net_list`	Details of those network interfaces. Both network lists are omitted when no interface is up

DVB frontends

Each dvb_list item describes one frontend. Restart Astra to refresh this list after hardware changes.

Field	Description
`adapter`, `device`	Numeric indexes in `/dev/dvb/adapterN/frontendM`
`busy`	Whether the frontend is in use. Omitted if it could not be opened
`type`	Frontend class: `S`, `C`, `T` or `ATSC`, when detected
`frontend`	Driver-reported frontend name, when detected
`mac`	Adapter MAC address, when available
`error`	Probe error, such as `Permission denied`

Network interfaces

Each net_list item describes one interface that is up.

Field	Description
`name`	Interface name, for example `eth0`
`up`	Always `true` for interfaces in this list
`loopback`, `running`, `broadcast`, `multicast`	Present as `true` when the corresponding interface flag is set
`flags`	Numeric interface flags
`index`	Numeric interface index
`mac`	Link-layer address, when available
`ipv4`	IPv4 addresses, for example `["192.168.1.10"]`, when available

System status

Read CPU, memory and uptime statistics. Use GET /api/system-status?t=0 for the latest sample, or omit t for the last interval report.

GET/api/system-status

admin

Query parameters

tnumberOptional: 0 for the latest sample; 1 for the last interval report. Default: 1.

ResponseHTTP 200

{
    "timestamp": 1758268800,
    "instance": "streamer-1",
    "la1": 45,
    "la5": 40,
    "la15": 38,
    "app_threads": 12,
    "sys_cpu_usage": 12,
    "app_cpu_usage": 3,
    "sys_mem_usage": 31,
    "app_mem_usage": 1,
    "app_mem_kb": 163184,
    "sys_uptime": 14400,
    "app_uptime": 60
}

Samples update every 10 seconds. Interval reports average thread count, CPU and memory usage over 60 seconds by default, configured by tsdb_interval. Load averages and uptimes use the last sample. Values are zero until the first sample or report is ready.

Field	Description
`timestamp`	Unix time: report creation time for `t=1`, current time for `t=0`
`instance`	The `instance_name` setting. Omitted when not set
`la1`, `la5`, `la15`	Load averages over 1, 5 and 15 minutes, multiplied by 100 and truncated. For example, `45` means `0.45`
`app_threads`	Number of process threads
`sys_cpu_usage`	Total system CPU usage, 0 to 100% across all CPUs
`app_cpu_usage`	Process CPU usage as a percentage of one CPU. Can exceed 100% on a multi-core host
`sys_mem_usage`	Percentage of total system memory that is not available
`app_mem_usage`	Process resident memory as a percentage of total system memory
`app_mem_kb`	Process resident memory in KiB
`sys_uptime`	Time since system boot, in minutes
`app_uptime`	Time since the process started, in minutes. Does not reset after Restart

A numeric t other than 0 or 1 returns HTTP 200 with an error:

{ "error": "not implemented" }

Version

Read the Astra build version.

POST/control/

admin, observer

Request body

{ "cmd": "version" }

ResponseHTTP 200

{ "version": "Astra 260918 (commit:c109858f)" }

The version contains the build date and commit.

Log

Read the most recent log entries, oldest first. Astra keeps up to 2000 entries in memory, separately from the log file.

POST/control/

admin, observer

Request body

{ "cmd": "log" }

ResponseHTTP 200

{
    "log": [
        {
            "level": "INFO",
            "time": 1758268800,
            "message": "[main] Starting Astra 260918 (commit:c109858f)"
        },
        {
            "level": "ERROR",
            "time": 1758268801,
            "message": "[main] Authentication failed. Login:admin IP:192.168.1.10"
        }
    ],
    "last_id": 1043
}

Field	Description
`log`	Log entries, oldest first
`log[].level`	`INFO`, `WARN`, `ERROR` or `DEBUG`. Debug entries require debug logging
`log[].time`	Unix time when the entry was recorded
`log[].message`	Message without the timestamp and level prefix
`last_id`	ID to use in the next request to read newer entries

Read new log entries

Pass last_id from the previous response to read only newer entries:

POST/control/

admin, observer

Request body

{
    "cmd": "log",
    "last_id": 1043
}

ResponseHTTP 200

{
    "log": [
        {
            "level": "INFO",
            "time": 1758268802,
            "message": "[main] Reloading configuration"
        }
    ],
    "last_id": 1044
}

Use 1044 in the next request. If there are no new entries, the response is {"log": []} without last_id; keep the previous value. Read frequently enough to stay within the 2000-entry archive.

last_idnumberOptional: Return entries recorded after this ID. Omit to read the entire archive.

With POST /control/, put last_id in the JSON body.

Restart

Reload the configuration file and restart streams, adapters and servers.

POST/control/

admin

Request body

{ "cmd": "restart" }

ResponseHTTP 200

{ "restart": "ok" }

The restart begins one second after the response. Streaming and API access are briefly interrupted, and WebSocket clients must reconnect.

For authentication and HTTP errors, see API replies.