Reinstall

List the operating systems a server can be reinstalled with, and start a reinstall that installs your SSH keys. Listing needs read; reinstalling needs the reinstall permission.

A reinstall wipes the server's disks. Everything on it is lost.

How it works

• The reinstall permission is chosen when a key is made, only while reinstall is on, and is limited by the key's server list, like power.
• The server is installed with the SSH keys you choose: at least one, at most 10.
• No password is returned unless you ask for it. By default, if a root password is set, it is emailed to the account owner, as for a reinstall started in the client area. With "return_password": true it can be read once from GET /actions/{id}/credentials after the reinstall is done: see Rescue and one-time credentials.
• The owner is emailed when a reinstall starts and when it finishes.
• The reinstall is an action of kind reinstall. Follow it with GET /actions/{id}. States are the same as for power.
• At most 2 reinstalls per server and 5 per account per day. Not while another action or install runs on the server, or while it is in rescue mode.
• An unknown reinstall blocks further actions on that server until RedSwitches settles it, like power.

List operating systems

GET /servers/{id}/os returns the images this server can be reinstalled with. The list is read from what was last collected for the server, never live.

curl -sS https://api.redswitches.com/v1/servers/srv_123/os \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY"

const { data: images } = await rs.servers.os("srv_123");

images = client.servers.os("srv_123").data

images, err := client.Servers.OS(ctx, "srv_123")

{
  "server_id": "srv_123",
  "as_of": "2026-11-15T09:00:00Z",
  "data": [
    { "id": "img_1042", "name": "Ubuntu 24.04" },
    { "id": "img_1043", "name": "Debian 12" }
  ],
  "reason": null
}

Until the list has been read for the server's current hardware, data and as_of are null and reason is not_collected:

{ "server_id": "srv_123", "as_of": null, "data": null, "reason": "not_collected" }

Start a reinstall

POST /servers/{id}/reinstall. Needs an Idempotency-Key.

curl -sS -X POST https://api.redswitches.com/v1/servers/srv_123/reinstall \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"os_id":"img_1042","ssh_key_ids":["sshkey_7"],"hostname":"web-1.example.com"}'

const action = await rs.servers.reinstall("srv_123", {
  os_id: "img_1042",
  ssh_key_ids: ["sshkey_7"],
  hostname: "web-1.example.com",
});
await rs.actions.wait(action.id);

action = client.servers.reinstall(
    "srv_123", os_id="img_1042", ssh_key_ids=["sshkey_7"], hostname="web-1.example.com"
)
client.actions.wait(action.id)

action, err := client.Servers.Reinstall(ctx, "srv_123", &redswitches.ReinstallRequest{
	OSID: "img_1042", SSHKeyIDs: []string{"sshkey_7"}, Hostname: "web-1.example.com",
})

{
  "id": "act_43",
  "kind": "reinstall",
  "server_id": "srv_123",
  "os_id": "img_1042",
  "state": "queued",
  "return_password": false,
  "poll_after": 30
}

The answer is 202 Accepted.

Errors