API

The panel exposes a JSON HTTP API under /api. Every route documented here exists in dashboard/src/app/api/** — methods and auth were read from the handlers, not inferred.

Authentication#

Three ways in, checked by lib/auth.ts / middleware.ts:

Roles: admin, operator, developer (scoped to assigned groups), viewer (read-only). Sensitive vaults (mail, domains, system credentials) additionally require sudo mode — a 5-minute elevation from POST /api/auth/reauth.

Who a route answers to#

The middleware lets the machine token through everywhere, but a handler decides who it is talking to in one of two ways, and the tables below say which:

• requester() (lib/requester.ts): a session, a personal token, or the machine token, which counts as an admin named "machine". A request the relay executes for a joined cluster carries the machine token plus a signed hop naming a person, and is answered as that person.
• currentUser() only: a session or a personal token. The machine token is refused with 401 on these routes, marked session only below. Routes that act on "your own account" need an account id, so they refuse the machine token too.
• Grant-gated: public at the middleware (it runs on the edge, with no store to read a grant from), verified in the handler against the grant's own paths, constant-time.

Two query parameters address another cluster (lib/cluster-params.ts). ?cluster=<id> on an instance action or anything under /api/services/<vmid>/ acts on that cluster's nodes directly over the mesh, with the credentials it issued, so it works while its panel is down; it is refused for a scoped account, for any role but admin or operator, and while the cluster has issued no reach. ?estate=<id> on an edit of a store record forwards the request to the panel that owns the record through its relay, as the person asking; only a signed-in, unscoped account may cross. Both take the cluster's own id. Sending either empty is a 400, never "local".

The same request, three ways — a session login followed by a read of the fleet overview:

# Session login: the cookie jar holds conduit_s afterwards.
curl -s -X POST http://panel:3001/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"name":"admin","password":"…"}' -c cookies.txt

# Or skip the session entirely and use a personal token.
curl -s http://panel:3001/api/overview -H 'Authorization: Bearer cu_…'

# One-time: name the panel, then approve the login from the panel's /approve page.
conduit context add production --url http://panel:3001
conduit auth login

# --json prints the route's response verbatim, so anything below is scriptable.
conduit status --json

const panel = "http://panel:3001";
const token = process.env.CONDUIT_TOKEN;   // cu_… — a personal token, never a machine token

const res = await fetch(`${panel}/api/overview`, {
  headers: { authorization: `Bearer ${token}` },
});

// A panel error arrives as 200 + {ok:false}, not as a 5xx — see "5xx does not carry a
// message anybody will read" below. Checking res.ok alone will miss it.
const body = await res.json();
if (!res.ok || body.ok === false) throw new Error(body.error ?? `HTTP ${res.status}`);

Conventions#

• Requests and responses are JSON (uploads use multipart).
• Errors: { "error": "message" } with a 4xx/5xx status.
• Mutations (POST/PATCH/PUT/DELETE) are recorded in the operator audit log with actor, method, and path.
• Failed logins answer after a uniform 400ms delay — no timing or existence oracle.

5xx does not carry a message anybody will read#

A panel behind Cloudflare cannot use a 5xx status to deliver an explanation. Cloudflare treats an origin 5xx as its own concern: it discards the body and serves a branded error page instead. Measured on this cluster — a 90-byte JSON explanation replaced by 6419 bytes of 502: Bad gateway HTML — and the browser then reports SyntaxError: unexpected character at line 1 column 1, which names the JSON parser and nothing that actually happened.

So the rule for handlers:

• 4xx for a request that could not be served as asked (unknown id, wrong software, not running, forbidden). These reach the client untouched, body included.
• 200 with ok: false and an error string for an operation that ran and did not succeed. The request was served; the outcome is the failure, and an outcome belongs in the body.
• 5xx only for genuinely unhandled faults, where nobody is relying on the text.

Swept across every handler on 2026-08-25: 26 sites moved off 5xx, and lib/api-fail.test.ts now fails the build if a new one appears. failed(e) in lib/api-fail.ts is the one implementation — 409 rather than 400 because these are almost never malformed requests: the request was fine and the cluster could not honour it, and 400 would blame the caller for the cluster's state.

/api/metrics/prometheus is the deliberate exception, for the opposite reason to everything else: nobody reads its text, a scraper reads the status. A 200 carrying an error comment would be recorded as a successful scrape of zero metrics — indistinguishable from a healthy idle cluster — so the 500 is the signal, and it is scraped inside the network rather than through the CDN.

services/[vmid]/hytale-auth is the worked example. On the client, lib/read-json.ts (readJson / fetchJson) reads a reply without letting a non-JSON one masquerade as a parser bug, and names the intermediary when a reply was replaced in transit. Prefer it to fetch(...).then(r => r.json()).

Route families#

Method lists are exact; per-field shapes live in the handlers.

Auth & account#

Fleet & infrastructure#

Joined clusters#

Capabilities from the manifest: /api/fleet reads with network.view and writes with network.edit (the handlers add admin); /api/fleet/grants is settings.secrets; /api/fleet/front-door and /api/clusters are network.view. The grant-gated routes are public at the middleware and verify the grant in the handler.

Services & consoles#

Players & gameplay#

Observability & automation#

/api/alerts: read open, not resolved. resolved is a property of one ENTRY, not of the condition. A "service is DOWN" record keeps resolved: false for ever — it is a true record of something that happened — and its recovery arrives as a separate entry carrying the same key. Openness is therefore "is the newest entry for this key unresolved", which is what the open flag on each entry and the openCount on the response answer, both judged over the whole ring rather than the returned window. Filtering on !resolved reports a healthy cluster as a wall of red; that is not hypothetical, it is how this note came to be written.

Streams (SSE)#

Machine API#

Paths intended for the connector and infrastructure (bearer-token auth; see lib/connector-auth.ts): /api/connector/* (heartbeat, register, unregister, event, announce, broadcasts, tabresult, transfer, pending, report, maintenance, rounds, servers, move-targets, selection — the in-game wand posts its box here — and maps/groups|upload|commit, the map studio's upload path: the connector asks for the game groups, gets a presigned S3 PUT for the world tarball, and commits only after the panel has verified the object exists), plus /api/luckperms/effective, /api/worlds/pull, /api/languages/lang-data, /api/friends|parties|bans|logs ops, and /api/metrics/prometheus.

The hub speaks its own small protocol, documented in hub/README.md: GET /v1/feed, GET /v1/artifacts/<version>.tgz, PUT /v1/releases/<version> (bearer publish token), POST /v1/ping, POST /v1/crash, GET /v1/crashes, GET /v1/stats, and GET /v1/diagnostics (a cluster reading back its own private crash detail, bearer cluster secret). The full protocol is described in architecture.md → Connector protocol.

One machine path authenticates differently: POST /api/auth/cli-session (the SSH gateway's token exchange) accepts only the CT-local secret at /etc/conduit/cli-gateway.secret, compared constant-time — useless from anywhere the reconcile leader hasn't provisioned that file.

Rate limiting — there is no global limiter. Login enforces a uniform 400ms failure delay, inbound hooks have per-hook cooldowns, and report filing is rate-limited; other routes rely on the auth gate. Front the panel with your own limiter if it faces the open internet.