Move this deployment to a different release.
const url = 'https://example.com/api/v1/system/upgrade';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"include_core":true,"pollers":["example"],"target_tag":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/system/upgrade \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "include_core": true, "pollers": [ "example" ], "target_tag": "example" }'Hands the request to the privileged updater container and returns immediately — the work
outlives this process, which restarts partway through. Poll GET for the outcome.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”A request to move this deployment to a particular release.
object
Whether to replace core, the WebUI and the co-located poller — everything in core’s own compose project. Defaults to true, which is what a request that omits it has always meant, so an older client and the MCP surface keep working unchanged.
false moves only the pollers named below, and then target_tag must be the version this
core is already running: N/N-1 promises new-core-with-old-poller and says nothing about the
reverse (ADR-009), so a poller may not be sent to a release core has not reached.
Which remote-site pollers to move. Absent means every poller that can move, which is what this route did before the field existed; an empty array means none.
That distinction is the reason this is nullable rather than a plain list: [] and “not
specified” have to be different answers, or unchecking every row would silently upgrade the
whole fleet.
Ids that name nothing are ignored. Core is not addressable here — it is moved by
include_core, so naming it in this list does nothing.
The release tag to move to, e.g. v0.2.2. Must be a published release tag; the repository
it is fetched from is fixed by the deployment and cannot be set here.
Examplegenerated
{ "include_core": true, "pollers": [ "example" ], "target_tag": "example"}Responses
Section titled “Responses”Accepted; the updater will carry it out
The accepted run.
object
Correlation id for this run; it appears on the status the updater writes.
The fleet-wide maintenance window opened for the duration, or null if one could not be
opened (the run still proceeds — silencing is a courtesy, not a precondition).
The release the run targets.
Examplegenerated
{ "id": "example", "maintenance_window_id": "example", "target_tag": "example"}Not a published release tag
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 ManageSystem
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 run is already in flight
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 updater (upgrade_unsupported), the mechanism is switched off (upgrade_disabled), the updater is not running (upgrade_unavailable), or this core is not the leader
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" }}