Build a relocation archive, and — unless the mode says otherwise — send it and restore it.

POST

/api/v1/system/relocation

curl --request POST \
  --url https://example.com/api/v1/system/relocation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "auth": { "kind": "password", "secret": "example", "sudo_password": "example" }, "include_images": true, "include_metrics": true, "include_tier2": true, "install_docker": true, "mode": "archive", "target": { "dir": "example", "host": "example", "port": 1, "user": "example" } }'

Hands the request to the privileged updater and returns immediately; the work outlives this request by minutes. Poll GET for the outcome.

Authorizations

• bearer

Request Body^required

Media typeapplication/json

What the operator asked for.

object

auth

One of:

null

null

object

Required for preflight and push. Never stored, never logged, never returned.

object

kind

required

password or key.

string

Allowed values: password key

secret

required

The password, or the OpenSSH private key, depending on kind.

string

sudo_password

The sudo password, when it differs from the login password. Only ever needed to install Docker on the target.

string | null

include_images

Carry the three Yagra images. Off by default — the new host usually pulls them. Needed when it cannot reach the registry, or when this deployment runs images from a private one.

boolean

include_metrics

Carry the metrics (VictoriaMetrics). On by default — a monitoring system that arrives with no history is a new deployment, not a moved one.

boolean

include_tier2

Carry the events and flows (VictoriaLogs, ClickHouse). On by default, and the one option with a running cost: both stores are stopped for the minutes the copy takes.

boolean

install_docker

Install Docker on the target if it has none. On by default; needs sudo and internet there, and runs the official get.docker.com script as root.

boolean

mode

archive builds one and stops, preflight only checks the target, push does everything.

string

Allowed values: archive preflight push

target

One of:

null

null

object

Required for preflight and push.

object

dir

A directory name — not a path — created under that account’s home.

string

host

required

Host name or IP of the new server.

string

port

SSH port. 22 unless the site moved it.

integer format: int32

user

required

The account to log in as. It needs sudo only when Docker has to be installed.

string

Responses

202

Accepted; the updater will carry it out

Media typeapplication/json

The run id, so the page can tell its own request from one another admin started.

object

id

required

string

Example^generated

{
  "id": "example"
}

400

A malformed target, or a push with no credentials

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, ManageCredentials or ViewAudit

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

A relocation or an upgrade is already running

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

The mechanism is absent, switched off, or too old for this command

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

507

Not enough free disk space to build the archive

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