WebSockets

A server's live output arrives over a websocket on the node, not over this API. One call mints the credential; everything after that is frames on that socket.

The same socket carries two things:

• the console — what the server process is printing right now, plus the status and resource frames that go with it, and the channel you send commands and power actions back through;
• a file tail — following any file in the server's directory, tail -f with byte offsets, so a disconnect is recoverable.

Getting a credential

curl -X POST https://one.terabit.io/api/v1/game-servers/{server}/socket \
  -H "Authorization: Bearer tbk_..."

{
  "data": {
    "socket": "wss://node-42.terabit.io:8080/api/servers/8f1c…/ws",
    "token": "eyJhbGciOi…",
    "expires_at": "2026-08-24T12:10:00+00:00",
    "permissions": ["websocket.connect", "file.read-content"]
  }
}

permissions is what your token can actually do, derived from your key's abilities — you cannot ask for more:

So a read-only key gets a socket it can listen on and not send through. And tailing needs the file-read ability, even though the tail arrives here rather than through the file endpoints.

Connecting

Open socket and authenticate in-band. There is no bearer header on a websocket:

{"event": "auth", "args": ["<token>"]}

Wait for auth success before subscribing to anything.

Tokens are short-lived. The socket emits token expiring about 60 seconds ahead — mint a fresh one and re-send auth on the same socket, and any tails already running continue untouched. A token minted before the node last restarted is refused, so mint on demand rather than caching.

Every frame in both directions has the same shape: an event name and an args array of strings. Structured payloads are JSON encoded into one of those strings rather than sent as an object.

Console

What arrives

Once authenticated, these are pushed without asking:

console output is unchanged from Pterodactyl: a bare string, no envelope. The tail events below use structured JSON instead, because a machine consumer needs to know which subscription, which bytes, and whether anything was missed — none of which a bare string can carry.

Install, backup and transfer events ride the same socket and are gated on permissions a customer key is not granted, so you will not see them.

What you can send

{"event": "send command", "args": ["say hello"]}
{"event": "set state", "args": ["restart"]}

send logs replays the recent console backlog as ordinary console output frames, which is how you fill a fresh terminal on connect. send stats asks for a stats frame immediately rather than waiting for the next one.

set state differs in one respect: an action that is not one of the four names is an error rather than a silent drop. Missing permission is still silent.

Tailing a file

args[0] is a JSON string, not an object — the frame's args is an array of strings, so the payload is encoded into one of them.

{"event": "tail file", "args": ["{\"id\":\"log\",\"path\":\"logs/latest.log\",\"lines\":150}"]}

Stop one tail, or all of them:

{"event": "untail file", "args": ["log"]}
{"event": "untail file", "args": [""]}

What you receive

tail data carries the lines and, more importantly, where they came from:

{"id":"log","seq":1,"inode":"2049:1234567",
 "offset":10420000,"next_offset":10424096,"size":10485760,
 "lines":["[12:00:01] Done (3.2s)!"],"truncated_lines":[]}

seq is monotonic per subscription across all frame types, so frame loss is detectable independently of byte arithmetic.

Resuming

This is what the byte offsets are for, and it is where an integration usually goes wrong.

1. Persist next_offset and inode from the last tail data you actually processed.
2. On reconnect, subscribe with start:"offset", that offset, and that inode.
3. Check resume in the tail started frame. rejected means you missed data, and on_mismatch decided where you landed instead.

An offset past the current end of file is refused the same way.

When you lose bytes, you are told

Losing data never passes silently. A tail gap frame names the range and why:

{"id":"log","seq":7,"reason":"rate_limit",
 "from":10424096,"to":18000000,"bytes":7575904}

One event with a discriminator rather than four, because the client-side meaning is identical in every case: your stored offset is no longer valid, here is what happened.

A tail error ends that subscription and carries a machine-readable code — not_found, is_a_directory, unsupported_file_type, denied, limit, disabled, invalid_request or io_error. Errors are scoped to the subscription; other tails and the console are unaffected.

This is the difference from the console: a tail tells you when it failed, a dropped send command does not.

What cannot be tailed

Directories, symlinks, FIFOs, sockets and devices, files matching the egg's denylist, and files whose opening bytes look binary. The denylist is re-checked when a rotation reopens the path.

Limits

The node caps how many tails one connection may hold, how fast it will feed them, and how far behind it will let you fall before signalling a gap instead. They are per-node configuration rather than a promise of this API, so treat a limit error and a rate_limit gap as normal conditions to handle rather than faults.