Organization API: Org Staff Containers: Staff

Part of Org Staff Containers.

GET /api/v1/orgs/{org_slug}/staff/servers

Every container behind one of this brand's services, failing installs first, newest after that, and the highest server ID first when two were created in the same second. Tier 2 and above; everything that acts on a server from here is Tier 3. FleetFilters narrows it further: by name, owner, software, creation day, extra ports or uptime, all optional. pattern_id keeps the servers of one abuse pattern's accounts. A servers bulk run (POST /staff/abuse/bulk-runs) with the same filter acts on exactly the servers this list holds.

status is the admin list's two filters in one word (:data:STATUS_WORDS): a power word matches what the daemon was last seen doing, never the lifecycle column, which reads running for a stopped server too.

sort orders the whole fleet, not the page, by one of :data:FLEET_SORT_KEYS, which are the admin list's words. Every key but players and join_address is a column; those two are decided from the proxies' snapshot and the gameproxy routes over every matching id before the page is cut, unknown last.

POST /api/v1/orgs/{org_slug}/staff/servers/bulk

Suspend, unsuspend, terminate, or pause or ban the owners of, a selection of this brand's servers.

Support may suspend and unsuspend, as they can order by order. Anything that ends a server or changes an account's standing (terminate, ban, pause, a suspension with a deletion date) takes an org admin who has stepped up in the last ten minutes, the same gate the single-order terminate and the customer standing change have. Servers outside the brand or already ending are skipped and listed in the answer, not refused. For more than 100 servers, start a bulk run (POST /staff/abuse/bulk-runs).

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/servers/heal-installs

Heal every broken install behind this brand's services, oldest first: install_failed rows and installing rows nothing has driven for 45 s.

GET /api/v1/orgs/{org_slug}/staff/servers/live

Live state, usage and players for the brand's servers on one screen.

The admin list's /servers/live for the brand: items maps each UUID the daemons answered for to state (the daemon's word, or missing when it no longer knows the server), usage (the same shape as a list row's, measured just now), players_online and join_address. A server with no answer is left out and degraded is true; the page keeps what it had.

Only UUIDs behind one of this brand's services are asked about. One from another brand is dropped before any daemon is spoken to and never answered, not even with an error, so the poll cannot be used to learn which UUIDs exist elsewhere.

GET /api/v1/orgs/{org_slug}/staff/servers/stats

How many servers sit in each bucket, and the nodes they sit on.

A power word counts the servers its filter lists: the daemon's recorded word, among servers whose lifecycle lets them run. The counts cover the whole brand. They are normally under a minute old, and the first request after a quiet spell can show numbers a few minutes old. The server list is always current.

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

One server as staff see it, with the customer who owns it named: customer_email and customer_name (first and last name, null when the account has neither) come off the one customer row the record already loads.

grant says where a free server was ordered from: the order's ip, how the free-tier rules classed it (ip_kind: residential, hosting, vpn, proxy, tor or private), which source said so (ip_source) and when (created_at). It is null for a paid server and for a free server ordered before those rules existed.

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations

application/json

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/available-ports

DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/{allocation_id}

Release a port. A running server on a bridge-network node keeps it until it restarts: 409 restart_required unless restart=true.

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/{allocation_id}/primary

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/{allocation_id}/publish-port

Publish a port on 25565 / 19132 of the customer's floating IP, or clear it.

application/json

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups

application/json

DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups/{backup_uuid}

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups/{backup_uuid}/lock

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups/{backup_uuid}/restore

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

application/json

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases

application/json

Type: object or null.

DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}/credentials

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}/retry

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}/rotate-password

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/chmod

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/compress

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/contents

A file's text; below Tier 3, only inside logs/ and crash-reports/.

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/copy

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/decompress

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/delete

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/download

One file, streamed; below Tier 3, only inside logs/ and crash-reports/.

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/list

A directory; below Tier 3, only inside logs/ and crash-reports/.

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/mkdir

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/pull

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/pull/status

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/rename

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/upload

multipart/form-data (required)

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/write

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/heal-install

Run the platform's install self-healing on one of this brand's servers.

Reads the disk first: files in place means the row is marked running with nothing reinstalled; otherwise the install is driven again through the retry ladder. The same code the watchdog runs, so brand staff can clear a server that broke before it existed.

application/json

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/install-log

What the install script printed: the log it leaves in the volume, and the output recorded off the daemon while it ran. The daemon's own log is read over SSH on the node and stays with the platform.

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

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

application/json (required)

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

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

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/retry-install

Run the install again for a server in install_failed or stuck installing. Refused for a server in any other state: a reinstall of a working server is the reinstall route, which wipes it and says so.

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules

A 200 response is a list; each item has these fields:

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}

Fields of a 200 response:

DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}/execute

application/json

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}/runs

A 200 response is a list; each item has these fields:

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}/toggle

Pause a schedule that is hurting the server, or resume one.

application/json (required)

Fields of a 200 response:

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/server-icon

The server's /server-icon.png: the picture as a data URI, and whether the game shows it (valid) or why not (problems).

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/server-icon

Convert the uploaded file to a 64×64 PNG with the chosen fit and write it to /server-icon.png. Audited as server.icon.set.

multipart/form-data (required)

DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/server-icon

Delete /server-icon.png. Audited as server.icon.remove.

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

Sleep and start-queue state of a free server; policy: none for a paid one.

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots

This server's snapshots, or every snapshot the owning account holds judged for restoring onto this server.

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots

application/json

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/estimate

DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/cancel

Cancel a snapshot of this server that is still being taken.

Support work, like taking one: a snapshot in flight is no copy of anything yet, so cancelling it removes nothing the customer had. Delete stays admin-only. Answers 409 once the snapshot has finished or failed.

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/download

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/lock

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/restore

application/json

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/bedrock

Turn Bedrock crossplay on or off for one of the organization's Java servers.

The same switch as the customer's own. {"enabled": true} installs Geyser and Floodgate before this answers and gives Geyser a port of its own. {"enabled": false} deletes both and returns the port. A body without enabled turns crossplay off, and an enabled that is not true or false answers 422. The answer is the crossplay state.

It answers 400 with the reason, and nothing changes, when the server cannot run Geyser, when GeyserMC's downloads do not answer, or when a plugin cannot be installed. Needs Tier 3 support or a role above it. Audited as server.bedrock_bridge.set, a refused request too.

application/json (required)

PUT /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/bedrock/channel

Choose where a server's Bedrock crossplay takes Geyser from: release or development.

release is GeyserMC's newest release. development is the newest build of GeyserMC's GitHub build workflow, for a Minecraft version no release supports yet. With crossplay on, the chosen Geyser is installed before this answers. With crossplay off, the choice applies when crossplay is turned on. The answer is the crossplay state, with geyser_channel.

It answers 400 with the reason, and nothing changes, when the builds cannot be downloaded. Needs Tier 3 support or a role above it. Audited as server.bedrock_bridge.channel, a refused request too.

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/catalog

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/catalog/{key}/versions

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/change

application/json (required)

Type: Body.

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/context

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/installs

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/installs/{install_uuid}/cancel

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/installs/{install_uuid}/retry

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/startup

How the server starts: runtime, command (override and default), variables.

PATCH /api/v1/orgs/{org_slug}/staff/servers/{uuid}/startup

Change the runtime, the startup command or the variables. Admin, stepped up.

Applies on the next start; nothing here stops or starts the server.

application/json (required)

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

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

Support follows the owner's rule (startup_variables.validate_owner_changes): variables sets or adds, remove_variables takes away, and 400 names the variable the rule refuses. The audit row names the keys and never the values, since one may be a password.

application/json (required)

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

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/users

PUT /api/v1/orgs/{org_slug}/staff/servers/{uuid}/users/{subuser_id}

application/json (required)

DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/users/{subuser_id}

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

Start a sleeping free server on the customer's behalf.

No Turnstile: the risk challenge exists to slow down a scripted customer, and a signed-in staff member is neither.

POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/wake-queue/kick

Get a free server's stuck start moving: settle it against the daemon now and, if it is still not up, admit it past the admission gate and start it. Scoped to the brand's own servers.

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

The live console. Below Tier 3 the relay lets it be watched, not typed into (STAFF_WATCH_PERMISSIONS in the console relay).

Fields of a 200 response: