API Reference
HTTP endpoints for the Rust backend API.
This reference documents every HTTP endpoint on the Rust backend (default port 8080). Use it when integrating with the API directly or extending the BFF. Router: backend/crates/bot/src/http/router.rs.
Authentication
Public routes
No authentication required.
Authenticated routes (/api/v1/*)
Require Authorization: Bearer <internal-jwt> header.
The JWT is minted by the web BFF with HS256 using the shared API_INTERNAL_SECRET. Claims:
| Claim | Description |
|---|---|
user_id | Discord user ID |
guild_id | Target guild ID |
exp | Expiration (60 second TTL) |
Each guild-scoped route also verifies the caller has Manage Server permission via Discord REST API.
Webhook route
POST /webhooks/attendance requires x-webhook-secret header matching WEBHOOK_SECRET. Currently returns 501 Not Implemented.
Public endpoints
GET /health
Bot and database health check.
Response: 200 OK
{ "status": "ok" }GET /verify/session/{session_id}
Verify a voice session Ed25519 signature.
Parameters:
| Name | Type | Description |
|---|---|---|
session_id | UUID | Voice session identifier |
Response: 200 OK
{ "valid": true }Returns 400 for invalid UUID format.
GET /verify/period/{guild_id}/{period_index}
Verify an archived period snapshot signature.
Parameters:
| Name | Type | Description |
|---|---|---|
guild_id | Integer | Discord guild ID |
period_index | Integer | Archived period index |
Response: 200 OK
{ "valid": true }Authenticated endpoints (/api/v1)
All routes require JWT auth. Base path: /api/v1/guilds/{guild_id}.
Overview & analytics
| Method | Path | Description |
|---|---|---|
GET | /overview | Guild overview (occupancy, period, signing status) |
GET | /leaderboard | Current period leaderboard |
GET | /stats?user_id= | Per-user stats for current period |
GET | /channel-stats?channel_id= | Per-channel stats |
GET | /analytics/heatmap | Activity heatmap data |
GET | /analytics/live-occupancy | Live voice occupancy |
Tracking settings
| Method | Path | Description |
|---|---|---|
PATCH | /tracking-mode | Set Off / Allowlist / Denylist / All |
GET | /tracked-channels | List tracked channels |
POST | /tracked-channels | Add tracked channel |
DELETE | /tracked-channels/{channel_id} | Remove tracked channel |
GET | /fairness | Get fairness settings |
PATCH | /fairness | Update fairness settings |
Fairness settings body:
{
"pause_on_mute": false,
"pause_on_deafen": false,
"pause_when_solo": false,
"min_session_seconds": 0
}Period management
| Method | Path | Description |
|---|---|---|
PATCH | /reset-interval | Configure reset schedule |
POST | /reset-now | Force period reset |
GET | /signing/history | List archived periods |
Signing
| Method | Path | Description |
|---|---|---|
POST | /signing/generate-keys | Generate Ed25519 keypair |
POST | /signing/unlock | Unlock signing key |
GET | /signing/status | Signing and period status |
GET | /signing/public-key | Get public verification key |
POST | /signing/verify-session | Verify session signature |
POST | /signing/verify-period | Verify period snapshot |
Discord integration
| Method | Path | Description |
|---|---|---|
GET | /channels | List guild channels |
GET | /bot-present | Check if bot is in guild |
Log destinations
| Method | Path | Description |
|---|---|---|
GET | /log-destinations | List log destinations |
POST | /log-destinations | Add log destination |
DELETE | /log-destinations/{destination_id} | Remove destination |
PATCH | /log-destinations/{destination_id}/types | Enable/disable log type |
PATCH | /log-destinations/{destination_id}/frequency | Set periodic frequency |
Pro features
| Method | Path | Description |
|---|---|---|
GET | /export/period/{period_index} | Download signed period export |
GET | /verified-roles | List verified role rules |
POST | /verified-roles | Create/update verified role rule |
DELETE | /verified-roles/{rule_id} | Delete verified role rule |
GET | /webhooks/settings | Get webhook settings |
PATCH | /webhooks/settings | Update webhook settings |
Subscription
| Method | Path | Description |
|---|---|---|
GET | /subscription | Get subscription tier info |
PATCH | /subscription | Update subscription tier |
Error responses
Authenticated routes return standard error JSON:
{ "error": "description" }| Status | Meaning |
|---|---|
401 | Missing or invalid JWT |
403 | User lacks Manage Server permission |
404 | Resource not found |
422 | Validation error |
500 | Internal server error |
Webhook endpoint (not implemented)
POST /webhooks/attendance
Inbound attendance webhook. Requires x-webhook-secret header.
Status: 501 Not Implemented