REST API

Heartbeat Endpoint

Submit periodic health heartbeats directly to Monitor via HTTP POST.

POSThttps://botmonitor.pages.dev/api/public/heartbeat

Authentication: Authorization: Bearer <heartbeat_token> or header x-heartbeat-token: <token>

Request Parameters

Field	Type	Required	Description
bot_id	string	Yes	Discord bot user ID. Must match the token-bound bot.
interval_seconds	integer	Yes	Expected ping interval in seconds (e.g. 60).
shards	array	No	List of shard telemetry objects.
shards[].shard_id	integer	Yes*	Zero-indexed shard identifier.
shards[].status	string	Yes*	"healthy" \| "degraded" \| "disconnected"
shards[].latency_ms	integer \| null	No	Round-trip WebSocket ping in milliseconds.
shards[].guild_count	integer \| null	No	Total guilds assigned to this shard.

Payload Examples

Standard Single Process Bot:

json

{
  "bot_id": "123456789012345678",
  "interval_seconds": 60
}

Sharded Bot Payload:

json

{
  "bot_id": "123456789012345678",
  "interval_seconds": 60,
  "shards": [
    {
      "shard_id": 0,
      "status": "healthy",
      "latency_ms": 42,
      "guild_count": 125
    },
    {
      "shard_id": 1,
      "status": "healthy",
      "latency_ms": 55,
      "guild_count": 130
    }
  ]
}

Response Codes

Status	Meaning	Details
200 OK	Success	Heartbeat recorded.
400 Bad Request	Invalid Payload	Malformed JSON, missing bot_id, or invalid shard array.
401 Unauthorized	Missing Auth	Missing or malformed Authorization header.
403 Forbidden	Invalid Token	Token revoked, invalid hash, or assigned to a different bot ID.
429 Rate Limit	Too Many Requests	Heartbeat sent faster than allowed threshold.