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
Workspace TokenAuthorization: Bearer <token>Client-side / scoped access

See Authentication for setup details.

Response format

Every response follows a consistent structure:

Success:

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

Error:

{
  "success": false,
  "error": "Human-readable error message"
}

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

Core

EndpointMethodDescription
/workspacePOSTCreate workspace
/workspaceGETList workspaces
/workspace/:idGETGet workspace
/workspace/:idPUTUpdate workspace
/workspace/:idDELETEDelete workspace
/workspace/:id/detailsGETAggregated details
/workspace/quotaGETResource quota

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/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 Internal API docs for the full endpoint reference.

The Internal 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/networkPUTReplace network
/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/:portDELETERevoke a port

Filesystem

EndpointMethodDescription
/workspace/:id/overlayGETList files
/workspace/:id/overlay/filesGETRead file
/workspace/:id/overlay/filesPOSTWrite file
/workspace/:id/overlay/usageGETDisk usage
/workspace/:id/overlay/resizePUTResize disk
/workspace/:id/overlay/syncPOSTSync overlay

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)

Monitoring

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

Other

EndpointMethodDescription
/workspace/:id/metadataGETGet metadata
/workspace/:id/metadataPUTUpdate metadata
/workspace/:id/api-access/tokenPOSTRotate token
/workspace/:id/api-access/enablePOSTEnable server
/workspace/:id/api-access/disablePOSTDisable server
/workspace/:id/logsGETGet logs
/workspace/:id/logsDELETEClear logs
/workspace/:id/logs/stream/bootGETStream boot logs
/workspace/:id/logs/stream/cmdGETStream cmd logs
/workspace/imagesGETImage catalog

SDK Setup

Install and configure the Oblien Workspace SDK

Filesystem

Read, write, and manage files inside your workspace

On this page

API Reference
Base URL
Authentication
Response format
Common HTTP status codes
Endpoint map
Core
Lifecycle & Power
Workspace Runtime
Network
SSH
Public Access
Filesystem
Resources
Snapshots & Archives
Workloads
Monitoring
Other