Organization API: Customer Portal: Servers

Part of Customer Portal.

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/auto-backups

This server's automatic backups: whether it has them, whether they run and the last backup.

A server, free or paid, has them while it carries the Automatic Server Backups add-on. We take one snapshot a day (frequency) and keep the newest keep. They count against the customer's snapshot storage. available says whether the server has them, enabled whether they are running, and paused whether the customer switched them off. reason is one word for why there are none or why the last run took none: not_included (an add-on the customer can buy, on a free server too), snapshots_off or no_room (the snapshot storage is full), and message says it in a sentence. last_backup is the newest finished one, with its snapshot id, created_at and size_bytes. A shared customer needs snapshot.read.

PUT /api/v1/orgs/{org_slug}/portal/servers/{uuid}/auto-backups

Pause or resume this server's automatic backups, and answer as GET does.

Pausing keeps the add-on and its billing, and keeps the backups already taken. Answers 409, naming why, when the server does not have automatic backups. Only the server's owner can change it, not a shared customer.

application/json (required)

POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/command

application/json

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/console

The newest lines of the server's console, as the Console tab shows them, without colour codes.

lines is a list of text lines, oldest first. It works for every game, Bedrock included, which has no logs/latest.log. A server that is not running answers with what the node kept from its last run, which may be empty. Needs the control.console permission on a shared server. 409 when the node no longer has the server.

POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/keep

Tell us this world is still wanted, and lift a hold if one is on.

One endpoint for both halves of the inactivity ladder: the nudge's "keep it" link and the suspension's "reactivate". They differ only in whether the server is currently suspended, and asking the customer to understand that distinction would be asking them to understand our sweep.

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing

Public-list visibility and tags for the Server Settings tab.

PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing

Toggle public-list visibility and replace the listing tags.

application/json (required)

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/permissions

POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/power

application/json (required)

POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/reinstall

Wipe server files and re-run the template install script + verify.

On a server that installed, this deletes every file, so it is confirmed the way every other wipe is: confirm_server_name must name the server. The storefront asks for it before the request; a request without it is refused here so no client can wipe a server on a bare click.

application/json

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/resources

PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/settings

application/json (required)

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/sftp

Connection details for this server's SFTP login.

The portal login email is the SFTP identity, and it need not match any platform user, so the storefront cannot derive this from auth/me.

Fields of a 200 response:

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/sleep

Sleep and start-queue state for a free server.

sleeps_at is absolute so a client can run the countdown locally instead of polling for a ticking number. Returns policy: none for a paid server, so a frontend can render one component for both.

Fields of a 200 response:

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/startup-variables

Every startup variable the server runs with, and what its owner may do with each.

The same answer as the client API's GET /servers/{uuid}/startup-variables: variables (each with value, secret, editable, locked, managed_by, removable, default, source and rule), game and free_plan_rules. Needs startup.read.

PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/startup-variables

Change, add or remove the server's startup variables.

The client API's rule (PATCH /servers/{uuid}/startup-variables): variables sets or adds names, remove_variables takes names away, values are single lines of up to 1,024 characters, a declared password and a game's own settings keep their rules, and 400 names the variable for a name the platform sets, a name its own setting manages, or a free server's program variable or shell characters. Values live in container_server_variables and apply on the next restart. Needs startup.update; the activity log names the keys, never the values.

application/json (required)

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/status-ping

Ask the game itself who is online. Best-effort; never fails the request.

Fields of a 200 response:

PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/subdomain

Rename the gameproxy join-address subdomain for this server.

application/json (required)

POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/wake

Ask for a sleeping free server to be started.

First in line with headroom starts in this request so the customer is not left waiting on a worker poll. Otherwise the row stays queued and a tick job releases it when the node has room. The response always carries the queue block (including ahead: 0) so a frontend can show the process.

application/json

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/websocket

Return panel WS URL + the caller's bearer token for WS query auth.

Fields of a 200 response:

GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization

What unused-chunk cleanup has done to this world, and when.

A feature that quietly deletes parts of somebody's world owes them the receipts: how much it reclaimed, when it last ran, and which worlds it left alone. It is also what turns an abstract switch into "this saved you 1.8 GB".

POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization

Queue an unused-chunk trim now, once per min_interval_hours.

Free and paid alike. Safety checks (offline, lease, node concurrency) stay with the job; this endpoint only gates the once-per-day customer button and that the feature is on for this server. Platform dry-run mode still applies.

Cooldown is based on last_run_at, not a pre-reserve of next_eligible_at, so a queued job that exits before recording a run cannot lock the button.