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/exchange | Trade an AuthOS token for a ServOS session |
POST | /api/v1/auth/logout | End the current session |
ServOS has no local passwords: sign-in, MFA and password recovery all live in AuthOS (see Authentication).
| GET | /api/v1/git/github/manifest/{state} | Hand a GitHub App manifest to GitHub (single-use link) |
| GET | /api/v1/git/github/callback | GitHub’s redirect after the App is created |
| GET | /api/v1/git/github/setup | GitHub’s redirect after the App is installed |
| POST | /api/v1/webhooks/github/{connector_id} | GitHub App webhook (signed with the App’s secret) |
| POST | /api/v1/webhooks/{resource_id} | Per-service git webhook (signed with the service’s secret) |
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 |
GET | /resources/{id}/stack | A Compose stack’s services and their state |
POST | /resources/{id}/stack/{start|stop|restart}?service= | Control the stack or one compose service |
GET | /resources/{id}/stack/logs?service=&tail= | Recent stack logs |
POST | /resources/{id}/takeover/revert | Hand a taken-over app back to Coolify |
POST | /resources/{id}/takeover/finish | Remove Coolify’s stopped containers |
POST | /compose/inspect | Parse a compose file: services, ports, volumes, variables |
Git connectors
| Method | Route | Purpose |
|---|---|---|
POST | /git/github/manifest | Start creating a GitHub App; returns the launch URL |
GET | /git/connectors | List GitHub App connectors with their installations |
GET, DELETE | /git/connectors/{id} | Read or remove a connector |
POST | /git/connectors/{id}/sync | Re-read installations and webhook target from GitHub |
GET | /git/connectors/{id}/repositories | Repositories the App can read |
GET | /git/connectors/{id}/branches?repo=owner/name | Branches of one repository |
GET | /git/connectors/{id}/inspect?repo=&branch=&path= | Detect how a repository builds (compose files, Dockerfiles, languages) |
POST | /git/connectors/{id}/webhook/claim | Point the App’s webhook at ServOS |
POST | /git/connectors/import/coolify | Adopt the GitHub Apps Coolify uses on a server |
Resources take build_pack (image, dockerfile, nixpacks, compose)
and, for stacks, compose: {file, content, project, services: {name: {domains, port}}, volumes, env_scope}. previews_enabled turns on pull
request previews.
Coolify takeover
| Method | Route | Purpose |
|---|---|---|
GET | /servers/{id}/coolify/applications | Coolify’s apps with ServOS’s plan for each |
POST | /servers/{id}/coolify/applications/{uuid}/takeover | Create the ServOS service and (by default) swap |
A resource builds through a connector when it is created or updated with
git_connector_id and a repo_url on the connector’s GitHub host. Send
"git_connector_id": null to stop using one.
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.