Aegis documentation

#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

  • Every endpoint lives under /api/...; nothing is versioned yet.
  • Authentication is the same session cookie the pages use (aegis_session). An
  • unauthenticated call answers 401; guard.require_user decides.

  • Unsafe requests from another origin are rejected with 403 before they reach
  • a route.

  • Answers are JSON objects. Success carries "ok": true most of the time; an
  • error 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.

  • Bodies are JSON (Content-Type: application/json), read with FastAPI's
  • Body(...); forms are used by the HTML routes only.

  • Sizes: an app config file and a settings document are capped at 1 MiB; a live
  • report carries at most 400 bytes of message.

    bash
    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.

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

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

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

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

    json
    {"ok": true, "detail": "task 41 queued again"}

    #Live feed

    #GET /api/live

    Connection details for the WebSocket client, handed out only after login.

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

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

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

    MethodPathPurpose
    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/backupback 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

    MethodPathPurpose
    GET/api/appsthe 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

    MethodPathPurpose
    POST/api/collector/setupcreate the databases and accounting chains
    POST/api/collector/ingestrun 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

    MethodPathPurpose
    GET/api/evocati/specthe protected-application rules
    PUT/api/evocati/specsave them
    POST/api/evocati/blockblock one address
    POST/api/evocati/limitrate-limit one address
    POST/api/evocati/countrycountry policy
    POST/api/evocati/trackstart tracking an address
    DELETE/api/evocati/track/{address}stop tracking it
    GET/api/evocati/counters/{chain}/{handle}live counters
    POST/api/evocati/applyapply the current rules
    POST/api/evocati/flushflush the dynamic sets

    #Network, keeper, GeoIP, preferences

    MethodPathPurpose
    POST/api/network/refreshre-read interfaces and addresses
    POST/api/network/tracktrack an address
    DELETE/api/network/track/{address}stop tracking it
    POST/api/keeper/jobs/{name}/runrun one scheduled job now
    POST/api/management/jobs/{name}/runthe 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/downloaddownload one dataset
    POST/api/management/geoip/indexrebuild an index
    POST/api/management/geoip/updaterrun 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.