API Reference

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

Session Cookie

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

Authenticated Read Endpoints

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

Admin Write and Management Endpoints

Admin role is required for write operations and system management.

Agent Enrollment Endpoints

All of these endpoints require the Admin role. Responses follow the standard { "data": ... } envelope.

POST /api/agent/enrollments -- Mint an enrollment code

Mints a one-time, short-lived enrollment code (default TTL 600 seconds / 10 minutes; single-use; consumed on the agent's first successful registration).

Response:

{
  "data": {
    "id": "01J...",
    "code": "<plaintext code, returned only once>",
    "expires_at": "2026-05-17T12:34:56Z"
  }
}

The plaintext code is returned only at mint time -- copy it immediately.

GET /api/agent/enrollments -- List enrollment codes

Lists issued enrollment codes with metadata. For security this endpoint never returns the plaintext code, only an 8-character prefix plus status/expiry metadata.

{
  "data": [
    {
      "id": "01J...",
      "code_prefix": "ab12cd34",
      "expires_at": "2026-05-17T12:34:56Z",
      "consumed_at": null
    }
  ]
}

DELETE /api/agent/enrollments/{id} -- Delete an enrollment code

Deletes an unused enrollment code, invalidating it immediately.

POST /api/agent/{id}/rotate-token -- Rotate/revoke a run token

Rotates (revokes) the agent run token for the given server. The old token is invalidated immediately and the affected agent is forced to disconnect and must reconnect with the new token.

WebSocket Endpoints

Common Status Codes