> ## Documentation Index
> Fetch the complete documentation index at: https://technified.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Manager

> The API-key command queue that powers live server control from the dashboard.

[Server Manager](https://technified.mintlify.site/dashboard/roblox/server-manager.md) lets staff control live Roblox servers from the dashboard: see who is online, kick, ban, mute, message, broadcast, or shut a server down. It works as a **command queue**, and your game server speaks to it with a guild API key.

> [!NOTE]
>
> 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](https://technified.mintlify.site/developer-api/introduction.md#scopes).

## How the queue works

```
Dashboard (staff clicks Kick)        Your Roblox server (API key)
        |                                     |
        |  enqueues a command                 |  1. heartbeat: report state + players
        v                                     |  2. read pending commands from the
   server_commands  <------------ heartbeat --+     heartbeat response
        |                                     |  3. run each command in-game
        +------------------ ack --------------+  4. ack: report the result
```

> [!NOTE]
>
> 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.

These endpoints use camelCase field names, like the rest of the [plugin protocol](https://technified.mintlify.site/developer-api/plugin-protocol.md).

## 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.

```http theme={null}
POST /roblox/servers/heartbeat
```

**guildId** `string` *required*

Must match your API key's guild.

**serverId** `string` *required*

The Roblox `game.JobId`.

**placeId** `string` *required*

**universeId** `string`

**gameName** `string`

**playerCount** `number` *required*

**maxPlayers** `number` *required*

**serverAge** `number`

Seconds since the server started.

**fps** `number`

**players** `object[]` *required*

The current players.

**player object**

**robloxId** `string` *required*

**username** `string` *required*

**displayName** `string`

**joinTime** `number` *required*

Unix timestamp when the player joined.

**team** `string`

```bash cURL theme={null}
curl "https://api.technified.xyz/api/v1/roblox/servers/heartbeat" \
  -H "X-API-Key: $TECHNIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "'$GUILD_ID'",
    "serverId": "abc123-...",
    "placeId": "987654321",
    "gameName": "My Game",
    "playerCount": 2,
    "maxPlayers": 50,
    "serverAge": 3600,
    "players": [
      { "robloxId": "261", "username": "Shedletsky", "joinTime": 1746712900 }
    ]
  }'
```

```json 200 theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "success": true,
    "commands": [
      {
        "id": 42,
        "type": "kick",
        "targetRobloxId": "261",
        "targetUsername": "Shedletsky",
        "parameters": { "reason": "AFK" },
        "issuedByUsername": "Febreeze"
      }
    ]
  }
}
```

Players missing from a heartbeat are treated as having left and are removed from the server's live list. `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](#acknowledge-a-command) 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.

```http theme={null}
GET /roblox/servers/:serverId/commands
```

**serverId** `string` *required*

The same `game.JobId` you heartbeat with.

**data.commands** `object[]`

Up to 20 pending commands, oldest first.

**command object**

**id** `number`

The command ID, needed to acknowledge it.

**type** `string`

One of `kick`, `ban`, `mute`, `message`, `teleport`, `broadcast`, `shutdown`.

**targetRobloxId** `string | null`

The target player, for player commands.

**targetUsername** `string | null`

**parameters** `object`

Command-specific data, for example `reason`, `duration`, or `message`.

**issuedByDiscordId** `string`

**issuedByUsername** `string`

```json 200 theme={null}
{
  "status": "success",
  "code": 200,
  "data": {
    "commands": [
      {
        "id": 17,
        "type": "kick",
        "targetRobloxId": "261",
        "targetUsername": "Shedletsky",
        "parameters": { "reason": "Breaking rules" },
        "issuedByDiscordId": "123456789012345678",
        "issuedByUsername": "Builderman"
      }
    ]
  }
}
```

### Command types

| Type | Scope | Common parameters |
| - | - | - |
| `kick` | Player | `reason` |
| `ban` | Player | `reason`, `duration` |
| `mute` | Player | `reason`, `duration` |
| `message` | Player | `message` |
| `teleport` | Player | destination data |
| `broadcast` | Server | `message` |
| `shutdown` | Server | none |

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 to `acknowledged` so it is not retried, and surfaces the result in the dashboard.

```http theme={null}
POST /roblox/servers/:serverId/commands/:commandId/ack
```

**serverId** `string` *required*

**commandId** `number` *required*

The `id` from the poll response.

**success** `boolean` *required*

**result** `string`

A short human-readable result, for example "Kicked Shedletsky".

**error** `string`

An error message when `success` is `false`.

```bash cURL theme={null}
curl "https://api.technified.xyz/api/v1/roblox/servers/abc123-.../commands/17/ack" \
  -H "X-API-Key: $TECHNIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "success": true, "result": "Kicked Shedletsky" }'
```

> [!TIP]
>
> If you run the Roblox integration or Technified Admin, this whole loop is already implemented. You only need these endpoints when building a custom admin system.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.