Harthelm Docs
REST APIWorkspaces

Get a workspace

Soft-deleted workspaces stay readable until they are purged.

Generated from openapi/harthelm.yaml at v1.5.0
GET
/workspaces/{ws}

Authorization

cookie__Host-harthelm_session<token>

Browser session of the UI (12 h idle, 7 days absolute). State-changing requests also need the header Harthelm-CSRF: 1 and a matching Origin.

Path Parameters

ws*integer

Numeric resource id.

Formatint64
Range1 <= value

Response Body

The workspace.

application/json
  1. response
id*ID

Numeric resource id.

Formatint64
Range1 <= value
team_id*ID

Numeric resource id.

Formatint64
Range1 <= value
name*string
plan*string

Plan id from the platform's plan list.

base_image*string

Base image id.

git?
storage_gib*integer
Range1 <= value
availability*Availability
Value in"always""on-demand"
restricted*boolean

When true, the workspace hosts are private to team members.

state*WorkspaceState
Value in"creating""cloning""running""sleeping""waking""stopped""error""deleting"
status_detail?string

Progress or error text for the current state, e.g. "Configuring storage", "Cloning repository", "Starting IDE", "Workspace is running".

urls*
dev_service?

The service behind the dev URL urls.dev: the one the route / of the entry host leads to. state is the IDE's business no more: a workspace can be running while this service sleeps. Absent for an older core.

vault_id?ID

Numeric resource id.

Formatint64
Range1 <= value
single_node?boolean

The volume is ReadWriteOnce (rwo-colocated), so every pod of the workspace runs on one node; the UI shows a "single-node workspace" badge. Absent for an older core.

idle_timeout_minutes?integer

Minutes without use before an on-demand IDE sleeps; absent: the installation's default, which GET /workspaces/{ws}/power shows as the IDE's effective timeout.

Range1 <= value <= 1440
last_archived_at?string

When the newest restorable archive of the volume was taken; absent when there is none. A workspace that never sleeps is never archived, so the UI shows the age.

Formatdate-time
restored_from?ID

Numeric resource id.

Formatint64
Range1 <= value
upgrade_pending?boolean

The IDE runs a pod template from before an upgrade of the installation (workspaces.upgradePolicy: keep) and gets the new one when it sleeps or stops; the UI shows an "upgrade pending" badge. Absent for an older core.

created_by?ID

Numeric resource id.

Formatint64
Range1 <= value
owner_id?ID

Numeric resource id.

Formatint64
Range1 <= value
needs_owner?boolean

The owner left the team or was disabled: the git proxy refuses the workspace until a workspace admin names a new owner (PUT /workspaces/{ws}/owner). Absent for an older core.

permissions?array<>

The caller's permissions on the resource; the UI shows only what they allow. Absent for an older core.

created_at*string
Formatdate-time
deleted_at?string

Set on soft-deleted workspaces.

Formatdate-time
purge_after?string

When a soft-deleted workspace is purged for good; restore works until then.

Formatdate-time
curl -X GET 'https://console.example.com/api/v1/workspaces/1'
{  "id": 1,  "team_id": 1,  "name": "string",  "plan": "string",  "base_image": "string",  "git": {    "provider": "string",    "repo": "string",    "ref": "string"  },  "storage_gib": 1,  "availability": "always",  "restricted": true,  "state": "creating",  "status_detail": "string",  "urls": {    "ide": "string",    "dev": "string"  },  "dev_service": {    "name": "string",    "state": "running",    "wake_seconds": 0,    "needs": [      "string"    ],    "failing_needs": [      "string"    ]  },  "vault_id": 1,  "single_node": true,  "idle_timeout_minutes": 1,  "last_archived_at": "2019-08-24T14:15:22Z",  "restored_from": 1,  "upgrade_pending": true,  "created_by": 1,  "owner_id": 1,  "needs_owner": true,  "permissions": [    "string"  ],  "created_at": "2019-08-24T14:15:22Z",  "deleted_at": "2019-08-24T14:15:22Z",  "purge_after": "2019-08-24T14:15:22Z"}

The Overview tab's data

One read for the Overview cockpit: the landscape's services with their status and URLs, the latest run of each stage, the synced and the selected profile. Everything comes from core's database, so it answers while the workspace sleeps and wakes nothing. The UI refetches it on `landscape.updated`, `stage.updated` and `workspace.updated`. Needs `workspace.view`.

List workspaces of a team

The workspaces of one team the caller may see, newest first; with `deleted` the soft-deleted ones that can still be restored. Needs `team.view`.