Organization API: Customer Portal: Servers

Part of Customer Portal.

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

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

application/json

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:

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

Update allowlisted startup env vars for the server's game.

Values live in container_server_variables and apply on the next restart after Wings sync. Arbitrary keys and startup_command are not accepted.

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.