API reference
REST endpoints, authentication, rate limits, and common patterns. Full reference for integrations and the CLI.
Base URL
https://$APP_DOMAIN/api
Authentication
All endpoints except /api/health and /api/auth/telegram require Authorization: Bearer <jwt>.
Obtain a JWT by posting Telegram initData:
POST /api/auth/telegram
{ "initData": "" }
→ 200 { "token": "", "user": { ... } } Response headers
X-Request-Id— unique ID for tracing. Include in bug reports.X-RateLimit-Limit,X-RateLimit-Remaining— on rate-limited routes.
Core endpoints
Servers
| Method | Path | Description |
|---|---|---|
| GET | /servers | List servers visible to the caller |
| POST | /servers | Create server (caller becomes owner) |
| GET | /servers/:id | Get single server (viewer+) |
| PUT | /servers/:id | Update server (admin+) |
| DELETE | /servers/:id | Delete server (owner only) |
| POST | /servers/:id/test | Test SSH connection |
Access control
| Method | Path | Description |
|---|---|---|
| GET | /servers/:id/access | List members (admin+) |
| POST | /servers/:id/access | Grant access (owner only) |
| PUT | /servers/:id/access/:userId | Change role (owner only) |
| DELETE | /servers/:id/access/:userId | Revoke access (owner only) |
OpenClaw
Base: /servers/:id/openclaw. Sub-resources: agents, sessions, skills, config, status, restart, dashboard-url. See backend/src/routes/openclaw.ts for the full list.
Setup wizard
Base: /servers/:id/setup. Endpoints: check-prereqs, install-node, install-openclaw, onboard, configure-gateway, systemd, verify-health, create-default-agent, check-updates, update-component.
RAG
Base: /servers/:id/rag. Endpoints: install (task), health, connections, and per-agent: agents/:agentId/configure, .../files, .../reindex, .../query, .../enable-skill, .../disable-skill, .../export, .../disconnect, DELETE .../agents/:agentId. Plus Ollama helpers: ollama/status, ollama/install (task), ollama/pull-model (task).
Tasks
| Method | Path | Description |
|---|---|---|
| GET | /tasks/:id | Get task state + steps |
| GET | /tasks/active?type=X&serverId=Y | Find active task for reconnection |
| GET | /tasks/active-server?serverId=Y | List all active tasks for a server |
Admin (super-admin only)
| Method | Path | Description |
|---|---|---|
| GET | /admin/health/detailed | DB status, memory, monitor, tasks, backup health |
| GET | /admin/backups | List retained backups |
| POST | /admin/backups/run | Trigger manual backup |
| GET | /admin/backups/download/:filename | Download a gzipped backup |
| GET | /admin/audit | Query audit log with filters |
User preferences
| Method | Path | Description |
|---|---|---|
| GET | /me/notification-prefs | Get your mute / quiet-hours settings |
| PUT | /me/notification-prefs | Update your preferences |
Error responses
All errors are JSON: {"error": "human-readable message"}. Common status codes:
400— invalid input401— missing or bad JWT403— authenticated but not authorized (wrong role)404— resource not found429— rate limit exceeded (includesRetry-After)500— server error (check logs with theX-Request-Id)