ServerBee Docs

ServerBee REST API overview, authentication, WebSocket endpoints, and Swagger UI interactive docs.

ServerBee exposes the same capabilities used by the web dashboard through REST and WebSocket APIs. The authoritative, schema-level reference is generated from OpenAPI annotations in the server binary.

Swagger UI

Open the built-in interactive documentation at:

https://your-server/swagger-ui/

Swagger UI lets you inspect request/response schemas, authentication requirements, and test requests against your own deployment. The raw OpenAPI document is available at:

https://your-server/api-docs/openapi.json

Response Format

Successful REST responses are wrapped as:

{
  "data": {}
}

Errors use:

{
  "error": "Error message describing what went wrong"
}

Authentication

Used by the web dashboard after login:

curl -X POST https://your-server/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}' \
  -c cookies.txt

curl https://your-server/api/servers -b cookies.txt

API Key

Use API keys for automation. Create them in Settings → API Keys.

curl https://your-server/api/servers \
  -H "X-API-Key: serverbee_your-api-key-here"

API keys use the serverbee_ prefix and are shown only once when created.

Bearer Session Token

Mobile flows use Bearer tokens for selected REST and WebSocket endpoints:

curl https://your-server/api/auth/me \
  -H "Authorization: Bearer <session-token>"

Public Endpoints

Method	Path	Description
POST	`/api/auth/login`	Web login
GET	`/api/auth/oauth/providers`	List enabled OAuth providers
GET	`/api/auth/oauth/{provider}`	OAuth authorization redirect
GET	`/api/auth/oauth/{provider}/callback`	OAuth callback
POST	`/api/mobile/auth/login`	Mobile login
POST	`/api/mobile/auth/refresh`	Refresh a mobile session
POST	`/api/mobile/auth/pair`	Redeem a mobile pairing code
POST	`/api/agent/register`	Agent auto-registration using discovery key
GET	`/api/status`	Default public status page data
GET	`/api/status/{slug}`	Configurable public status page data
GET	`/api/settings/brand`	Public brand settings
GET	`/api/brand/logo`	Serve uploaded logo
GET	`/api/brand/favicon`	Serve uploaded favicon

Authenticated Read Endpoints

Read endpoints are available to Admin and Member users unless noted otherwise.

Family	Representative endpoints
Current user and API keys	`GET /api/auth/me`, `PUT /api/auth/password`, `GET/POST /api/auth/api-keys`, `DELETE /api/auth/api-keys/{id}`
2FA and OAuth accounts	`/api/auth/2fa/`, `GET/DELETE /api/auth/oauth/accounts/`
Mobile devices	`POST /api/mobile/auth/logout`, `GET /api/mobile/auth/devices`, `DELETE /api/mobile/auth/devices/{id}`
Servers	`GET /api/servers`, `GET /api/servers/{id}`, `GET /api/servers/{id}/records`, `GET /api/servers/{id}/gpu-records`
Groups and tags	`GET /api/server-groups`, `GET /api/server-tags`
Uptime and traffic	`GET /api/servers/{id}/uptime-daily`, `GET /api/servers/{id}/traffic`
GeoIP	`GET /api/geoip/status`
Ping tasks	`GET /api/ping-tasks`, `GET /api/ping-tasks/{id}/records`
Network probes	`/api/network-probes/`, `/api/servers/{id}/network-probes/`
Traceroute results	`GET /api/servers/{id}/traceroute/{request_id}`
Files, read-only	`POST /api/files/{server_id}/list`, `stat`, `read`, `GET /api/files/transfers`, `GET /api/files/download/{transfer_id}`
Docker, read-only	`GET /api/servers/{id}/docker/containers`, `stats`, `info`, `events`, `networks`, `volumes`
Service monitors	`GET /api/service-monitors`, `GET /api/service-monitors/{id}`, `GET /api/service-monitors/{id}/records`
Status page config	`GET /api/status-pages`
Dashboards	`GET /api/dashboards`, `GET /api/dashboards/default`, `GET /api/dashboards/{id}`
Themes	`GET /api/themes/*`
Cost insights	`GET /api/cost/overview`, `GET /api/servers/{id}/cost-insights`
Alert events	alert event read endpoints used by the dashboard

Admin Write and Management Endpoints

Admin role is required for write operations and system management.

Family	Representative endpoints
Server management	`POST/PUT/DELETE /api/servers/*`, `PUT /api/servers/batch-capabilities`, `POST /api/servers/{id}/upgrade`
Agent recovery	`GET /api/servers/{target_id}/recovery-candidates`, `GET /api/servers/recovery-jobs/{job_id}`, `POST /api/servers/{target_id}/recover-merge`
Groups and tags	CRUD `/api/server-groups/`, CRUD `/api/server-tags/`
Ping and network probes	CRUD `/api/ping-tasks/`, write endpoints under `/api/network-probes/`
Traceroute	`POST /api/servers/{id}/traceroute`
Files	`POST /api/files/{server_id}/write`, `delete`, `mkdir`, `move`, `download`, `upload`, `DELETE /api/files/transfers/{transfer_id}`
Docker actions	`POST /api/servers/{id}/docker/containers/{cid}/action`
Service monitors	CRUD `/api/service-monitors/*`, `POST /api/service-monitors/{id}/check`
Dashboards	`POST /api/dashboards`, `PUT/DELETE /api/dashboards/{id}`
Themes and appearance	theme write endpoints, `PUT /api/settings/brand`, `POST /api/settings/brand/logo`, `POST /api/settings/brand/favicon`
Status pages	CRUD `/api/status-pages/*`
Incidents	CRUD `/api/incidents/*`, `POST /api/incidents/{id}/updates`
Maintenance windows	CRUD `/api/maintenances/*`
Alerts and notifications	CRUD `/api/alert-rules/`, `/api/notifications/`, `/api/notification-groups/*`
Tasks	`GET/POST /api/tasks`, `GET/PUT/DELETE /api/tasks/{id}`, `GET /api/tasks/{id}/results`, `POST /api/tasks/{id}/run`
Users	CRUD `/api/users/*`
Audit and settings	`GET /api/audit-logs`, `/api/settings/*`, backup/restore endpoints
GeoIP	`POST /api/geoip/download`
Mobile push	`POST /api/mobile/pair`, `POST /api/mobile/push/register`, `POST /api/mobile/push/unregister`

WebSocket Endpoints

Path	Auth	Description
`/api/agent/ws?token=<agent_token>`	Agent token query parameter	Agent metrics, commands, pings, files, Docker, traceroute
`/api/ws/servers`	Session cookie, API key, or Bearer token	Browser/mobile real-time server updates
`/api/ws/terminal/{server_id}`	Authenticated Admin + `CAP_TERMINAL`	Web terminal proxy; terminal payloads use binary frames
`/api/ws/docker/logs/{server_id}`	Authenticated + `CAP_DOCKER`	Per-container Docker log streaming

Common Status Codes

Code	Meaning
400	Bad request or invalid operation
401	Not authenticated
403	Forbidden: role, capability, or local agent policy blocks the operation
404	Resource not found, server offline, or disabled public page
409	Conflict, such as duplicate slug/name
422	Validation error
429	Rate limited
500	Internal server error

API Reference