Overview

A deliberately small surface: list servers, check status, restart, and send a command from a deploy pipeline. Anything beyond that is done in the portal.

Everything on this page is one section; the per-endpoint schemas and the playground are in the API Reference.

Requires game-servers.read to read and game-servers.manage to act. Unlike the other two areas, this one needs no activation flag.

Servers are addressed by UUID

curl https://one.terabit.io/api/v1/game-servers \
  -H "Authorization: Bearer tbk_..."

{
  "data": [
    {
      "uuid": "3f2a1c9e-5b4d-4a8e-9c7f-1d2e3a4b5c6d",
      "identifier": "a1b2c3d4",
      "name": "Survival",
      "service_id": 4821,
      "provisioned": true,
      "limits": { "memory": 8192, "cpu": 200, "disk": 51200 }
    }
  ]
}

uuid is the id every other route takes — see Conventions for the units on limits.

The list is filtered per server, so a key can legitimately receive fewer servers than the organisation owns. A shorter list than you expected is a permissions result, not a missing server.

Unprovisioned servers

provisioned is false until the node has actually built the server. Until then identifier is null, and power and command calls return 422:

{ "ok": false, "message": "This server is not provisioned yet." }

This is the state a freshly ordered server sits in, so a provisioning pipeline should poll provisioned before trying to start anything.

Live state

curl https://one.terabit.io/api/v1/game-servers/3f2a1c9e-.../ \
  -H "Authorization: Bearer tbk_..."

The detail endpoint adds state and resources, fetched live from the node. Both are null when the server is unprovisioned or the node did not answer — treat null as "unknown", not as "offline".

Power actions

curl -X POST https://one.terabit.io/api/v1/game-servers/3f2a1c9e-.../power \
  -H "Authorization: Bearer tbk_..." \
  -H "Content-Type: application/json" \
  -d '{"signal":"restart"}'

Four signals: start, stop, restart, kill.

Console commands

curl -X POST https://one.terabit.io/api/v1/game-servers/3f2a1c9e-.../command \
  -H "Authorization: Bearer tbk_..." \
  -H "Content-Type: application/json" \
  -d '{"command":"say Restarting in 5 minutes"}'

One line per call, up to 2048 characters.

There is no output in the response. This endpoint reports only whether the node accepted the command — read output from the console in the portal. If you are trying to script something that needs to read a reply, this is not the endpoint for it.

The acknowledgement envelope

Power and command both return the same two-field body rather than the data envelope the reads use — see Conventions:

{ "ok": true, "message": "" }

ok reports acceptance, not completion. A 200 on restart means the node took the instruction, not that the server is back up. Poll the detail endpoint for that.