API Reference

API Reference

Complete reference for every Workspace API endpoint. Each page shows both SDK and REST API syntax side by side.

Base URL

https://api.oblien.com

Authentication

All requests require one of:

MethodHeadersUse case
API KeyX-Client-ID + X-Client-SecretServer-side / SDK
Scoped TokenAuthorization: Bearer <jwt>Namespace or workspace scoped access
Workspace TokenAuthorization: Bearer <token>Client-side / single workspace access

See Authentication for setup details.

Response format

Every response follows a consistent structure:

Success:

{
  "success": true,
  "workspace": { ... }
}

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 workspace)

Core

EndpointMethodDescription
/workspacePOSTCreate workspace
/workspaceGETList workspaces
/workspace/:idGETGet workspace
/workspace/:idPUTUpdate workspace
/workspace/:idDELETEDelete workspace
/workspace/:id/detailsGETAggregated details
/workspace/quotaGETResource quota
/workspace/estimateGETEstimate monthly credits
/workspace/archivedGETList archived workspaces

Lifecycle & Power

EndpointMethodDescription
/workspace/:id/startPOSTStart workspace
/workspace/:id/stopPOSTStop workspace
/workspace/:id/restartPOSTRestart workspace
/workspace/:id/pausePOSTPause workspace
/workspace/:id/resumePOSTResume workspace
/workspace/:id/lifecycleGETGet lifecycle status
/workspace/:id/lifecycle/permanentPOSTMake permanent
/workspace/:id/lifecycle/temporaryPOSTMake temporary
/workspace/:id/lifecycle/ttlPUTUpdate TTL
/workspace/:id/lifecycleDELETEDestroy workspace VM
/workspace/:id/pingPOSTKeep-alive (renew TTL)

Workspace Runtime

Command execution, terminal sessions, file operations, search, and file watchers run inside the workspace VM on a separate API surface. See the Workspace Runtime API docs for the full endpoint reference.

The Runtime API uses workspace.oblien.com (gateway) or 10.x.x.x:9990 (direct) - not api.oblien.com.

Network

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

SSH

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

Public Access

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

Resources

EndpointMethodDescription
/workspace/:id/resourcesGETGet resources
/workspace/:id/resourcesPUTUpdate resources

Snapshots & Archives

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

Workloads

EndpointMethodDescription
/workspace/:id/workloadsPOSTCreate workload
/workspace/:id/workloadsGETList workloads
/workspace/:id/workloads/:widGETGet workload
/workspace/:id/workloads/:widPUTUpdate workload
/workspace/:id/workloads/:widDELETEDelete workload
/workspace/:id/workloadsDELETEDelete all
/workspace/:id/workloads/:wid/startPOSTStart workload
/workspace/:id/workloads/:wid/stopPOSTStop workload
/workspace/:id/workloads/:wid/statusGETWorkload status
/workspace/:id/workloads/:wid/logsGETWorkload logs
/workspace/:id/workloads/:wid/logs/streamGETStream logs (SSE)
/workspace/:id/workloads/:wid/statsGETWorkload stats
/workspace/:id/workloads/:wid/stats/streamGETStream stats (SSE)
/workspace/: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
/workspace/:id/statsGETCurrent stats
/workspace/:id/stats/streamGETStream stats (SSE)
/workspace/:id/infoGETVM info
/workspace/:id/configGETVM config
/workspace/usageGETGlobal usage
/workspace/activityGETActivity history
/workspace/:id/usageGETWorkspace usage
/workspace/:id/usage/totalsGETUsage totals
/workspace/:id/usage/credits/chartGETCredits chart
/workspace/:id/usage/tracking/startPOSTStart tracking
/workspace/:id/usage/tracking/stopPOSTStop tracking
/workspace/:id/usageDELETEWipe usage data

Logs

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

Metadata

EndpointMethodDescription
/workspace/:id/metadataGETGet metadata
/workspace/:id/metadataPUTUpdate metadata

Runtime API Access

EndpointMethodDescription
/workspace/:id/runtime-api-accessGETServer status
/workspace/:id/runtime-api-access/enablePOSTEnable server
/workspace/:id/runtime-api-access/disablePOSTDisable server
/workspace/:id/runtime-api-access/tokenGETGet gateway JWT
/workspace/:id/runtime-api-access/tokenPOSTRotate token
/workspace/:id/runtime-api-access/token/rawGETRaw token + VM IP

Custom Domains

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

Images

EndpointMethodDescription
/workspace/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-workspacesPOSTStop all workspaces
/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

SDK Setup

Install and configure the Oblien Workspace SDK

Analytics

Traffic analytics, bandwidth metrics, geo breakdown, request logs, and live streaming for your domains

On this page

API Reference
Base URL
Authentication
Response format
Common HTTP status codes
Endpoint map
Authentication
Core
Lifecycle & Power
Workspace Runtime
Network
SSH
Public Access
Resources
Snapshots & Archives
Workloads
Monitoring
Logs
Metadata
Runtime API Access
Custom Domains
Images
Namespaces
Pages
Edge Proxy