18790. Add the access cookie to each curl, as shown under Authentication. All six routes are on the general rate limit described in the REST API overview.
Routes
Settings
Clawboo keeps the Gateway URL, the Gateway token and the time the first-run notice was dismissed in<clawboo home>/settings.json (~/.clawboo/settings.json unless CLAWBOO_HOME is set). Most other dashboard settings live in the SQLite settings table and are not served here.
No route returns the Gateway token. The server adds it itself when it connects to the Gateway, so the browser never needs it. Errors use { "error": "<message>" }.
GET /api/settings
Responses
200 OK:
gatewayUrl is the first of:
- the URL saved in
settings.json; ws://localhost:<port>, when no token is saved and OpenClaw’sopenclaw.jsonhas both a Gateway token and a port;ws://localhost:18789.
hasToken is true when a Gateway token resolves: the token saved in settings.json (a ${VAR} value is read from the environment, then from OpenClaw’s .env), or else the gateway.auth.token in OpenClaw’s openclaw.json. So it can be true with nothing saved in Clawboo. OpenClaw’s files are in its state directory, ~/.openclaw by default.
500 Internal Server Error: the settings could not be read, { "error": "<message>" }.
Example
POST /api/settings
Saves only the fields you send; the rest keep their values, so a dismiss-only request leaves the Gateway URL alone. A field of the wrong type is ignored rather than rejected.
- Request body:
ws: or wss: URL is accepted, because the server later connects to it. After you clear it, GET returns the fallback above. Changing gatewayUrl or gatewayToken makes the server reconnect to the Gateway in the background.
Responses
200 OK: { "ok": true }.
400 Bad Request: the body is missing or not a JSON object:
400 Bad Request: a non-empty gatewayUrl that is not a ws:// or wss:// URL:
500 Internal Server Error: saving failed, { "error": "<message>" }.
Example
Health
The server runs a boot probe at startup and keeps the result: one pass or fail per check, plus what the install resolved (folders, port, vault). The System Health panel shows it. These routes answer with the Gateway down, andok (true when no check is fatal) is the one field a monitor needs.
Responses pass through the same redaction as the logs, so a credential-shaped string inside a check’s message is masked. On failure the health routes answer { "ok": false, "error": "<message>" }.
GET /api/health
Returns the latest boot report. A request that arrives before the first report exists computes one.
Responses
200 OK: the boot report (see The boot report below), with ok added. Dates are ISO strings.
200 OK while the server moves older work into the work folder at startup (see The work folder): { "ok": false, "status": "migrating", "migration": { "total": <n>, "done": <n>, "left": <n> } }. Until the move ends, every other request answers 503 with a Retry-After: 2 header and { "error": "Clawboo is moving its work folders. Try again in a moment.", "status": "migrating" }, and a WebSocket upgrade gets 503 too. The HTTP answers come after the access gate, like any other. A WebSocket upgrade is refused before the origin and access checks, with no body.
500 Internal Server Error: computing a first report failed, { "ok": false, "error": "<message>" }.
Example
POST /api/health/recheck
Runs the boot probe again: the Re-run probe button in System Health. It runs SQLite’s full integrity_check, where the boot probe runs the quicker quick_check, so on a large database the answer can take several seconds; the server keeps answering other requests meanwhile. When the Gateway cannot be reached, the answer also waits out the Gateway check, about 1.5 seconds. Takes no body.
Responses
200 OK: the new boot report, the same shape as GET /api/health.
500 Internal Server Error: { "ok": false, "error": "<message>" }.
Example
The boot report
ok: true with a non-empty degraded. Three failures are fatal: clawbooHomeWritable, databaseIntegrity and databaseSchema. Each failed check’s detail says what to do; resetting the Clawboo home folder is the last resort (see Data and state).
The checks, in the order they run:
config reports the defaults this build ships, not live overrides: logLevel reads info even when LOG_LEVEL is set. Only otelConfigured and otelActive reflect this boot.
Graph layout
The node positions the dashboard saves when you drag nodes on a graph, stored in the SQLitegraph_layouts table under a pair of keys: a layout name and a Gateway URL. The URL is only part of the storage key: when the dashboard runs without a Gateway, it saves under ''. Errors on POST use { "ok": false, "error": "<message>" }.
In a
loose- layout the position keys are node ids such as loose:skill:web-search.
GET /api/graph-layout
The query parameter for the Gateway URL is url, not gatewayUrl.
- Query params:
Responses
200 OK: the saved layout, or no positions when nothing is saved:
{ "positions": {} }.
Example
POST /api/graph-layout
Creates or replaces the positions for one layout. The positions are stored as sent.
- Request body:
Responses
200 OK: { "ok": true }.
400 Bad Request: the body is not a JSON object:
400 Bad Request: gatewayUrl is missing or not a string:
500 Internal Server Error: { "ok": false, "error": "<message>" }.
Example
apps/web/server/api/settings.ts with packages/config/src/index.ts (settings resolution), apps/web/server/api/health.ts with apps/web/server/lib/bootProbe.ts and lib/defaults.ts, apps/web/server/lib/workDirMoveGate.ts (the answers while the work folder move runs), and apps/web/server/api/graphLayout.ts.
Related
- System Health: the panel over the boot report
- Configuration:
settings.jsonand the other files in the Clawboo home folder - Environment variables:
CLAWBOO_HOME,LOG_LEVELand the OpenTelemetry variables - System API: installing, configuring and starting the OpenClaw Gateway
- Org chart: the graphs whose positions these routes save