Issue a poller a bus token of its own and return the archive its site needs.

POST

/api/v1/pollers/{id}/token

curl --request POST \
  --url https://example.com/api/v1/pollers/example/token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "host": "example", "pool": "example", "port": 1, "self_upgrade": true }'

The response is the archive, not the token: this is the only moment the token exists in the clear — only its digest is stored — and everything else the site needs is derivable here. See poller_bundle.rs.

Creates the inventory row when the poller has not connected yet, which is what lets a site be prepared before anything is running there. That is also what makes the callout able to refuse an unregistered id: something has to be able to register one first.

Authorizations

• bearer

Parameters

Path Parameters

id

required

string

Poller id

Request Body^required

Media typeapplication/json

What a new site needs, beyond its own name.

object

host

The hostname or IP address the site will dial. Must be one the bus certificate covers, or the site’s connection fails with nothing visible centrally. Defaults to the first name on the certificate that is not an internal one.

string | null

pool

The pool this poller serves. Only used when the poller is not in the inventory yet — an existing poller keeps the pool it reported.

string | null

port

The bus port at that address. Defaults to 4222.

integer | null format: int32

self_upgrade

Whether this site should upgrade itself when the deployment does (ADR-051 Inc.4).

Defaults to true, which is why it is an Option rather than a plain bool: false and “the caller said nothing” have to be told apart, and #[serde(default)] on a bool gives both of them false. An older client that has never heard of this field therefore gets the same archive a current one does with the box ticked.

It becomes a COMPOSE_PROFILES line in the generated .env, which is the only file at the site that an upgrade does not replace — so the answer given here survives the site’s own upgrades, and can be changed there without waiting for a new bundle.

boolean | null

Example^generated

{
  "host": "example",
  "pool": "example",
  "port": 1,
  "self_upgrade": true
}

Responses

200

A gzipped tar archive holding the site’s .env, the bus certificate, the composition and a README

Media typeapplication/gzip

400

The poller id is not usable as a bus identity, the pool name is not a valid subject token or is longer than 63 characters, or no address was given and none could be derived

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"
  }
}

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 ManageSystem

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"
  }
}

503

Skeleton mode, or this deployment has no bus certificate yet

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"
  }
}