Skip to content
Yagra

Install a release from an uploaded image archive, for a site with no reachable registry.

POST
/api/v1/system/upgrade/bundle
curl --request POST \
  --url 'https://example.com/api/v1/system/upgrade/bundle?target_tag=example' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/octet-stream' \
  --data '[ 1 ]'

The body is the output of docker save for the release’s three images. Nothing else about the upgrade changes: the same backup is taken, the same composition is installed from the target image, and the same provenance check decides whether it worked. Returns as soon as the archive is stored; poll GET /api/v1/system/upgrade for the outcome.

Accepting archives is opt-in on the deployment and off by default, so this answers 503 until an operator has turned it on at the host.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
target_tag
required
string

The release the archive contains, e.g. v0.2.2. The updater checks it against the images the archive actually carries, so a bundle cannot quietly install a different version.

Request Bodyrequired

Section titled “Request Bodyrequired”

A docker save archive holding the core, poller and web images for the target release

Media typeapplication/octet-stream
Array<integer>

Responses

Section titled “Responses”

202

Section titled “202”

Archive stored; the updater will install it

Media typeapplication/json

The accepted run.

object
id
required

Correlation id for this run; it appears on the status the updater writes.

string
maintenance_window_id

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).

string | null
target_tag
required

The release the run targets.

string
Examplegenerated
{
  "id": "example",
  "maintenance_window_id": "example",
  "target_tag": "example"
}

400

Section titled “400”

Not a published release tag

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

409

Section titled “409”

A run is already in flight

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

413

Section titled “413”

The archive is larger than this deployment accepts

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Section titled “503”

This deployment has no updater (upgrade_unsupported), the mechanism is switched off (upgrade_disabled), the updater is not running (upgrade_unavailable) or does not accept archives (bundle_not_allowed), or this core is not the leader

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

507

Section titled “507”

Not enough free space to store the archive and unpack it

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}