StaffHQ
Docs/Reference/REST API

REST API

Authentication, plugin endpoints, and public endpoints for the StaffHQ API.

The StaffHQ dashboard exposes a REST API at https://dash.staffhq.net/api. The API is used internally by the plugin and the Discord bot, and selected endpoints are publicly documented for custom integrations.

ℹ
Note
The API is not versioned with a public stability guarantee at this time. Breaking changes will be announced in the Discord server. Monitor the changelog for updates.

Authentication

All authenticated endpoints require a Bearer token in the Authorization header. Two types of API keys are available:

Plugin key

Used by the Minecraft plugin. Has write access to heartbeat, chat, punishment, and anti-cheat endpoints. Cannot access dashboard data.

Dashboard key

Used by the Discord bot and custom integrations. Has read access to player, punishment, and stats data. Cannot write plugin events.

Request format

http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Plugin endpoints

These endpoints are used by the Minecraft plugin. Plugin API keys are required.

POST
/api/plugin/heartbeat

Report server TPS, player count, and online status. Called every sync_interval seconds.

POST
/api/plugin/chat

Submit a batch of chat messages and commands captured during the sync interval.

POST
/api/plugin/punishments

Report a new punishment event (ban, mute, kick, or warning) from a supported punishment plugin.

POST
/api/plugin/anticheat-flags

Submit anti-cheat flag events from a supported anti-cheat plugin.

POST
/api/plugin/sessions

Report a player join or quit event with timestamp and server.

POST
/api/plugin/rank-changes

Report a LuckPerms group change event for a player.

Example: submit a heartbeat

json
POST /api/plugin/heartbeat
Authorization: Bearer YOUR_PLUGIN_KEY

{
  "server_id": "550e8400-e29b-41d4-a716-446655440000",
  "tps": 19.8,
  "player_count": 42,
  "max_players": 100,
  "timestamp": "2026-04-13T12:00:00Z"
}

Dashboard endpoints

These endpoints are available to Dashboard-type API keys for custom integrations and the Discord bot.

GET
/api/players/:uuid

Look up a player by UUID. Returns join history, punishments, and linked Discord account.

GET
/api/players/:uuid/punishments

Return the full punishment history for a player.

GET
/api/players/:uuid/flags

Return anti-cheat flag history for a player.

GET
/api/players/:uuid/chatlog

Return recent chat messages for a player. Supports a limit query parameter.

GET
/api/servers

List all servers linked to this account with current status.

GET
/api/staff

Return all detected staff members and their current online/offline status.

Public endpoints

These endpoints do not require authentication and are suitable for external widgets or public status pages.

GET
/api/public/reviews

Return a list of published customer reviews displayed on the marketing site.

GET
/api/public/exchange-rates

Return the current exchange rates used for credit pricing (GBP base).

Rate limits

Plugin endpoints have a higher rate limit to accommodate frequent heartbeats and batch submissions. Dashboard endpoints are rate-limited per API key.

Plugin endpoints1,000 requests / minute
Dashboard endpoints60 requests / minute
Public endpoints30 requests / minute

If you exceed the rate limit you will receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

← PreviousCreditsNext →Troubleshooting