ServerBee

API Reference

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

ServerBee provides a complete REST API for programmatic access to all Dashboard features. All endpoints are documented via OpenAPI 3.0.

Swagger UI

ServerBee includes a built-in Swagger UI for interactive API exploration:

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

You can browse all 50+ API endpoints, inspect request/response schemas, and send test requests directly.

Authentication

The ServerBee API supports two authentication methods:

Used automatically after browser login. Call /api/auth/login to obtain a session:

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

# Use the cookie for subsequent requests
curl https://your-server/api/servers -b cookies.txt

API Key

Suitable for automation. Create one in Settings → API Keys:

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

API keys use the format serverbee_ prefix + 43-character random string. The key is shown only once at creation time.

Endpoint Overview

Public Endpoints (No Auth Required)

MethodPathDescription
POST/api/auth/loginUser login
GET/api/auth/oauth/{provider}OAuth authorization redirect
GET/api/auth/oauth/{provider}/callbackOAuth callback
GET/api/statusPublic status page data

Authenticated Endpoints (Session or API Key)

MethodPathDescription
POST/api/auth/logoutUser logout
GET/api/auth/meGet current user info
POST/api/auth/change-passwordChange password
GET/POST/api/auth/2fa/*2FA management
GET/DELETE/api/auth/oauth/accountsOAuth account management
GET/api/serversList servers
GET/api/servers/{id}Get server details
GET/api/servers/{id}/recordsGet metric records
GET/api/servers/{id}/gpu-recordsGet GPU records
GET/api/server-groupsList server groups
GET/api/ping-tasksList ping tasks
GET/api/ping-tasks/{id}/recordsGet ping records

Admin Endpoints (Admin Role Required)

MethodPathDescription
POST/PUT/DELETE/api/servers/*Server management
PUT/api/servers/batch-capabilitiesBatch update capabilities
POST/api/servers/{id}/upgradeTrigger agent upgrade
CRUD/api/server-groups/*Server group management
CRUD/api/notifications/*Notification channel management
CRUD/api/notification-groups/*Notification group management
CRUD/api/alert-rules/*Alert rule management
CRUD/api/ping-tasks/*Ping task management
POST/api/tasksCreate a remote command task
GET/api/tasks/{id}Get task details and results
CRUD/api/users/*User management
GET/api/audit-logsAudit logs
GET/PUT/api/settings/*System settings
POST/api/settings/backupDatabase backup
POST/api/settings/restoreDatabase restore

WebSocket Endpoints

PathDescription
/api/ws/browserBrowser real-time data push
/api/ws/terminal/{server_id}Web terminal proxy

Error Responses

All API errors use a consistent format:

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

Common status codes:

CodeDescription
400Bad request / invalid parameters
401Not authenticated
403Forbidden (insufficient role or capability disabled)
404Resource not found
429Too many requests (rate limited)
500Internal server error

Capabilities

Admin Guide

Architecture

Admin Guide

User management, audit logs, remote commands, and billing management.

Architecture

Technical overview of ServerBee's system design, components, and protocols.

On this page

Swagger UIAuthenticationSession CookieAPI KeyEndpoint OverviewPublic Endpoints (No Auth Required)Authenticated Endpoints (Session or API Key)Admin Endpoints (Admin Role Required)WebSocket EndpointsError Responses