`GET /api/runners/dispatch-state` — per-runner load / cap / drain / liveness for the operator console (ADR 0046 P2.7). System-admin auth. Replaces the dashboard's fragile container-id heuristic with a real wire field.

GET

/api/runners/dispatch-state

curl --request GET \
  --url https://example.com/api/runners/dispatch-state

Responses

200

Per-runner load / cap / drain / staleness

Media typeapplication/json

Array

Operator-facing dispatch state for one runner (ADR 0046 P2.7 observability): the registry row plus live load (open in-flight assignments), its advertised max_parallel cap, and whether its heartbeat has gone stale.

object

capabilities

required

Free-form advertised capabilities (images/labels/max_parallel/weight/…). Typed as an open string-keyed map in the spec (not Object, which strips every key) so the FE binds the advertised capability map it reads (#541).

object

key

additional properties

created_at

required

string format: date-time

drain_state

required

ADR 0046 RUNG 2 — graceful drain: active | cordoned | draining. cordoned/draining runners receive no new work but keep heartbeating and finish in-flight assignments. Always populated from the row (this type is serialize-only), so no serde default is needed.

string

id

required

string format: uuid

last_heartbeat_at

string | null format: date-time

name

required

string

registered_at

required

string format: date-time

status

required

string

in_flight

required

Open (‘assigned’/‘claimed’/‘running’) assignments this runner holds.

integer format: int64

max_parallel

The advertised concurrency cap (RUNG 3), if any.

integer | null format: int64

stale

required

True when the last heartbeat predates the liveness stale window (the sweep will demote it / dispatch already skips it).

boolean

Example^generated

[
  {
    "capabilities": {
      "additionalProperty": "example"
    },
    "created_at": "2026-04-15T12:00:00Z",
    "drain_state": "example",
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "last_heartbeat_at": "2026-04-15T12:00:00Z",
    "name": "example",
    "registered_at": "2026-04-15T12:00:00Z",
    "status": "example",
    "in_flight": 1,
    "max_parallel": 1,
    "stale": true
  }
]

401

Authentication required

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

403

Permission denied

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

500

Structured server error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}