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

# Plugin Protocol

> The lower-level endpoints the Roblox integration uses for staff activity and Server Manager.

These endpoints power staff activity tracking and the [Server Manager](https://technified.mintlify.site/dashboard/roblox/server-manager.md) command queue. They are the protocol the [Roblox integration](https://technified.mintlify.site/roblox-integration/overview.md) and the standalone Technified Admin speak. You only need them if you are building a custom in-game admin system. If you use the official plugin, it handles all of this for you.

> [!WARNING]
>
> Unlike the moderation endpoints, these routes use **camelCase** field names (`guildId`, `robloxId`). Match the examples exactly.

## Staff permissions

Resolve a Roblox user's staff permission level so your admin system can grant the right access in-game.

```http theme={null}
GET /guilds/:guildId/staff/roblox/:robloxId/permissions
```

**guildId** `string` *required*

**robloxId** `number` *required*

## Game registration

Register the running game with Technified on startup. This is what makes the game appear under connected games in the dashboard.

```http theme={null}
POST /roblox/games/register
```

```json Body theme={null}
{
  "guildId": "123456789012345678",
  "placeId": "987654321",
  "universeId": "111222333",
  "gameName": "My Game",
  "creatorId": "1",
  "metadata": {
    "source": "adonis-plugin",
    "pluginVersion": "2.0.0",
    "jobId": "abc123-..."
  }
}
```

`metadata.source` identifies which client registered the game. The official integration sends `adonis-plugin` or `guardsman-plugin`. Pick your own identifier if you are building a custom admin system.

## Session tracking

Report when a staff member starts and stops playing, so their hours show up in [Staff Activity](https://technified.mintlify.site/dashboard/roblox/staff-activity.md).

> [tab] Start
>
> ```http theme={null}
> POST /staff/roblox/session/start
> ```
>
> ```json Body theme={null}
> {
>   "guildId": "123456789012345678",
>   "robloxId": "261",
>   "robloxUsername": "Shedletsky",
>   "placeId": "987654321",
>   "universeId": "111222333",
>   "gameName": "My Game"
> }
> ```

> [tab] End
>
> ```http theme={null}
> POST /staff/roblox/session/end
> ```
>
> ```json Body theme={null}
> {
>   "guildId": "123456789012345678",
>   "robloxId": "261"
> }
> ```

> [tab] Heartbeat
>
> ```http theme={null}
> POST /staff/roblox/heartbeat
> ```
>
> Keeps an open session alive. Send periodically while the staff member is in-game.

## Action logging

Log a moderation or admin command so it appears in the audit logs and counts toward performance scoring.

```http theme={null}
POST /staff/roblox/action
```

```json Body theme={null}
{
  "guildId": "123456789012345678",
  "actorRobloxId": "261",
  "actorUsername": "Shedletsky",
  "actionType": "ban",
  "actionCategory": "moderation",
  "targetRobloxId": "156",
  "targetUsername": "Telamon",
  "placeId": "987654321",
  "universeId": "111222333",
  "details": {
    "reason": "Exploiting",
    "rawCommand": ":ban Telamon Exploiting",
    "source": "adonis"
  }
}
```

`actionCategory` is `moderation` or `admin`. See the [Roblox integration features](https://technified.mintlify.site/roblox-integration/features.md#action-logging) for the full command list.

## Server Manager queue

The live server control endpoints (heartbeat, poll commands, acknowledge) are also part of this protocol and use the same guild API key. They have their own page.

> [card] [Server Manager](https://technified.mintlify.site/developer-api/server-manager.md)
>
> Heartbeat a server, poll for queued commands, and acknowledge results.


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