API Reference
Complete reference for every VM API endpoint. Each page shows both SDK and REST API syntax side by side.
This reference describes the native VM API for SDK 3. Upgrade clients after the matching API and gateway release is deployed and verified. SDK 2 is incompatible with that service. See Migrating to SDK 3.
Base URL
https://api.oblien.com/v1The SDK supplies this versioned base URL. Direct paths such as /vms also use the same v1 handlers as /v1/vms, with identical authentication and permissions and no redirect. The direct alias stays pinned to v1 when a later /v2 API is introduced. OAuth callbacks and MCP resource metadata remain on their canonical versioned URLs.
Authentication
All requests require one of:
| Method | Headers | Use case |
|---|---|---|
| API Key | X-Client-ID + X-Client-Secret | Server-side / SDK |
| Scoped Token | Authorization: Bearer <jwt> | Namespace or VM scoped access |
| VM Token | Authorization: Bearer <token> | Client-side / single VM access |
See Authentication for setup details.
Response format
Every response follows a consistent structure:
Success:
{
"success": true,
"vm": { ... }
}Error:
{
"success": false,
"error": "validation_error",
"code": "validation_error",
"message": "Port must be between 1 and 65535",
"details": {
"field": "port"
}
}error / code are machine-readable. message is human-readable. details is optional.
Some endpoints return additional top-level fields (e.g., total, page, limit for paginated results).
Common HTTP status codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Created (new resource) |
400 | Bad request - invalid parameters |
401 | Unauthorized - missing or invalid credentials |
402 | Payment required - quota exceeded |
403 | Forbidden - not your resource |
404 | Not found |
409 | Conflict - resource in wrong state |
422 | Unprocessable - validation failed |
429 | Rate limited - slow down |
500 | Server error |
503 | Service unavailable - VM backend down |
Endpoint map
Authentication
| Endpoint | Method | Description |
|---|---|---|
/tokens | POST | Issue a scoped token (namespace or VM) |
Core
| Endpoint | Method | Description |
|---|---|---|
/vms | POST | Create VM |
/vms | GET | List VMs |
/vms/:id | GET | Get VM |
/vms/:id | PUT | Update VM |
/vms/:id | DELETE | Delete VM |
/vms/:id/details | GET | Aggregated details |
/vms/quota | GET | Resource quota |
/vms/estimate | GET | Estimate monthly credits |
/vms/archived | GET | List archived VMs |
Lifecycle & Power
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/start | POST | Start VM |
/vms/:id/stop | POST | Stop VM |
/vms/:id/restart | POST | Restart VM |
/vms/:id/pause | POST | Pause VM |
/vms/:id/resume | POST | Resume VM |
/vms/:id/lifecycle | GET | Get lifecycle status |
/vms/:id/lifecycle/permanent | POST | Make permanent |
/vms/:id/lifecycle/temporary | POST | Make temporary |
/vms/:id/lifecycle/ttl | PUT | Update TTL |
/vms/:id/lifecycle | DELETE | Destroy VMs |
/vms/:id/ping | POST | Keep-alive (renew TTL) |
VM Runtime
Command execution, terminal sessions, file operations, search, and file watchers run inside the VMs on a separate API surface. See the VM Runtime API docs for the full endpoint reference.
The Runtime API uses
vm.oblien.com(gateway) or10.x.x.x:9990(direct) - notapi.oblien.com.
Network
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/network | GET | Get network config |
/vms/:id/network | PATCH | Update network (firewall + private links) |
/vms/:id/network/ip | POST | Apply outbound IP |
SSH
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/ssh | GET | SSH status |
/vms/:id/ssh/enable | POST | Enable SSH |
/vms/:id/ssh/disable | POST | Disable SSH |
/vms/:id/ssh/password | POST | Set password |
/vms/:id/ssh/key | POST | Set authorized key |
Public Access
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/public-access | GET | List exposed ports |
/vms/:id/public-access | POST | Expose a port |
/vms/:id/public-access/:port | PATCH | Update port slug |
/vms/:id/public-access/:port | DELETE | Revoke a port |
Resources
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/resources | GET | Get resources |
/vms/:id/resources | PUT | Update resources |
Snapshots & Archives
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/snapshot | POST | Create snapshot |
/vms/:id/restore | POST | Restore snapshot |
/vms/:id/archives | POST | Create archive |
/vms/:id/archives | GET | List archives |
/vms/:id/archives/:version | GET | Get archive |
/vms/:id/archives/:version | DELETE | Delete archive |
/vms/:id/archives | DELETE | Delete all archives |
Workloads
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/workloads | POST | Create workload |
/vms/:id/workloads | GET | List workloads |
/vms/:id/workloads/:wid | GET | Get workload |
/vms/:id/workloads/:wid | PUT | Update workload |
/vms/:id/workloads/:wid | DELETE | Delete workload |
/vms/:id/workloads | DELETE | Delete all |
/vms/:id/workloads/:wid/start | POST | Start workload |
/vms/:id/workloads/:wid/stop | POST | Stop workload |
/vms/:id/workloads/:wid/status | GET | Workload status |
/vms/:id/workloads/:wid/logs | GET | Workload logs |
/vms/:id/workloads/:wid/logs/stream | GET | Stream logs (SSE) |
/vms/:id/workloads/:wid/stats | GET | Workload stats |
/vms/:id/workloads/:wid/stats/stream | GET | Stream stats (SSE) |
/vms/:id/workloads/stats/stream | GET | Stream all workloads stats (SSE) |
Monitoring
| Endpoint | Method | Description |
|---|---|---|
/analytics/home/summary | GET | Analytics: all domains summary |
/analytics/:domain | GET | Analytics: unified (overview + timeseries + geo + requests) |
/analytics/:domain/timeseries | GET | Analytics: time-bucketed metrics |
/analytics/:domain/geo | GET | Analytics: country breakdown |
/analytics/:domain/requests | GET | Analytics: raw request logs |
/analytics/:domain/live/token | POST | Analytics: SSE stream token |
/vms/:id/stats | GET | Current stats |
/vms/:id/stats/stream | GET | Stream stats (SSE) |
/vms/:id/info | GET | VM info |
/vms/:id/config | GET | VM config |
/vms/usage | GET | Global usage |
/vms/activity | GET | Activity history |
/vms/:id/usage | GET | VM usage |
/vms/:id/usage/totals | GET | Usage totals |
/vms/:id/usage/credits/chart | GET | Credits chart |
/vms/:id/usage/tracking/start | POST | Start tracking |
/vms/:id/usage/tracking/stop | POST | Stop tracking |
/vms/:id/usage | DELETE | Wipe usage data |
Logs
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/logs | GET | Get logs |
/vms/:id/logs | DELETE | Clear logs |
/vms/:id/logs/list | GET | List log files |
/vms/:id/logs/file/:name | GET | Get log file |
/vms/:id/logs/stream/boot | GET | Stream boot logs (SSE) |
/vms/:id/logs/stream/cmd | GET | Stream cmd logs (SSE) |
Metadata
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/metadata | GET | Get metadata |
/vms/:id/metadata | PUT | Update metadata |
Runtime API Access
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/runtime-api-access | GET | Server status |
/vms/:id/runtime-api-access/enable | POST | Enable server |
/vms/:id/runtime-api-access/disable | POST | Disable server |
/vms/:id/runtime-api-access/token | GET | Get gateway JWT |
/vms/:id/runtime-api-access/token | POST | Rotate token |
/vms/:id/runtime-api-access/token/raw | GET | Raw token + VM IP |
Custom Domains
| Endpoint | Method | Description |
|---|---|---|
/vms/:id/domain | GET | Get domain config |
/vms/:id/domain | POST | Connect custom domain |
/vms/:id/domain | DELETE | Disconnect domain |
/vms/:id/domain/check | POST | Check DNS |
/vms/:id/domain/ssl/renew | POST | Renew SSL |
/domain/check-slug | POST | Check slug availability |
/domain/verify | POST | Verify domain DNS |
Images
| Endpoint | Method | Description |
|---|---|---|
/vms/images | GET | Image catalog |
Namespaces
| Endpoint | Method | Description |
|---|---|---|
/namespaces | POST | Create namespace |
/namespaces | GET | List namespaces |
/namespaces/:identifier | GET | Get namespace |
/namespaces/:id | PUT | Update namespace |
/namespaces/:id | DELETE | Delete namespace |
/namespaces/:id/suspend | POST | Suspend namespace |
/namespaces/:id/activate | POST | Activate namespace |
/namespaces/:id/stop-vms | POST | Stop all VMs |
/namespaces/:id/activity | GET | Namespace activity |
/namespaces/:id/usage | GET | Namespace usage |
Pages
| Endpoint | Method | Description |
|---|---|---|
/pages | GET | List pages |
/pages | POST | Create page |
/pages/:slug | GET | Get page |
/pages/:slug | PUT | Update page |
/pages/:slug | DELETE | Delete page |
/pages/:slug/deploy | POST | Re-deploy files |
/pages/:slug/enable | POST | Enable page |
/pages/:slug/disable | POST | Disable page |
/pages/:slug/domain | GET | Get domain config |
/pages/:slug/domain | POST | Connect custom domain |
/pages/:slug/domain | DELETE | Disconnect domain |
/pages/:slug/domain/check | POST | Check DNS |
/pages/:slug/domain/ssl/renew | POST | Renew SSL |
Edge Proxy
| Endpoint | Method | Description |
|---|---|---|
/edge/proxies | GET | List proxies |
/edge/proxies | POST | Create proxy |
/edge/proxies/:id | GET | Get proxy |
/edge/proxies/:id | PUT | Update proxy |
/edge/proxies/:id | DELETE | Delete proxy |
/edge/proxies/:id/enable | POST | Enable proxy |
/edge/proxies/:id/disable | POST | Disable proxy |
Billing
| Endpoint | Method | Description |
|---|---|---|
/billing/catalog | GET | List plans + credit packs (public) |
/billing/checkout | POST | Start a namespace-bound checkout |
/billing/portal | POST | Open this namespace's customer billing portal |
/billing/subscription | GET | Read a namespace's subscription and scheduled cancellation |
/billing/subscription/cancel | POST | Cancel renewal at the end of the paid period |
/billing/subscription/resume | POST | Undo a scheduled cancellation |
/billing/entitlement | GET | Read a namespace's plan + quota |
/billing/balance | GET | Fast "can it keep spending?" check |
/billing/policy/:namespace | GET | Read a namespace's allowance policy |
/billing/policy/:namespace | PUT | Set a namespace's allowance policy |
/billing/policy/:namespace/reset | POST | Reset a quota cycle when you collect payment yourself |
/billing/defaults | GET | Read default policy for new namespaces |
/billing/defaults | PUT | Set default policy for new namespaces |
/billing/account/tier | PUT | Set account tier (platform operator only) |