Reference

Admin API

scalwsd serves one admin API, HTTP/1.1 with JSON or plain-text answers, on up to four transports. scalwsctl and the console use it; this page lists every endpoint for tools that call it directly. Design records: ADR-0017 (socket and views), ADR-0023 (remote admin) and ADR-0049 (upstream pools).

Transports

Paths may carry a /v1 prefix (/v1/status and /status are the same endpoint); tools should use it. Changes use POST (or PUT for upstream members); other methods answer 405, unknown paths 404. Error answers are one line of plain text.

Over the socket with curl:

curl --unix-socket /run/scalws/admin.sock http://localhost/v1/status

Views

All views are GET. “Metrics” marks the views the metrics listener serves as well.

Changes

Available on the admin socket and the remote admin listener only.

Upstream pools

GET /v1/upstreams

Every pool of the active configuration, sorted by name:

{
  "pools": [
    {
      "name": "api",
      "members_from": "api",
      "balance": "round_robin",
      "members": [
        {
          "address": "192.0.2.5:8080",
          "weight": 2,
          "active_requests": 1,
          "consecutive_failures": 0,
          "ejected_until_unix_ms": null
        },
        {
          "address": "192.0.2.6:8080",
          "weight": 1,
          "active_requests": 0,
          "consecutive_failures": 0,
          "ejected_until_unix_ms": 1792000000000
        }
      ]
    }
  ]
}

With no pools the answer is {"pools": []}.

GET /v1/upstreams/{name}

One pool, as one element of pools above. 404 unknown pool for a name that is not configured.

PUT /v1/upstreams/{name}

Replaces the whole member list of a pool with members_from: api, without a reload:

curl --unix-socket /run/scalws/admin.sock -X PUT \
  --data '{"members": [{"address": "192.0.2.5:8080", "weight": 2}, {"address": "192.0.2.6:8080"}]}' \
  http://localhost/v1/upstreams/api

The body is a JSON object with exactly one key, members: a list of {"address": "...", "weight": N}, where weight is optional (default 1). Addresses follow the configuration’s rules: ip:port, [ipv6]:port, host:port, or unix:/path as the only member of a plain-HTTP pool. An empty list empties the pool (its requests then get 503 with Retry-After: 1).

A refused request changes nothing. The change is serialised with reloads; members that stay (same canonical address) keep their connections, load and health, requests in flight to a removed member finish, and the series of removed members leave the metrics. Members set this way survive reloads but not a restart. See load-balancing.md.

scalwsctl upstreams, scalwsctl upstreams show <pool> and scalwsctl upstreams set <pool> <addr[=weight]>... call these endpoints (scalwsctl).

Under scalws-controller

The controller’s local control API (controller.socket, default /run/scalws-controller/control.sock, mode 0600; see adaptive-runtime.md) answers the same three calls without the /v1 prefix:

A pool name that does not follow the name rule (lower-case letter first, then a-z, 0-9, -, _, at most 63 characters) is 404 there.