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.

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.

curlTypeScriptPythonGo

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

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

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

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

{
  "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.

curlTypeScriptPythonGo

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

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

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

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

{
  "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), and in beta cancel_request and cancel_withdrawal (see Cancellation), reinstall (see Reinstall) and rescue (see Rescue). A reinstall or rescue started with return_password: true has one-time credentials at GET /actions/{id}/credentials (see Rescue and one-time credentials). 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.