#Panel JSON API
The panel has two kinds of route: HTML pages, which answer with a rendered page and a redirect, and JSON endpoints, which the panel's own JavaScript calls. This page documents the second kind — enough to script the panel or to build another client.
#Conventions
/api/...; nothing is versioned yet.aegis_session). Anunauthenticated call answers 401; guard.require_user decides.
403 before they reacha route.
"ok": true most of the time; anerror is {"ok": false, "error": "…"} with 400, 403, 404, 409 or 422. A few read endpoints return their payload without an ok key — the panel's chart and editor components take the object itself.
Content-Type: application/json), read with FastAPI'sBody(...); forms are used by the HTML routes only.
report carries at most 400 bytes of message.
curl -s --cookie "aegis_session=$SESSION" http://127.0.0.1:9981/api/tasker/feed | jq#Tasker
#GET /api/tasker/active
Queued and running roots, running first, for the window.
{"ok": true, "count": 2, "tasks": [ {"id": 41, "name": "vhost example.com", "group_name": "web", "status": "running", "started_at": "2026-11-17T15:20:01+00:00", "scheduled_at": ""}]}#GET /api/tasker/feed
One call for the window and the bell: what is in flight and the newest finished tasks. steps is the number of children; the window uses it to decide whether a running task can still be stopped.
{"ok": true, "active": [{"id": 41, "name": "…", "group_name": "web", "status": "running", "steps": 3}], "recent": [{"id": 40, "name": "…", "group_name": "mail", "status": "done", "steps": 0, "completed_at": "2026-11-17T15:19:40+00:00"}]}#GET /api/tasker/task/{id}
One task with its steps and the newest 60 log lines (logs are newest first).
{"ok": true, "task": {"id": 41, "name": "…", "type": "internal", "target": "web.vhost.create", "status": "done", "retries": 0, "max_retries": 0, "output": "…", "error_output": "", "…": "…"}, "steps": [{"id": 42, "name": "render nginx", "status": "done", "…": "…"}], "logs": [{"at": "2026-11-17T15:20:02+00:00", "stream": "out", "line": "action web.vhost.create"}]}Unknown id: 404 {"ok": false, "error": "unknown task: 999"}.
#POST /api/tasker/task/{id}/cancel
Cancels a pending task at once, or asks a running container to stop before its next step. A running task without steps cannot be interrupted.
{"ok": true, "detail": "task 41 stops after the current step"}400 with the reason when the task is unknown or its state does not allow it.
#POST /api/tasker/task/{id}/retry
Puts a failed, cancelled or interrupted root back in the queue, keeping the same id and the previous attempt in its log.
{"ok": true, "detail": "task 41 queued again"}#Live feed
#GET /api/live
Connection details for the WebSocket client, handed out only after login.
{"enabled": true, "url": "ws://host:9982", "path": "/ws", "channel": "private", "token": "…", "ping": 20}path is the same-origin proxy nginx provides, which is what a page served over TLS uses (wss). See live.md.
#POST /api/live/report
Client-side diagnosis, one line per report in <logs>/web-admin-live.log.
{"stage": "message", "message": "first core message, data"}stage must be one of open, message, frame, decode, handler, socket; anything else is 400.
#Charts
#GET /api/management/tasker/series?range=24h
Finished and failed tasks per hour, for the Tasker page.
{"labels": ["2026-11-17T13:00", "…"], "unit": "tasks", "series": [{"name": "done", "values": [3, 0, 1]}, {"name": "failed", "values": [0, 1, 0]}]}range accepts 24h, 48h, 72h (default 24h).
#GET /api/management/bird/series?range=24h
Joins and leaves per hour, rebuilt from the Bird log.
#GET /api/network/interface/{name}/series
IN/OUT bytes per second of one interface; range, start and end are passed to the collector. 400 when the window is not valid.
#GET /api/network/ip/{address}/series
The same for one address.
#GET /api/monitor/history/{section}/series
Stored samples of one monitor section.
#Settings editor
| Method | Path | Purpose |
|---|---|---|
GET | /api/settings/file/{name} | raw text plus the parse error, if any |
GET | /api/settings/data/{name} | parsed document and the form hints |
PUT | /api/settings/data/{name} | apply submitted values through tomlkit, comments kept |
PUT | /api/settings/file/{name} | save raw text |
POST | /api/settings/databases/backup | back up the panel's SQLite databases |
A write answers with the new document; 400 carries the validation error and 404 an unknown file name.
#Applications and jobs
| Method | Path | Purpose |
|---|---|---|
GET | /api/apps | the catalogue the Apps page renders |
GET | /api/apps/{name} | one application |
GET | /api/apps/{name}/file?path=… | current content of one config file |
PUT | /api/apps/{name}/file?path=… | back up and save that file |
POST | /api/apps/{name}/action | {"action": "install"} → starts a background job |
GET | /api/jobs/{id} | job state and the tail of its log |
A file endpoint never escapes the application's config_dir: the path is resolved and checked against the root. 413 when the body is too large, 409 when an action cannot start (already running, unknown action).
#Collector
| Method | Path | Purpose |
|---|---|---|
POST | /api/collector/setup | create the databases and accounting chains |
POST | /api/collector/ingest | run one ingestion pass for every submodule |
GET | /api/collector/raw/{name} | last raw snapshot, unchanged |
GET | /api/collector/log/{name} | tail of one daemon's log |
ingest reports {"ok": …, "details": [...], "errors": [...]} — partial success is a normal outcome when one collector is down.
#Evocati
| Method | Path | Purpose |
|---|---|---|
GET | /api/evocati/spec | the protected-application rules |
PUT | /api/evocati/spec | save them |
POST | /api/evocati/block | block one address |
POST | /api/evocati/limit | rate-limit one address |
POST | /api/evocati/country | country policy |
POST | /api/evocati/track | start tracking an address |
DELETE | /api/evocati/track/{address} | stop tracking it |
GET | /api/evocati/counters/{chain}/{handle} | live counters |
POST | /api/evocati/apply | apply the current rules |
POST | /api/evocati/flush | flush the dynamic sets |
#Network, keeper, GeoIP, preferences
| Method | Path | Purpose |
|---|---|---|
POST | /api/network/refresh | re-read interfaces and addresses |
POST | /api/network/track | track an address |
DELETE | /api/network/track/{address} | stop tracking it |
POST | /api/keeper/jobs/{name}/run | run one scheduled job now |
POST | /api/management/jobs/{name}/run | the same, from the Jobs page |
POST | /api/management/jobs/{name} | create or update a job |
DELETE | /api/management/jobs/{name} | remove a job |
POST | /api/management/geoip/download | download one dataset |
POST | /api/management/geoip/index | rebuild an index |
POST | /api/management/geoip/updater | run geoipupdate |
POST | /api/settings/geoip/{action} | the older GeoIP entry point |
POST | /api/preferences | {"theme": "dark", "sidebar": "default"} |
/api/preferences stores the same two values the browser keeps in localStorage; an unknown key is rejected in rejected instead of failing the whole call.
#HTML routes
Everything else is a page or a form. Form routes answer 303 to the page they came from with ?ok=… or ?error=…, and are not meant for scripts. The rule of thumb: if it changes the host, call the tasker endpoint or the CLI — a form post that queues a task is still a form post, with a session cookie and a redirect.