Managing servers

Server states

Status	Meaning
`active`	Running normally. Reboot and re-image are available.
`rebooting`	A reboot is in progress. Returns to `active` once the machine has booted back into its OS.
`reimaging`	A re-image is in progress.
`powering-on`	Being powered on. Becomes `active` once the machine has booted into its OS.
`powering-off`	Being powered off.
`off`	Powered down. Power it back on from the dashboard or the API.
`error`	The last operation failed. Reboot and re-image are still available — this is the recovery path.
`retired`	No longer in service.

Reboot and re-image are accepted only from active and error. Anything else returns 409 server-not-ready, and a machine that already has an operation running returns 409 server-busy — with the running operation’s id as action_id, so you can poll it rather than guess when to retry.

off, powering-on and powering-off appear when a server has been powered down rather than restarted — by you, or by us during maintenance. Actions of kind power-on and power-off show up in the action list alongside reboot and reimage.

Power

Power on and Power off sit next to Reboot on the servers page of the dashboard. Powering off asks the operating system to shut down cleanly and forces it off if it does not comply; nothing on the disks is erased either way. Powering on is offered from off and error, powering off from active and error — a faulted server offers both, because its real power state is unknown to us.

Both are also available from the API, which applies the same rules:


curl -X POST https://braesystems.com/api/v1/servers/$SERVER_ID/power \
  -H "Authorization: Bearer bs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"direction":"off"}'


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main(): Promise<void> {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/power`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ direction: "off" }),
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = (await response.json()) as { data: unknown };
  console.log(data);
}
 
void main();


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main() {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/power`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ direction: "off" }),
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = await response.json();
  console.log(data);
}
 
void main();


import os
 
import requests
 
api_key = "bs_live_..."
server_id = os.environ["SERVER_ID"]
 
response = requests.post(
    f"https://braesystems.com/api/v1/servers/{server_id}/power",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"direction": "off"},
    timeout=30,
)
response.raise_for_status()
 
print(response.json()["data"])


package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
 
func main() {
	apiKey := "bs_live_..."
	serverID := os.Getenv("SERVER_ID")
 
	body := strings.NewReader(`{"direction":"off"}`)
 
	req, err := http.NewRequest("POST", "https://braesystems.com/api/v1/servers/" + serverID + "/power", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
 
	fmt.Println(resp.Status, string(out))
}

direction is on or off. It answers 202 with an action to poll, the way reboot and re-image do. Asking for a state the server is already in is a 409 rather than a quiet success, so a script can tell “it was already off” from “it is off because you asked”.

A power-on is not finished when the machine has power. The server stays powering-on until its management controller reports that firmware self-test has finished and control has passed to the operating system — the point at which the next reboot is safe to accept, and typically under a minute before SSH answers. Self-test alone takes a few minutes on this hardware, so expect a power-on to take longer than a power-off. If the controller reports no boot within fifteen minutes the action fails and the server is marked error; the message says whether the boot never started or stalled part-way, and at which stage.

Remember that reboot and re-image need a running server: both are accepted only from active and error, so a server you have powered off has to be powered back on before either is available.

Asynchronous operations

Reboot and re-image operations return 202 with an action, then run in the background. Poll GET /api/v1/actions/{id} until status is succeeded or failed; a failure carries the reason in error.

This is the one workflow worth writing out end to end, because it is the shape every power operation takes: start it, then follow the action it hands back.


ACTION=$(curl -s -X POST "https://braesystems.com/api/v1/servers/$SERVER_ID/reboot" \
  -H "Authorization: Bearer bs_live_..." | jq -r .data.id)
 
while :; do
  STATUS=$(curl -s "https://braesystems.com/api/v1/actions/$ACTION" \
    -H "Authorization: Bearer bs_live_..." | jq -r .data.status)
  echo "$STATUS"
  case "$STATUS" in succeeded|failed) break ;; esac
  sleep 10
done


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
// The fields this walkthrough reads. The response carries more — kind,
// server_id, simulated, timestamps — see the API reference.
interface Action {
  id: string;
  status: "queued" | "running" | "succeeded" | "failed";
  error: string | null;
}
 
async function call(path: string, method: string = "GET"): Promise<Action> {
  const response = await fetch(`https://braesystems.com/api/v1${path}`, {
    method,
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
  const { data } = (await response.json()) as { data: Action };
  return data;
}
 
async function main(): Promise<void> {
  const started = await call(`/servers/${serverId}/reboot`, "POST");
 
  for (;;) {
    const action = await call(`/actions/${started.id}`);
    console.log(action.status);
    if (action.status === "succeeded") return;
    if (action.status === "failed") throw new Error(action.error ?? "reboot failed");
    await new Promise((resolve) => setTimeout(resolve, 10_000));
  }
}
 
void main();


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function call(path, method = "GET") {
  const response = await fetch(`https://braesystems.com/api/v1${path}`, {
    method,
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
  const { data } = await response.json();
  return data;
}
 
async function main() {
  const started = await call(`/servers/${serverId}/reboot`, "POST");
 
  for (;;) {
    const action = await call(`/actions/${started.id}`);
    console.log(action.status);
    if (action.status === "succeeded") return;
    if (action.status === "failed") throw new Error(action.error ?? "reboot failed");
    await new Promise((resolve) => setTimeout(resolve, 10_000));
  }
}
 
main();


import os
import time
 
import requests
 
api_key = "bs_live_..."
server_id = os.environ["SERVER_ID"]
base = "https://braesystems.com/api/v1"
headers = {"Authorization": f"Bearer {api_key}"}
 
started = requests.post(f"{base}/servers/{server_id}/reboot", headers=headers, timeout=30)
started.raise_for_status()
action_id = started.json()["data"]["id"]
 
while True:
    action = requests.get(f"{base}/actions/{action_id}", headers=headers, timeout=30)
    action.raise_for_status()
    data = action.json()["data"]
    print(data["status"])
    if data["status"] == "succeeded":
        break
    if data["status"] == "failed":
        raise RuntimeError(data["error"] or "reboot failed")
    time.sleep(10)


package main
 
import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)
 
type envelope struct {
	Data struct {
		ID     string `json:"id"`
		Status string `json:"status"`
		Error  string `json:"error"`
	} `json:"data"`
}
 
func call(apiKey, method, url string) (envelope, error) {
	var result envelope
 
	req, err := http.NewRequest(method, url, nil)
	if err != nil {
		return result, err
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return result, err
	}
	defer resp.Body.Close()
 
	if resp.StatusCode >= 300 {
		return result, fmt.Errorf("brae api %s", resp.Status)
	}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return result, err
	}
	return result, nil
}
 
func main() {
	apiKey := "bs_live_..."
	serverID := os.Getenv("SERVER_ID")
	base := "https://braesystems.com/api/v1"
 
	started, err := call(apiKey, "POST", base+"/servers/"+serverID+"/reboot")
	if err != nil {
		panic(err)
	}
 
	for {
		action, err := call(apiKey, "GET", base+"/actions/"+started.Data.ID)
		if err != nil {
			panic(err)
		}
		fmt.Println(action.Data.Status)
		if action.Data.Status == "succeeded" {
			return
		}
		if action.Data.Status == "failed" {
			panic(action.Data.Error)
		}
		time.Sleep(10 * time.Second)
	}
}

Actions you did not start

The 202 is the only place an action id is handed out, and it goes to whoever sent the command. If that was another client, the dashboard, or us — or your own client lost it — the server’s action list is the way back to it:


curl https://braesystems.com/api/v1/servers/$SERVER_ID/actions \
  -H "Authorization: Bearer bs_live_..."


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main(): Promise<void> {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/actions`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = (await response.json()) as { data: unknown };
  console.log(data);
}
 
void main();


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main() {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/actions`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = await response.json();
  console.log(data);
}
 
void main();


import os
 
import requests
 
api_key = "bs_live_..."
server_id = os.environ["SERVER_ID"]
 
response = requests.get(
    f"https://braesystems.com/api/v1/servers/{server_id}/actions",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30,
)
response.raise_for_status()
 
print(response.json()["data"])


package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
)
 
func main() {
	apiKey := "bs_live_..."
	serverID := os.Getenv("SERVER_ID")
 
	req, err := http.NewRequest("GET", "https://braesystems.com/api/v1/servers/" + serverID + "/actions", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
 
	fmt.Println(resp.Status, string(out))
}

It returns the hundred most recent actions on the server, newest first, whoever started them. A 409 server-busy refusal also names the running operation directly in action_id, so a refused command already tells you what to poll.

The `simulated` field

Every action carries a simulated boolean. It is true when the action ran against a test server rather than hardware — the machines in a development environment, which report an outcome after a short delay without anything being touched.

On a real server it is always false. It exists so a simulated success can never be mistaken for a real power cycle after the fact.

Reboot


curl -X POST https://braesystems.com/api/v1/servers/$SERVER_ID/reboot \
  -H "Authorization: Bearer bs_live_..."


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main(): Promise<void> {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/reboot`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = (await response.json()) as { data: unknown };
  console.log(data);
}
 
void main();


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main() {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/reboot`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = await response.json();
  console.log(data);
}
 
void main();


import os
 
import requests
 
api_key = "bs_live_..."
server_id = os.environ["SERVER_ID"]
 
response = requests.post(
    f"https://braesystems.com/api/v1/servers/{server_id}/reboot",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30,
)
response.raise_for_status()
 
print(response.json()["data"])


package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
)
 
func main() {
	apiKey := "bs_live_..."
	serverID := os.Getenv("SERVER_ID")
 
	req, err := http.NewRequest("POST", "https://braesystems.com/api/v1/servers/" + serverID + "/reboot", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
 
	fmt.Println(resp.Status, string(out))
}

A graceful restart is attempted first, which asks the operating system to shut down cleanly. The server’s management controller records every boot, and we watch those records rather than the power light: a reboot is finished when the controller shows a new boot that has passed firmware self-test and handed control to the operating system. If it shows no sign of a boot starting within five minutes, the operating system has ignored the request, and we escalate to a forced restart. If there is still no completed boot after fifteen minutes in total, the action fails.

The server stays rebooting throughout and returns to active at that hand-off, which is typically under a minute before SSH answers again — so a second reboot is accepted only once the first has actually finished booting.

The failure message distinguishes two cases, because they call for different responses:

“Server never restarted” — neither the graceful request nor the forced restart after it took the machine down. It is still running as it was; contact us.
“Server restarted, but did not hand off to the operating system” — it went down and stalled in self-test or the boot loader, at the stage the message names. Reboot it once more; if it stalls again, contact us.

Re-image

Re-imaging erases every disk on the server. All data on it is destroyed and there is no undo.


curl -X POST https://braesystems.com/api/v1/servers/$SERVER_ID/reimage \
  -H "Authorization: Bearer bs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"image":"ubuntu-24-04"}'


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main(): Promise<void> {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/reimage`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ image: "ubuntu-24-04" }),
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = (await response.json()) as { data: unknown };
  console.log(data);
}
 
void main();


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main() {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/reimage`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ image: "ubuntu-24-04" }),
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = await response.json();
  console.log(data);
}
 
void main();


import os
 
import requests
 
api_key = "bs_live_..."
server_id = os.environ["SERVER_ID"]
 
response = requests.post(
    f"https://braesystems.com/api/v1/servers/{server_id}/reimage",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"image": "ubuntu-24-04"},
    timeout=30,
)
response.raise_for_status()
 
print(response.json()["data"])


package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
 
func main() {
	apiKey := "bs_live_..."
	serverID := os.Getenv("SERVER_ID")
 
	body := strings.NewReader(`{"image":"ubuntu-24-04"}`)
 
	req, err := http.NewRequest("POST", "https://braesystems.com/api/v1/servers/" + serverID + "/reimage", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
 
	fmt.Println(resp.Status, string(out))
}

image is a slug from GET /api/v1/images. Optionally pass ssh_key_ids to install a specific subset of your keys; omit it and every key on the account is installed.

A re-image with no keys is rejected before anything is erased — a rebuilt server with no key would be one you could not log into.

What happens

We validate the request: the image exists, the keys belong to your account, and there is at least one of them.
The installer image and a configuration volume carrying your SSH keys are mounted over the server’s virtual media.
The machine is set to boot from the installer once, then power-cycled.
Every disk in the server is erased, including data drives that are not the boot volume.
The operating system is installed on the boot volume and reports back when it finishes.
Both volumes are unmounted and the server reboots into the new system.
The server returns to active once its management controller shows that first boot handing off to the new system — with the keys you chose for the re-image, from that moment on.

Typically fifteen to forty minutes depending on the image. If the installer has not reported back within two hours the action fails and the server is marked error. If it reports back but no completed boot follows within fifteen minutes, the action fails too: the image is installed, and the message says whether the server never left the installer or stalled in self-test on the way up.

Step 4 erases partition tables and filesystem signatures on every disk, which makes the data unreachable by any normal means. It is not a certified secure erase — the blocks themselves are not overwritten, so specialist recovery of a physically obtained drive is not ruled out. Tell us if you need a certified wipe before hardware leaves your control.

Listing addresses

Addresses are also available on their own:


curl https://braesystems.com/api/v1/servers/$SERVER_ID/ips \
  -H "Authorization: Bearer bs_live_..."


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main(): Promise<void> {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/ips`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = (await response.json()) as { data: unknown };
  console.log(data);
}
 
void main();


const apiKey = "bs_live_...";
const serverId = process.env.SERVER_ID;
 
async function main() {
  const response = await fetch(`https://braesystems.com/api/v1/servers/${serverId}/ips`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });
 
  if (!response.ok) {
    throw new Error(`Brae API ${response.status}: ${await response.text()}`);
  }
 
  const { data } = await response.json();
  console.log(data);
}
 
void main();


import os
 
import requests
 
api_key = "bs_live_..."
server_id = os.environ["SERVER_ID"]
 
response = requests.get(
    f"https://braesystems.com/api/v1/servers/{server_id}/ips",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30,
)
response.raise_for_status()
 
print(response.json()["data"])


package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
)
 
func main() {
	apiKey := "bs_live_..."
	serverID := os.Getenv("SERVER_ID")
 
	req, err := http.NewRequest("GET", "https://braesystems.com/api/v1/servers/" + serverID + "/ips", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
 
	fmt.Println(resp.Status, string(out))
}


{
  "data": [
    {
      "address": "203.0.113.11",
      "version": 4,
      "kind": "public"
    },
    {
      "address": "2001:db8:1::11",
      "version": 6,
      "kind": "public"
    }
  ]
}

This endpoint returns one flat list rather than the separate ipv4 and ipv6 arrays a server carries, so version is what tells the two families apart here.

Addresses survive a re-image — rebuilding a server does not change how you reach it.