API Reference
Complete REST API reference for NOBA Command Center.
Base URL
http://<host>:<port> (default port 8080)
Authentication
All endpoints except /api/health and /api/login require a valid session token.
- HTTP header:
Authorization: Bearer <token> - Query parameter:
?token=<token>(required for SSE / EventSource)
Tokens are valid for 24 hours and expire automatically. A cleanup job runs every 5 minutes to purge expired tokens.
Roles
| Role | Access |
|---|---|
viewer | Read-only: stats, history, logs, dashboards |
operator | Viewer + service control, automations, agent commands, approvals |
admin | Full access: settings, user management, system update, audit log |
Interactive Docs
When enabled (NOBA_OPENAPI=1), Swagger UI is available at /api/docs and ReDoc at /api/redoc. These cover 490+ endpoints across 57 routers with request/response schemas.
Core Endpoints
| Method | Endpoint | Auth | Description |
|---|---|---|---|
GET | /api/health | None | Health check with version and uptime |
GET | /api/me | Read | Current user info and permissions |
GET | /api/stats | Read | Live system metrics snapshot |
GET | /api/stream | SSE | Server-Sent Events metrics stream |
GET | /api/history/{metric} | Read | Time-series history for a metric |
GET | /api/alert-rules | Read | List configured alert rules |
GET | /api/notifications | Read | User notifications with unread count |
POST | /api/login | None | Authenticate and get session token |
POST | /api/logout | None | Revoke current session token |
Key Endpoint Groups
| Router | Endpoints | Auth | Description |
|---|---|---|---|
| agents.py | 25+ | Read/Admin | Agent report, commands, file transfer, deploy, capabilities |
| integrations.py | 100+ | Read/Admin | 50+ integration endpoints: Proxmox, Docker, K8s, Pi-hole, etc. |
| automations.py | 30+ | Operator/Admin | Automations CRUD, jobs, webhooks, maintenance windows, approvals |
| healing.py | 20+ | Operator/Admin | Heal ledger, trust levels, chaos testing, dry-run, rollback |
| security.py | 15+ | Read/Admin | Security scan, findings, posture, baseline drift |
| admin_core.py | 30+ | Admin | Settings, audit log, backup, plugins, runbooks, reports |
| enterprise_core.py | 25+ | Admin | SAML, SCIM, WebAuthn, database status, compliance |
| enterprise_governance.py | 20+ | Admin | RBAC, freeze, vault, password policy, retention |
Rate Limiting
Per-IP and per-user rate limiting with automatic lockout. Login endpoint: 5 attempts per 5-minute window. Lockout duration: 30 minutes (configurable).
Error Codes
| Code | Meaning |
|---|---|
400 | Bad request — invalid parameters or configuration |
401 | Unauthorized — missing or invalid session token |
403 | Forbidden — insufficient role/permissions |
404 | Not found — resource does not exist |
409 | Conflict — resource already exists or state conflict |
422 | Validation error — request body failed schema validation |
429 | Too many requests — rate limit exceeded |
500 | Internal server error — generic error handler (details never exposed) |