`PUT /api/v1/pools/{name}` — rename a pool and/or replace its description.
const url = 'https://example.com/api/v1/pools/example';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"description":"example","name":"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/pools/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "description": "example", "name": "example" }'🚨 A rename is refused while a poller serving the old name cannot follow a pool change, and
that refusal is the whole safety of this endpoint. Renaming moves nodes.pool,
node_groups.pool and pollers.pool in one transaction (ADR-107 Inc.2 — before core owned
the last of those, this had to refuse for any poller at all). What is still refused is a
poller that will not act on the change: one that is offline, or whose build predates
[yagra_bus::CAP_POOL_FOLLOW]. Rename out from under one of those and it goes on listening for
the old name while the new name’s nodes are published to a subject nobody subscribes to —
plain NATS discards them. That is a monitoring hole opened by a button, and nothing surfaces
it until pool_coverage’s 300s debounce.
🚨 The default pool is refused outright (ADR-107 Inc.3). Its name is a constant in the code, not a row here, so renaming the row renames the description and nothing else: every node that is in the pool only by inheritance keeps resolving to the constant and is left behind by the pollers that follow the new name — the same hole, through a different door.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The pool to update
Request Bodyrequired
Section titled “Request Bodyrequired”object
Replacement description. Omit to leave it unchanged; send null or "" to clear it.
A new name. Omit to leave it unchanged.
⚠️ Renaming moves every node and folder assignment, and is refused while any poller reports the old name — see the handler.
Examplegenerated
{ "description": "example", "name": "example"}Responses
Section titled “Responses”The pool was updated
The new name is not a valid subject 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" }}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 pool of that name is described
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" }}A poller serving the old name cannot follow the change, the new name is taken, or the pool is the default one (which cannot be renamed)
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" }}