API Reference

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/v1

The 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:

MethodHeadersUse case
API KeyX-Client-ID + X-Client-SecretServer-side / SDK
Scoped TokenAuthorization: Bearer <jwt>Namespace or VM scoped access
VM TokenAuthorization: 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

CodeMeaning
200Success
201Created (new resource)
400Bad request - invalid parameters
401Unauthorized - missing or invalid credentials
402Payment required - quota exceeded
403Forbidden - not your resource
404Not found
409Conflict - resource in wrong state
422Unprocessable - validation failed
429Rate limited - slow down
500Server error
503Service unavailable - VM backend down

Endpoint map

Authentication

EndpointMethodDescription
/tokensPOSTIssue a scoped token (namespace or VM)

Core

EndpointMethodDescription
/vmsPOSTCreate VM
/vmsGETList VMs
/vms/:idGETGet VM
/vms/:idPUTUpdate VM
/vms/:idDELETEDelete VM
/vms/:id/detailsGETAggregated details
/vms/quotaGETResource quota
/vms/estimateGETEstimate monthly credits
/vms/archivedGETList archived VMs

Lifecycle & Power

EndpointMethodDescription
/vms/:id/startPOSTStart VM
/vms/:id/stopPOSTStop VM
/vms/:id/restartPOSTRestart VM
/vms/:id/pausePOSTPause VM
/vms/:id/resumePOSTResume VM
/vms/:id/lifecycleGETGet lifecycle status
/vms/:id/lifecycle/permanentPOSTMake permanent
/vms/:id/lifecycle/temporaryPOSTMake temporary
/vms/:id/lifecycle/ttlPUTUpdate TTL
/vms/:id/lifecycleDELETEDestroy VMs
/vms/:id/pingPOSTKeep-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) or 10.x.x.x:9990 (direct) - not api.oblien.com.

Network

EndpointMethodDescription
/vms/:id/networkGETGet network config
/vms/:id/networkPATCHUpdate network (firewall + private links)
/vms/:id/network/ipPOSTApply outbound IP

SSH

EndpointMethodDescription
/vms/:id/sshGETSSH status
/vms/:id/ssh/enablePOSTEnable SSH
/vms/:id/ssh/disablePOSTDisable SSH
/vms/:id/ssh/passwordPOSTSet password
/vms/:id/ssh/keyPOSTSet authorized key

Public Access

EndpointMethodDescription
/vms/:id/public-accessGETList exposed ports
/vms/:id/public-accessPOSTExpose a port
/vms/:id/public-access/:portPATCHUpdate port slug
/vms/:id/public-access/:portDELETERevoke a port

Resources

EndpointMethodDescription
/vms/:id/resourcesGETGet resources
/vms/:id/resourcesPUTUpdate resources

Snapshots & Archives

EndpointMethodDescription
/vms/:id/snapshotPOSTCreate snapshot
/vms/:id/restorePOSTRestore snapshot
/vms/:id/archivesPOSTCreate archive
/vms/:id/archivesGETList archives
/vms/:id/archives/:versionGETGet archive
/vms/:id/archives/:versionDELETEDelete archive
/vms/:id/archivesDELETEDelete all archives

Workloads

EndpointMethodDescription
/vms/:id/workloadsPOSTCreate workload
/vms/:id/workloadsGETList workloads
/vms/:id/workloads/:widGETGet workload
/vms/:id/workloads/:widPUTUpdate workload
/vms/:id/workloads/:widDELETEDelete workload
/vms/:id/workloadsDELETEDelete all
/vms/:id/workloads/:wid/startPOSTStart workload
/vms/:id/workloads/:wid/stopPOSTStop workload
/vms/:id/workloads/:wid/statusGETWorkload status
/vms/:id/workloads/:wid/logsGETWorkload logs
/vms/:id/workloads/:wid/logs/streamGETStream logs (SSE)
/vms/:id/workloads/:wid/statsGETWorkload stats
/vms/:id/workloads/:wid/stats/streamGETStream stats (SSE)
/vms/:id/workloads/stats/streamGETStream all workloads stats (SSE)

Monitoring

EndpointMethodDescription
/analytics/home/summaryGETAnalytics: all domains summary
/analytics/:domainGETAnalytics: unified (overview + timeseries + geo + requests)
/analytics/:domain/timeseriesGETAnalytics: time-bucketed metrics
/analytics/:domain/geoGETAnalytics: country breakdown
/analytics/:domain/requestsGETAnalytics: raw request logs
/analytics/:domain/live/tokenPOSTAnalytics: SSE stream token
/vms/:id/statsGETCurrent stats
/vms/:id/stats/streamGETStream stats (SSE)
/vms/:id/infoGETVM info
/vms/:id/configGETVM config
/vms/usageGETGlobal usage
/vms/activityGETActivity history
/vms/:id/usageGETVM usage
/vms/:id/usage/totalsGETUsage totals
/vms/:id/usage/credits/chartGETCredits chart
/vms/:id/usage/tracking/startPOSTStart tracking
/vms/:id/usage/tracking/stopPOSTStop tracking
/vms/:id/usageDELETEWipe usage data

Logs

EndpointMethodDescription
/vms/:id/logsGETGet logs
/vms/:id/logsDELETEClear logs
/vms/:id/logs/listGETList log files
/vms/:id/logs/file/:nameGETGet log file
/vms/:id/logs/stream/bootGETStream boot logs (SSE)
/vms/:id/logs/stream/cmdGETStream cmd logs (SSE)

Metadata

EndpointMethodDescription
/vms/:id/metadataGETGet metadata
/vms/:id/metadataPUTUpdate metadata

Runtime API Access

Custom Domains

EndpointMethodDescription
/vms/:id/domainGETGet domain config
/vms/:id/domainPOSTConnect custom domain
/vms/:id/domainDELETEDisconnect domain
/vms/:id/domain/checkPOSTCheck DNS
/vms/:id/domain/ssl/renewPOSTRenew SSL
/domain/check-slugPOSTCheck slug availability
/domain/verifyPOSTVerify domain DNS

Images

EndpointMethodDescription
/vms/imagesGETImage catalog

Namespaces

EndpointMethodDescription
/namespacesPOSTCreate namespace
/namespacesGETList namespaces
/namespaces/:identifierGETGet namespace
/namespaces/:idPUTUpdate namespace
/namespaces/:idDELETEDelete namespace
/namespaces/:id/suspendPOSTSuspend namespace
/namespaces/:id/activatePOSTActivate namespace
/namespaces/:id/stop-vmsPOSTStop all VMs
/namespaces/:id/activityGETNamespace activity
/namespaces/:id/usageGETNamespace usage

Pages

EndpointMethodDescription
/pagesGETList pages
/pagesPOSTCreate page
/pages/:slugGETGet page
/pages/:slugPUTUpdate page
/pages/:slugDELETEDelete page
/pages/:slug/deployPOSTRe-deploy files
/pages/:slug/enablePOSTEnable page
/pages/:slug/disablePOSTDisable page
/pages/:slug/domainGETGet domain config
/pages/:slug/domainPOSTConnect custom domain
/pages/:slug/domainDELETEDisconnect domain
/pages/:slug/domain/checkPOSTCheck DNS
/pages/:slug/domain/ssl/renewPOSTRenew SSL

Edge Proxy

EndpointMethodDescription
/edge/proxiesGETList proxies
/edge/proxiesPOSTCreate proxy
/edge/proxies/:idGETGet proxy
/edge/proxies/:idPUTUpdate proxy
/edge/proxies/:idDELETEDelete proxy
/edge/proxies/:id/enablePOSTEnable proxy
/edge/proxies/:id/disablePOSTDisable proxy

Billing

EndpointMethodDescription
/billing/catalogGETList plans + credit packs (public)
/billing/checkoutPOSTStart a namespace-bound checkout
/billing/portalPOSTOpen this namespace's customer billing portal
/billing/subscriptionGETRead a namespace's subscription and scheduled cancellation
/billing/subscription/cancelPOSTCancel renewal at the end of the paid period
/billing/subscription/resumePOSTUndo a scheduled cancellation
/billing/entitlementGETRead a namespace's plan + quota
/billing/balanceGETFast "can it keep spending?" check
/billing/policy/:namespaceGETRead a namespace's allowance policy
/billing/policy/:namespacePUTSet a namespace's allowance policy
/billing/policy/:namespace/resetPOSTReset a quota cycle when you collect payment yourself
/billing/defaultsGETRead default policy for new namespaces
/billing/defaultsPUTSet default policy for new namespaces
/billing/account/tierPUTSet account tier (platform operator only)