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 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
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": [
    {
      "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"
  }
}