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

> **Beta.** Reinstall through the API is built but switched off. RedSwitches decides when to switch it on; until then `POST /servers/{id}/reinstall` answers `503 unavailable` and the `reinstall` permission is not offered when you make a key. The endpoints and fields below are the beta contract and may still change.

**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](rescue.md#read-the-credentials-once).
- The owner is emailed when a reinstall starts and when it finishes.
- The reinstall is an [action](actions.md) 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.

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

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

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

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

```json
{
  "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`:

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

## Start a reinstall

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

| Body field | Required | Rule |
|---|---|---|
| `os_id` | yes | An image id from `GET /servers/{id}/os`: `img_` followed by 1 to 64 letters, digits, `_`, `.` or `-`. These are not the `os_…` ids of an order: an `os_…` id here is `400 invalid_body`. An OS that is not on the server's list is `422 not_supported`. |
| `ssh_key_ids` | yes | 1 to 10 saved key ids, such as `["sshkey_7"]`. A key that is not saved on the account is `422 invalid_ssh_key`. |
| `hostname` | no | Up to 253 characters: lower-case letters, digits, dots and dashes. |
| `raid` | no | `none`, `raid0`, `raid1` or `raid10`. Only some servers offer a choice; elsewhere it is `422 not_supported`. |
| `return_password` | no | `true` or `false` (default). With `true`, the password can be read once from `GET /actions/{id}/credentials` after the reinstall is done, within 24 hours. Store it at once. |

```bash
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"}'
```

```ts
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);
```

```python
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)
```

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

```json
{
  "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

| Status | Code | Meaning |
|---|---|---|
| 403 | `permission_denied` | The key does not have `reinstall`, or this server is not on its server list. |
| 404 | `not_found` | No such server on this account. |
| 409 | `server_busy` | Another action, install or rescue is running on the server. |
| 409 | `server_not_active` | The server is not active. |
| 422 | `not_supported` | The OS is not on the server's list, or the server does not offer the chosen `raid`. |
| 422 | `invalid_ssh_key` | A key id is not saved on the account. |
| 429 | `action_limit` | Over the daily ceiling: 2 per server (`details.per: "server_day"`) or 5 per account (`account_day`). |
| 503 | `unavailable` | Reinstall is switched off, or RedSwitches has reinstalls paused. |