API Reference

ServerBee exposes the same capabilities the web dashboard uses 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 and authentication requirements, and send 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": {}
}

Application errors use an error code and message, with optional details:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Bad request: description of 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. Admin users can 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. An API key authenticates as its owning user; it is a credential, not a separate role. Requests inherit the owner's current Admin or Member permissions. Only Admin users can create new API keys.

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

Ordinary mobile refresh preserves the installation registration and invalidates the previous access and refresh credentials. Login returns a stable revocation_token; the client retains it across refreshes and sends it with installation_id to /api/mobile/auth/revoke when signing out or discarding permanently rejected credentials. Cleanup uses the original login context even if a replacement login starts while the request is pending. This proof can only delete its original session, credentials, and registration; it cannot authenticate other APIs or refresh a session. Cleanup captures both the saved proof and the original login's current refresh secret before rotation. The saved proof can be absent or stale when an older Server replaced sessions during an iOS-first upgrade. If the saved proof is rejected, the client tries only the captured refresh secret at the deletion endpoint, without adopting a replacement login's credentials. An absent proof is saved before networking. Revocation can verify that secret before consumption; every successful rotation also retains the consumed secret's hash in the same transaction. Verification and deletion are serialized with rotation, so cleanup remains possible whether it reaches the Server before consumption or after a committed response is lost. These retained hashes grant deletion of only the original session and are removed with that session. They never grant ordinary API access or allow reuse of a consumed refresh token. Other installations, users, and replacement logins remain independent.

Recovery through /api/mobile/auth/recover uses the same login rate limit and accepts exactly one authentication mode: username plus password (with totp_code when enabled), pairing_code from the authenticated web QR pairing flow, or a previously returned recovery_token. Password fields are optional for QR/grant mode; mixing modes or supplying TOTP with QR/grant is rejected. The QR code is consumed once by recovery and cannot also be redeemed for a normal login. Account security changes after code generation or grant creation invalidate that authority; password onboarding remains enforced. Every request includes expected_user_id, installation_id, optional expected_session_id, and captured original access/refresh/revocation material. Recovery issues no login tokens. Expired material may identify an original session, but cannot authenticate ordinary requests.

A response contains outcome, user_id, installation_id, nullable mobile_session_id, and candidates. Outcomes ok and already_absent confirm cleanup and return no candidates. Without a known ID or matching material, remaining scoped sessions produce selection_required with device names, session IDs, creation dates and last-use dates, including expired sessions. No session is selected or removed automatically. The user chooses the original session, and another reauthenticated request uses that exact expected_session_id. Absence without an ID is confirmed only when the original account and installation have no remaining operational state. Unattributed state or more than 64 candidates returns 409 without discarding records. Recovery never chooses the newest session or deletes all sessions for an installation.

QR/grant responses also contain a cleanup-only recovery_token; password responses omit it. This random grant expires five minutes after creation, is kept only in client memory, and is lost on Server restart. The Server retains at most 128 grants, cleans expired entries, and returns 429 at capacity. It is bound to the original account, installation, and exact captured access/refresh/revocation material, and cannot authorize ordinary login, pairing, refresh or API calls. Reuse it with unchanged captured material for session selection and retries. Selection is restricted to the initially offered candidates and pinned before deletion; retries cannot change the target or broaden the list. A terminal grant retains the exact resolved target until expiry, so lost-response retries confirm only that target’s absence. An ID-less absence grant cannot acknowledge or clean up later replacement state. After restart, expiry, or new state following an ID-less absence, scan a fresh web QR code.

Authenticated Read Endpoints

These endpoints require a user credential. Admin and Member users can use the listed read operations, plus operations that apply only to the signed-in account. API keys receive the same access as their owning users. Admin-only management endpoints are listed separately below.

Admin Write and Management Endpoints

The following management and host-control operations require Admin. Operations listed above that apply only to the signed-in account remain available to authenticated Member users.

The backup endpoint returns a raw SQLite download. Restore accepts a raw SQLite body with Content-Type: application/octet-stream and requires a Server restart. Both are Admin-only, high-risk operations; see Backup and Restore for verified commands and safeguards.

Agent Authority and Enrollment

Responses follow the standard { "data": ... } envelope. Agent Authority management requires Admin; state and event history are authenticated read endpoints.

POST /api/servers -- Onboard a Server

Creates the Server profile and its initial bound offer atomically. onboarding_request_id is required and is scoped to the authenticated actor. Retrying the same ID with identical normalized input returns the same server_id; reusing it with different input returns 409 ONBOARDING_IDEMPOTENCY_CONFLICT.

{
  "onboarding_request_id": "019f...",
  "name": "edge-tpe-1",
  "tags": ["production"],
  "ttl_secs": 600
}

A new operation returns replayed: false and enrollment: { id, code, code_prefix, expires_at }. A replay returns replayed: true, never returns plaintext code, and may return outstanding_offer metadata.

POST /api/agent/register -- Claim an offer

This public Agent endpoint authenticates with Authorization: Bearer <enrollment_code> and requires an Agent-generated token:

{ "proposed_run_token": "<32-or-more non-whitespace characters>" }

On success it consumes the offer, stores only the run-token hash, and returns { "data": { "server_id": "..." } }. The Server never returns the plaintext run token.

Agent Authority state and history

• GET /api/servers/{id}/agent-authority returns status (claimed or unclaimed) and the current outstanding_offer, if any.
• GET /api/agent-authority/events?server_id={id}&limit=100 returns secret-free transition history. Events survive Server deletion.

Offer and authority actions

• POST /api/servers/{id}/agent-authority/re-enrollment with { "mode": "graceful" | "emergency", "ttl_secs": 600 } starts re-enrollment for a claimed authority. Graceful keeps the old authority valid; emergency revokes and fences it immediately.
• POST /api/servers/{id}/agent-authority/offers with optional { "ttl_secs": 600 } issues an offer only when authority is unclaimed.
• POST /api/servers/{id}/agent-authority/offers/{offer_id}/replace replaces exactly the current outstanding offer and returns new plaintext once.
• DELETE /api/servers/{id}/agent-authority/offers/{offer_id} revokes exactly that offer.
• DELETE /api/servers/{id}/agent-authority revokes the current authority and disconnects its Agent without issuing an offer.

Only one offer may be outstanding per Server. Its terminal outcome is exactly one of consumed, revoked, replaced, or expired. Exact-ID replacement is compare-and-swap: stale or terminal offers return 409 and cannot overwrite newer state.

WebSocket Endpoints

Common Status Codes