Skip to content

API Overview

PowerBeacon exposes a REST API under the /api prefix. The API is organized by domain and designed for frontend and automation clients.

Interactive API docs

  • Swagger UI: http://localhost:8000/api/docs
  • OpenAPI JSON: http://localhost:8000/api/openapi.json

API Domains

Domain Base path Purpose
Authentication /api/auth Local login, current user, OIDC entry/callback
Devices /api/devices CRUD and wake operations
Clusters /api/clusters Cluster CRUD, detail, and cluster-level wake operations
Agents /api/agents Registration, heartbeat, inventory
Users /api/users User and role management
Config /api/config OIDC and runtime configuration
Setup /api/setup First-run platform setup

Authentication Model

flowchart LR
    A[Client] -->|POST /api/auth/login| B[Backend]
    B -->|JWT| A
    A -->|Authorization: Bearer token| C[/Protected API endpoints/]
    style A fill:#2563eb,stroke:#1e3a8a,color:#fff
    style B fill:#7c3aed,stroke:#5b21b6,color:#fff
    style C fill:#16a34a,stroke:#166534,color:#fff

Agent endpoints

Agent registration and heartbeat are authenticated with per-agent bearer tokens, not user JWTs.

Request and Response Conventions

  • JSON request/response bodies by default
  • UUID identifiers for core entities
  • Standard HTTP status codes
  • Error payloads include status/message/details where applicable

Common Workflows

  1. POST /api/auth/login
  2. Store returned access_token
  3. Call protected endpoints with Authorization: Bearer <token>
  1. GET /api/devices/
  2. Pick device ID
  3. POST /api/devices/{id}/wake
  1. GET /api/clusters/
  2. Pick cluster ID
  3. POST /api/clusters/{id}/wake
  1. POST /api/agents/register
  2. Agent stores token in memory
  3. Agent sends periodic POST /api/agents/heartbeat

Next Steps

  • Use Setup pages to get an environment running
  • Use Architecture pages to understand internals
  • Use Swagger UI for endpoint-level details

Wake orchestration note

Device wake requests are cluster-aware and multi-agent aware. The backend resolves every agent associated with a device and attempts dispatch through all online agents instead of routing through a single assigned relay.