The queue endpoints (
servers/heartbeat, servers/:serverId/commands, and the command ack) require the server:write scope. Quick-installed plugin keys have it automatically. See Scopes.How the queue works
Only these three endpoints accept a guild API key. The dashboard side, listing servers and enqueuing a command (
/guilds/:guildId/servers...), requires a logged-in dashboard session with the server_manager permission and is not callable with an API key.Heartbeat
Report a live server and its current player list. Send this on a short loop, for example every 10 seconds (a server counts as stale after 30 seconds without a heartbeat). It keeps the server marked online, feeds the player list shown in the dashboard, and its response carries any pending commands for this server, so no separate poll loop is needed.data.commands holds up to 20 pending commands (oldest first, including broadcast commands targeted at every server); they are marked as delivered on return, so execute and acknowledge each one.
Poll for commands
Alternative to heartbeat-delivered commands: fetch the pending commands queued for this server on a dedicated loop. The response also includes broadcast commands targeted at every server. Polled commands are marked as delivered. If you already send heartbeats, you do not need this endpoint.Command types
Player commands carry a
targetRobloxId. Server-level commands like broadcast and shutdown do not. A broadcast is queued for every server at once.
Acknowledge a command
After running a command, report the outcome. This moves the command toacknowledged so it is not retried, and surfaces the result in the dashboard.