`PUT /api/v1/pollers/{id}/pool` — move this poller to another pool (ADR-107 Inc.2).
const url = 'https://example.com/api/v1/pollers/example/pool';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"on_source_empty":"move_nodes","pool":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://example.com/api/v1/pollers/example/pool \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "on_source_empty": "move_nodes", "pool": "example" }'This moves it, now. Core owns pollers.pool; the write here plus
[crate::coordinator::Coordinator::set_pool] rebuild the pool’s hash ring on the next sweep
(woken immediately) and the poller receives a snapshot of the new pool’s nodes on
yagra.poller.assign.{id} — a subject with no pool token in it, which is why the primary work
path needs no cooperation from the poller at all. The snapshot also carries the pool name, which
is how the poller re-points the three subjects that are pool-derived and reconnects the bus so
Auth Callout re-mints its credential. Nothing restarts.
Two refusals, and both exist because the failure they prevent is silent:
poller_cannot_change_pool— the build does not advertisepool-follow([yagra_bus::CAP_POOL_FOLLOW]), or it is offline. Moving it anyway would look like it worked: the working set would arrive and the screens would agree, whilepoll_nowand discovery kept going to the old pool’s subject, where nothing is listening.source_pool_would_empty— this is the last live poller of its current pool and that pool still has nodes assigned. The caller must choose explicitly withon_source_empty, because the alternative is an entire pool that stops being monitored with no error anywhere. Folders alone do not trigger it: a folder with no nodes under it strands nothing, and it travels with amove_nodesanswer anyway.
⚠️ The second check is deliberately duplicated in the WebUI, and is not a mirror. The UI
asks “should I show the confirmation?”; this asks “did the caller answer?”. This side is the
authority — a client that skips the dialog gets the 409, not the hole.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Poller id
Request Bodyrequired
Section titled “Request Bodyrequired”Move a poller to another pool.
object
The destination pool. Validated as a NATS subject token.
Responses
Section titled “Responses”The poller was moved
The pool name is not a valid subject token (letters, digits, _ and - only), or is longer than 63 characters
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}No valid bearer token
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Role lacks the ManageSystem permission
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}No such poller
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}The poller cannot follow a pool change, or the move would leave its current pool unmonitored and the caller did not say what to do
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}This deployment has no write side (skeleton mode)
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}