What the relocation mechanism can do, and what it is doing.
const url = 'https://example.com/api/v1/system/relocation';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/api/v1/system/relocation \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Responses
Section titled “Responses”The mechanism’s state and the current run
Everything the relocation page needs in one read.
object
Whether a relocation can be started from here: the updater is deployed, alive, the operator’s switch is on, and it supports the command.
Roughly how large the archive will be. ⚠️ Partial — the database plus the metrics. Core cannot see the event, flow or image volumes; only the sidecar can, and its check is the one that can stop a run.
Free bytes on the filesystem holding the hand-off volume.
estimate_bytes doubled: the copy, and the tar of the copy.
The current or most recent run.
object
Whether this run installed Docker on the target.
The archive on this host, while there is one.
Unix seconds, once it has ended.
The target’s SSH host-key fingerprint, once it has been seen.
The run id core minted.
Whether the three Yagra images were included.
What to show the operator about this stage.
Whether metrics were included.
The mode the request asked for, as its token.
The account that asked for it.
Its size in bytes.
Which part of the work this is: start, preflight, docker, backup, files,
images, tier2, archive, push, or validate for a request refused before it began.
Unix seconds.
requested · running · done · failed.
The host being moved to, absent for a plain archive.
Where the new deployment answers, once it does.
Whether the event and flow stores were included.
Whether this deployment’s updater declares the command at all. false on an updater that
predates ADR-121 — the next upgrade recreates it.
The updater container’s own state, from the same reading the Upgrade page uses.
object
Whether it will install an uploaded image archive. Off unless the host’s compose file turns it on — it is the only path that can bring an image this deployment never named onto the host, so it is gated separately from the mechanism as a whole (ADR-050 Increment 3).
The largest archive core will accept, in bytes. Present whenever allow_bundle is, so the
UI can refuse an oversized file before spending an hour uploading it.
How often it re-checks the registry, in seconds.
Whether its last report is recent enough for it to be considered alive.
Whether this deployment has an upgrade mechanism at all — that is, whether the host wired
the hand-off directory in. false describes how the deployment was installed rather than
anything that went wrong: upgrading from the WebUI needs a container composition that
carries the privileged updater alongside core, so a native installation, or a composition
that does not ship it, cannot offer it. The command-line upgrade path is unaffected.
Unix seconds of its last report.
Whether the sidecar has seen the switch turned off. Distinct from upgrade_enabled, which
is what this deployment stored: while the two disagree the change has not reached the
sidecar yet, which takes at most one of its beats.
Whether the updater has ever reported. Meaningful only where installed is true, and there
it means the container is missing or has not finished starting — a fault, not a property of
the deployment.
The image repository it is pinned to. Fixed by the host environment and not settable over this API.
The operator’s switch, as stored. Shared with the upgrade mechanism: one sidecar, one switch — turning upgrades off turns this off too, which is deliberate.
Examplegenerated
{ "archive": { "filename": "example", "modified_at": 1, "size_bytes": 1 }, "enabled": true, "estimate_bytes": 1, "free_bytes": 1, "needed_bytes": 1, "run": { "docker_installed": true, "filename": "example", "finished_at": 1, "host_key_fingerprint": "example", "id": "example", "images": true, "message": "example", "metrics": true, "mode": "example", "requested_by": "example", "size_bytes": 1, "stage": "example", "started_at": 1, "state": "example", "target_host": "example", "target_url": "example", "tier2": true }, "supported": true, "updater": { "allow_bundle": true, "bundle_max_bytes": 1, "check_interval_secs": 1, "fresh": true, "installed": true, "last_seen": 1, "paused": true, "present": true, "repo": "example" }, "upgrade_enabled": true}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" }}No upgrade mechanism is installed (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" }}