Managing servers

Server states

Status	Meaning
`provisioning`	Being set up by us. Not yet operable.
`active`	Running normally. Reboot and re-image are available.
`rebooting`	A reboot is in progress.
`reimaging`	A re-image is in progress.
`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.

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;
 
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)
	}
}

The `simulated` field

Every action carries a simulated boolean. It is true when the action ran against a short-circuited environment — a preview deployment, where hardware operations report success after a short delay without touching a machine.

In production 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. If the machine has not returned after roughly five minutes we escalate to a forced restart. If it still has not returned after ten, the action fails.

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

“Server never left power state On” — the restart was ignored. Investigate the operating system.
“Server did not return to power state On” — it went down and did not come back. Investigate the hardware, or 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 returns to active.

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.

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.