# Actions and power

Power a server on, off or reboot it, and follow the action until it has finished. Power needs `power`; reading an action needs `read`. For patterns and advice see the [Power and actions guide](guide-power.md).

## Power a server

`POST /servers/{id}/power` asks for a power action. Needs an `Idempotency-Key`. The action is queued and carried out within moments; the request does not wait for it.

| Body field | Rule |
|---|---|
| `action` | `on`, `off` or `reboot`. Nothing else is accepted. |

```bash
curl -sS -X POST https://api.redswitches.com/v1/servers/srv_123/power \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"action":"reboot"}'
```

```ts
const action = await rs.power.run("srv_123", { action: "reboot" });
const done = await rs.actions.wait(action.id);
```

```python
action = client.power.run("srv_123", action="reboot")
done = client.actions.wait(action.id)
```

```go
action, err := client.Power.Run(ctx, "srv_123", "reboot")
if err != nil {
	log.Fatal(err)
}
done, err := client.Actions.Wait(ctx, action.ID)
```

```json
{
  "id": "act_42",
  "kind": "power",
  "server_id": "srv_123",
  "action": "reboot",
  "state": "queued",
  "poll_after": 10
}
```

The answer is `202 Accepted` with the new action.

### Power errors

| Status | Code | Meaning |
|---|---|---|
| 403 | `permission_denied` | The key does not have `power`, or this server is not on its server list. |
| 403 | `power_paused` | API power is paused for the account (for example after a burst of power-offs). Staff have been told. |
| 404 | `not_found` | No such server on this account. |
| 409 | `server_busy` | Another action on this server is queued, running or unsettled, or the server is being delivered or installed, or a change started in the client area is running. |
| 409 | `server_not_active` | The server is pending, suspended or ended. A suspended server cannot be powered on through the API. |
| 422 | `not_supported` | This server cannot be powered through the API. |
| 429 | `action_limit` | Over a ceiling: 6 actions per server or 20 per account in a rolling hour. `details.limit` and `details.per` (`server_hour` or `account_hour`) say which. |

## Get an action

`GET /actions/{id}` returns an action of your account, made with any of its keys.

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

```ts
const action = await rs.actions.get("act_42");
```

```python
action = client.actions.get("act_42")
```

```go
action, err := client.Actions.Get(ctx, "act_42")
```

```json
{
  "id": "act_42",
  "kind": "power",
  "server_id": "srv_123",
  "action": "reboot",
  "state": "done",
  "reason": null,
  "created": "2026-11-15T09:30:00Z",
  "started": "2026-11-15T09:30:04Z",
  "finished": "2026-11-15T09:30:07Z"
}
```

| Field | Type | Meaning |
|---|---|---|
| `id` | string | `act_<n>`. |
| `kind` | string or null | `power`, `label`, `rdns`, `ssh_key_add` or `ssh_key_remove`. |
| `server_id` | string or null | The server, when the action is about one. |
| `action` | string or null | For power: `on`, `off` or `reboot`. Otherwise null. |
| `state` | string | `queued`, `running`, `done`, `failed` or `unknown`. |
| `reason` | string or null | Only when `failed` or `unknown`. See below. |
| `created`, `started`, `finished` | string or null | Times in UTC. |

Power, reinstall, rescue and some reverse DNS changes answer with an action id. Rename, SSH key changes and cancellation requests answer with their result directly.

### States

| State | Meaning |
|---|---|
| `queued` | Accepted, not started yet. An action that has not started within 15 minutes expires (`failed`, reason `expired`). |
| `running` | Being carried out now. |
| `done` | Finished. |
| `failed` | Did not happen. Nothing was changed. |
| `unknown` | Sent, but no clear answer came back. RedSwitches staff check and settle it. Until then no other API power action runs on that server. |

### Reasons

| Reason | Meaning |
|---|---|
| `expired` | Not started within 15 minutes. |
| `server_busy` | The server was being delivered, installed or changed when the action came up. |
| `server_not_active` | The server was no longer active. |
| `server_changed` | The server's assignment changed since the action was accepted. |
| `power_paused` | API power was paused for the account meanwhile. |
| `not_supported` | This server cannot do that through the API. |
| `provider_refused` | The server's network refused the command. |
| `no_answer` | No answer in time. |
| `provider_unavailable` | The server's state could not be read before the call. |
| `settled_by_staff` | Staff settled an unknown action as failed. |
| `key_no_longer_allowed` | The key was revoked, lost the permission, or no longer covers the server. |

Other kinds of action: `rdns` (reverse DNS changes carried out as actions, see [Reverse DNS](rdns.md)), and in beta `cancel_request` and `cancel_withdrawal` (see [Cancellation](cancellation.md)), `reinstall` (see [Reinstall](reinstall.md)) and `rescue` (see [Rescue](rescue.md)). A reinstall or rescue started with `return_password: true` has one-time credentials at `GET /actions/{id}/credentials` (see [Rescue and one-time credentials](rescue.md#read-the-credentials-once)). More reasons: `ip_not_on_server` (the IP was no longer on the server), `paused` (RedSwitches has reinstalls and rescues paused) and `not_tracked` (the server accepted the command but its progress could not be recorded; state `unknown` until RedSwitches settles it) and `password_unavailable` (a reinstall or rescue started, but the password you asked for could not be kept; staff will set one for you). A `done` action has no reason, except `password_unavailable` or `not_tracked`.