Documentation
API Reference
Core ServOS REST and WebSocket routes
API Reference
ServOS exposes its control-plane API under /api/v1. Use your own ServOS
origin, for example https://servos.example.com/api/v1.
Authentication
Authenticated routes accept the session established by the login flow. Agents use their issued agent credentials. Public bootstrap routes are explicitly called out below; do not assume an unlisted route is public.
Public and authentication routes
| Method | Route | Purpose |
|---|---|---|
GET | /health | Process health check (outside /api/v1) |
GET | /api/v1/health/init-status | Initial-setup status |
POST | /api/v1/setup-handshake | First-run setup handshake |
POST | /api/v1/auth/login | Standalone login |
POST | /api/v1/auth/logout | End the current session |
POST | /api/v1/auth/forgot-password | Start password recovery |
POST | /api/v1/auth/reset-password | Complete password recovery |
Core resources
All routes below are relative to /api/v1 and require authentication.
| Method | Route | Purpose |
|---|---|---|
GET, POST | /organizations | List or create organizations |
GET, PUT, PATCH, DELETE | /organizations/{id} | Manage an organization |
GET, POST | /servers | List or create servers |
GET, PUT, DELETE | /servers/{id} | Manage a server |
POST | /servers/{id}/commission | Commission a server |
GET | /servers/{id}/status | Read server status |
GET | /servers/{id}/preflight | Inspect commissioning risks |
GET | /servers/{id}/control-state | Read ownership and control state |
GET, POST | /projects | List or create projects |
GET, PUT, DELETE | /projects/{id} | Manage a project |
GET, POST | /projects/{project_id}/environments | List or create environments |
GET, PUT, DELETE | /environments/{id} | Manage an environment |
GET | /resources | List resources across the current scope |
GET, POST | /environments/{env_id}/resources | List or create environment resources |
GET, PUT, DELETE | /resources/{id} | Manage a resource |
POST | /resources/{id}/deploy | Start a deployment |
POST | /resources/{id}/deploy/source | Upload and deploy source |
POST | /resources/{id}/rollback | Roll back a resource |
Storage, backups, and operations
| Method | Route | Purpose |
|---|---|---|
GET, POST | /storage-providers | List or create storage providers |
GET, DELETE | /storage-providers/{id} | Read or delete a storage provider |
GET | /storage-providers/{id}/browse | Browse stored objects |
POST | /backups | Create a resource backup |
GET | /resources/{resource_id}/backups | List resource backups |
GET | /backups/{id}/restore/rehearsal | Check restore readiness |
POST | /backups/{id}/restore | Restore a backup |
GET | /resources/{resource_id}/deployments | List deployment history |
GET | /deployments/{id}/logs | Read deployment logs |
GET | /metrics/query | Query metrics |
WebSockets and streams
| Route | Purpose |
|---|---|
wss://HOST/api/v1/terminal?server=UUID | Interactive SSH terminal; optional cols and rows query parameters |
wss://HOST/api/v1/resources/{id}/logs | Live resource logs |
wss://HOST/api/v1/resources/{id}/exec | Interactive resource shell |
wss://HOST/api/v1/deployments/{id}/logs/ws | Live deployment logs |
GET /api/v1/events | Server-sent deployment status events |
Errors
Error responses use an appropriate HTTP status and a JSON body containing an
error field. Treat the message as operator-facing text rather than a stable
machine-readable error code.