Skip to content
Yagra

`GET /api/v1/pools` — the pools that exist, for the assignment picker. Names only, no telemetry.

GET
/api/v1/pools
curl --request GET \
  --url https://example.com/api/v1/pools \
  --header 'Authorization: Bearer <token>'

Deliberately separate from GET /pollers, which scans the whole node table to build its per-pool counts; this is one small table plus two indexed DISTINCTs, and is loaded by an ordinary page.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The pools on offer, default first, each flagged with whether a live poller serves it

Media typeapplication/json

The pools that exist, for the assignment picker.

object
pools
required
Array<object>

One pool offered by the pool picker.

object
covered_by

The pool currently polling this one’s members on its behalf, if an operator asked for that (ADR-107 Inc.4). None is the ordinary case.

⚠️ Its members are already in that pool — this says the move is recorded and can be undone, not that it is pending. A UI that reads it as “will be” would offer a takeover that has already happened.

string | null
description

Why this pool exists, in the operator’s words. None for a pool nobody has described — including every pool that predates the pools table, which is most of them on an existing deployment.

string | null
live
required

Whether a live poller currently serves it. A pool with none takes the legacy per-job path onto a subject nothing subscribes to, so its jobs are silently discarded — the picker has to say so rather than present it as an equivalent choice.

boolean
name
required

Pool name.

string
Examplegenerated
{
  "pools": [
    {
      "covered_by": "example",
      "description": "example",
      "live": true,
      "name": "example"
    }
  ]
}

401

Section titled “401”

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

Role lacks the View permission

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Section titled “503”

This deployment has no write side (skeleton mode)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}