`DELETE /api/v1/pools/{name}` — stop describing a pool.

DELETE

/api/v1/pools/{name}

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

⚠️ Refused while anything still names it, and that is not caution: the name is derived from nodes, folders and pollers as well as from this table, so deleting the row of a pool still in use would not free the name. The pool would keep appearing in the picker with its description gone — a delete that appears to succeed and changes nothing.

Authorizations

• bearer

Parameters

Path Parameters

name

required

string

The pool to delete

Responses

204

The pool is no longer described

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

Example^generated

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

403

Role lacks the ManageSystem 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

Example^generated

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

404

No pool of that name is described

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

Example^generated

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

409

Nodes, folders or pollers still name this pool

Media typeapplication/json

What a refusal names, so the operator knows which thing to move first.

object

folders

required

Folders assigning this pool.

integer format: int64

nodes

required

Nodes assigned to this pool directly.

integer format: int64

pollers

required

Poller ids reporting this pool, or recorded as heading to it.

Array<string>

Example^generated

{
  "folders": 1,
  "nodes": 1,
  "pollers": [
    "example"
  ]
}

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

Example^generated

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