API Reference¶

Eight.ly OS is a single Go binary. Everything the dashboard does, it does by calling this same HTTP API — there is no separate backend for the UI.

Base URL: http://box.example.lan:8080/api/

The spec¶

The API is described by an OpenAPI 3.1 document, generated straight from the Go router by scripts/gen-openapi.py — it isn't hand-written, so it can't describe a route that doesn't exist. Every box serves its own copy live:

curl http://box.example.lan:8080/api/openapi.json

Fetch it and read it with any OpenAPI tool (Swagger UI, Postman, eosctl api) rather than copying routes out of this page by hand — this page gives you the shape of the API, not the whole spec.

Authentication¶

Two ways to authenticate:

• API key — Authorization: Bearer eos_.... Create one from Settings > Security > API Keys in the dashboard. See API Keys.
• Signed-cookie session — what the dashboard itself uses. POST /api/auth/login issues an HMAC-SHA256 signed cookie (not a JWT); every subsequent request just needs the cookie.

Log in (session cookie)¶

curl -c cookies.txt -X POST http://box.example.lan:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

{
  "success": true,
  "data": { "id": "...", "username": "admin", "role": "admin", "status": "active" }
}

curl -b cookies.txt http://box.example.lan:8080/api/health

Repeated failed logins are throttled per-IP and per-username (429 Too Many Requests with a Retry-After header); every login attempt, success or failure, is audit-logged.

Cookie sessions need a CSRF token; API keys don't¶

A state-changing request (POST/PUT/PATCH/DELETE) made with a session cookie must also carry a double-submit CSRF token — the server rejects it otherwise. A request authenticated with Authorization: Bearer eos_... is exempt: a bearer token can't be replayed cross-origin the way a cookie can, so there's nothing for CSRF to protect against on that path. If you're scripting against the API, using an API key sidesteps CSRF entirely — that's the main reason the CLI, the MCP server, and any automation should use one rather than logging in.

API keys¶

curl -H "Authorization: Bearer eos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  http://box.example.lan:8080/api/health

Full detail — creating, listing, and revoking keys, and what a key can do — is on the API Keys page.

Response envelope¶

Success responses across the API share one shape:

{
  "success": true,
  "data": { }
}

Parse .data.

Error bodies are less consistent. The spec's own declared response schema says {"success": false, "message": "..."}, but some handlers don't follow it — a few return {"success": false, "error": "..."} instead, and a handful of older ones return a bare {"error": "..."} with no success field at all. Check the HTTP status code first, and look for a message under either message or error rather than assuming one key name.

Common status codes: 400 bad request, 401 not authenticated, 403 not authorized, 404 not found, 429 rate limited, 500 server error.

API areas¶

Counted straight from the spec: 521 distinct paths, 695 operations, across 69 subsystem groups.

This table shows the largest groups and a representative slice — not the full spec.

RBAC is enforced per subsystem, deny-by-default — each API package wires its own role requirements, and an endpoint with no role wired rejects the request. Three roles:

An API key has no role of its own — it inherits whichever of these three roles the account that created it holds. See API Keys.

Common endpoints¶

# System health
curl -b cookies.txt http://box.example.lan:8080/api/health

# List containers
curl -b cookies.txt http://box.example.lan:8080/api/containers

# List VMs
curl -b cookies.txt http://box.example.lan:8080/api/vm/list

# Storage status
curl -b cookies.txt http://box.example.lan:8080/api/storage/status

# App catalog
curl -b cookies.txt http://box.example.lan:8080/api/apps

# Nova AI chat
curl -X POST -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"message": "how much disk space is free?"}' \
  http://box.example.lan:8080/api/nova/chat

Prefer not to hand-write curl calls at all? eosctl is a command line client generated from this same spec, and eosctl-mcp exposes it to AI assistants as MCP tools.

Streaming¶

curl -N -b cookies.txt http://box.example.lan:8080/api/events

One shared SSE connection streams system metrics, container state changes, storage events, and Docker events — the dashboard uses a single EventSource for all of it.

Nova AI chat responses stream as NDJSON, emitting thinking, tool_call, tool_result, and content events.

WebSocket endpoints¶