# Workspaces Create, run and delete workspaces and their volumes over HTTP. A [workspace](https://docs.privatemind.com/workspaces.html) is your own dev environment on your org's GPUs. This API lets a script make a home volume, launch a workspace on it, start, stop and restart it, and delete both when you're done. [From start to finish](https://docs.privatemind.com/workspaces-api.html#from-start-to-finish) does all of that in one script. The API can't run anything inside a workspace or open its JupyterLab, VS Code or terminal. Use the browser or [SSH](https://docs.privatemind.com/workspaces.html#connect-from-your-own-machine-ssh) for those, and a [workspace job](https://docs.privatemind.com/sdk-jobs.html) for a command that runs unattended. A workspace's size, sharing and owner change only on the Workspaces page. All paths below are on `https://privatemind.com/api/v1`. | Request | Does | |---|---| | `GET /workspaces/templates` | Lists the workspace types your org can launch. | | `GET /volumes/storage-tiers` | Lists the storage tiers you can put a volume on, per cluster. | | `GET /volumes` | Lists the volumes you can see. | | `POST /volumes` | Creates a volume. | | `DELETE /volumes/` | Deletes a volume and every file on it. | | `GET /workspaces` | Lists the workspaces you can see on the Workspaces page. | | `POST /workspaces` | Launches a workspace. | | `GET /workspaces/` | Returns one workspace, or `404` if it doesn't exist or you can't open it. | | `POST /workspaces//start` | Starts a stopped workspace. | | `POST /workspaces//stop` | Stops a running one. | | `POST /workspaces//restart` | Restarts a running one. | | `DELETE /workspaces/` | Deletes a workspace. Its home volume stays. | ## Authentication Send a personal [API key](https://docs.privatemind.com/api-keys.html) in the `Authorization` header, access key id and secret joined by a colon: ```text Authorization: Bearer : ``` What each key can do: - A personal key can make every call above, acting as you. - A workspace or a job carries its own key, which the [Python SDK](https://docs.privatemind.com/sdk.html) and the coding agent use inside it. That key can list, read, start and stop workspaces. Other calls answer it `403`. - `Inference only`, `Inference and containers` and management keys get `403`, and so does an org application key. Creating a volume or a workspace also needs compute access on your account. ## Pick a template ```bash curl -s "https://privatemind.com/api/v1/workspaces/templates" \ -H "Authorization: Bearer $PMIND_KEY" ``` `body` holds the templates. Each has the `name` a launch takes, a `display_name` and `description`, its standard `memory_gib`, the surfaces it serves in `access_modes`, and its `versions`: ```json { "success": true, "body": [ { "name": "pytorch-gpu", "display_name": "PyTorch ยท GPU", "description": "GPU workspace for deep learning. PyTorch with CUDA, plus Jupyter, VS Code, and a terminal.", "memory_gib": 32, "shared_memory_gib": 4, "access_modes": ["jupyter", "vscode", "terminal", "ssh"], "versions": [ { "version": "1.4.36", "guidance": "stable", "released": "2026-11-15", "notes": "..." } ] } ] } ``` ## Make a home volume A workspace mounts a volume as its home directory, and the volume outlives the workspace. A volume is home to one workspace at a time. If you already have a volume, skip to [Launch a workspace](https://docs.privatemind.com/workspaces-api.html#launch-a-workspace) and pass its name. `GET /volumes` lists yours in `body`, each with its full name in `metadata.name` and its `size`, `storageClassName` and `targetCluster` in `spec`. To make one, list your org's storage tiers: ```bash curl -s "https://privatemind.com/api/v1/volumes/storage-tiers" \ -H "Authorization: Bearer $PMIND_KEY" ``` `body` holds one entry per cluster your org can use, with its tiers. `availableBytes` is what's left of your org's quota on that tier. A volume still being deleted counts against the quota until it's gone: ```json { "success": true, "body": [ { "cluster": "gpu-cluster", "tiers": [ { "storageClassName": "standard", "displayName": "Standard", "quota": "1Ti", "usedBytes": 107374182400, "availableBytes": 992137445376 } ] } ] } ``` Then create the volume: ```bash curl -s -X POST "https://privatemind.com/api/v1/volumes" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "ci home", "size": "50Gi", "target_cluster": "gpu-cluster", "storage_class": "standard" }' ``` | Field | Required | Notes | |---|---|---| | `label` | yes | The name shown in the app. The volume's full name is generated from it. | | `size` | yes | A whole number with `Mi`, `Gi` or `Ti`, such as `50Gi`. | | `target_cluster` | yes | A `cluster` from the storage tiers. | | `storage_class` | yes | A `storageClassName` from that cluster's tiers. | | `visibility` | no | `private` (the default), `shared` for your org, or `personal`. No one else can mount or open a personal volume, org admins included, and it can't be made anything else later. An org admin can still delete it. | The response is `201`, with the volume's full name in `total.name`. A launch takes that name as `home_volume`: ```json { "success": true, "total": { "namespace": "...", "name": "ci-home-ab1cd", "displayName": "ci home" } } ``` ## Launch a workspace ```bash curl -s -X POST "https://privatemind.com/api/v1/workspaces" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{ "template": "pytorch-gpu", "home_volume": "ci-home-ab1cd", "gpus": 1, "label": "nightly eval" }' ``` | Field | Required | Notes | |---|---|---| | `template` | yes | A `name` from the templates list. | | `home_volume` | yes | The full name of a volume you can use. | | `target_cluster` | no | Defaults to the home volume's cluster. | | `gpus` | no | How many GPUs, or MIG slices in `Shared` mode. Defaults to 0, a CPU workspace. | | `gpu_host`, `gpu_indices` | no | Name both to pin the cards, one index per GPU, from your org's hosts in [`/api/v1/model-servers/allocations`](https://docs.privatemind.com/model-servers-api.html#see-what-you-can-run). Leave both out and free cards are picked for you. | | `gpu_sharing_mode` | no | `Exclusive`, the default, or `Shared` for a MIG slice. `Shared` needs `gpu_host` and exactly one index in `gpu_indices`. | | `cpu` | no | vCPU as a string, such as `"8"`. Leave it out for the template's standard size. | | `memory` | no | Memory as a string with `Mi`, `Gi` or `Ti`, such as `"64Gi"`. | | `shared_memory` | no | The size of `/dev/shm`, such as `"16Gi"`. It comes out of `memory`. | | `extra_volumes` | no | More volumes to mount, by full name. Each appears under `~/mounts/`. | | `label` | no | The name shown in the app, up to 64 characters. Defaults to `Workspace 1`, `Workspace 2` and so on. | | `visibility` | no | `private`, the default, or `shared` for your org. A workspace on a personal volume is personal whatever you send. | | `template_version` | no | A version from the template's `versions` whose `guidance` is `stable`, such as `"1.4.36"`, to hold the workspace on it. Leave it out to take the current one. | | `net_profile` | no | A network profile your org offers, by slug. | | `startup_dir` | no | The folder the terminal, VS Code and the coding agent open in, under your home directory. | | `secrets` | no | [Secrets](https://docs.privatemind.com/secrets.html) to attach, as a list of ids or names, as the Secrets page shows them. | An unknown field, such as `homeVolume`, answers `400` with the field's name. The response is `201`, with the workspace's generated `name`: ```json { "success": true, "name": "pytorch-gpu-ab1cd", "label": "nightly eval", "phase": "Pending", "template": "pytorch-gpu", "cluster": "gpu-cluster", "gpus": 1 } ``` ## Wait for it to come up A new workspace answers `Pending` while it starts. Read it until `phase` says `Active`: ```bash curl -s "https://privatemind.com/api/v1/workspaces/pytorch-gpu-ab1cd" \ -H "Authorization: Bearer $PMIND_KEY" ``` ```json { "success": true, "name": "pytorch-gpu-ab1cd", "label": "nightly eval", "phase": "Active", "template": "pytorch-gpu", "cluster": "gpu-cluster", "gpus": 1 } ``` | `phase` | Meaning | |---|---| | `Pending` | Starting, or waiting for room on its cluster. | | `Active` | Up. Open it from the Workspaces page or connect over SSH. | | `Stopped` | Stopped, with its files and settings kept. | | `Failed` | It started and crashed. | | `Deleting` | On its way out. | ## Start, stop and restart ```bash curl -s -X POST "https://privatemind.com/api/v1/workspaces/pytorch-gpu-ab1cd/stop" \ -H "Authorization: Bearer $PMIND_KEY" ``` Only the workspace's owner or an org admin can start, stop, restart or delete it, even when it's shared. `start`, `stop` and `restart` each answer with the workspace, as above. - `stop` gives back what the workspace was using, its GPU included, and keeps everything else. - `start` asks for that room again, so it's refused when there is none, such as no free GPU on its cluster. It answers `Pending`, so read the workspace until it says `Active`, as after a launch. - `restart` closes everything running in the workspace. `start` and `restart` both bring the workspace back on its template's current version, unless you set `template_version` to hold it on a version. `start` and `stop` are safe to repeat: starting a running workspace or stopping a stopped one changes nothing. ## Delete a workspace and its volume ```bash curl -s -X DELETE "https://privatemind.com/api/v1/workspaces/pytorch-gpu-ab1cd" \ -H "Authorization: Bearer $PMIND_KEY" ``` ```json { "success": true, "total": { "namespace": "...", "name": "pytorch-gpu-ab1cd", "deleted": true } } ``` Deleting a workspace ends it and revokes the keys it carried. Its home volume and extra volumes stay, with every file on them. Deleting one that's already gone answers `404`. To delete the volume as well: ```bash curl -s -X DELETE "https://privatemind.com/api/v1/volumes/ci-home-ab1cd" \ -H "Authorization: Bearer $PMIND_KEY" ``` This deletes every file on the volume, and it can't be undone. Only the volume's owner or an org admin can delete it. If a workspace still mounts the volume, the call answers `409` with each such workspace's label in `total.holders[].workspace`. Add `?confirm=true` to delete those workspaces along with it. If a job is still running on the volume, the call answers `409` until the job ends. ## From start to finish This script launches a GPU workspace on a new volume and waits for it to come up, deleting the volume again if the launch fails. It needs `curl` and `jq`, and prints the reason when a call is refused: ```bash set -euo pipefail API=https://privatemind.com/api/v1 api() { local out code out=$(curl -s -w '\n%{http_code}' -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" "$@") code=${out##*$'\n'} out=${out%$'\n'*} [ "$code" -lt 400 ] || { echo "refused ($code): $out" >&2; return 1; } printf '%s' "$out" } vol=$(api -X POST "$API/volumes" \ -d '{"label": "my home", "size": "50Gi", "target_cluster": "gpu-cluster", "storage_class": "standard"}' \ | jq -r .total.name) trap 'api -X DELETE "$API/volumes/$vol?confirm=true" > /dev/null' ERR ws=$(api -X POST "$API/workspaces" \ -d "{\"template\": \"pytorch-gpu\", \"home_volume\": \"$vol\", \"gpus\": 1, \"label\": \"gpu box\"}" \ | jq -r .name) for i in $(seq 60); do phase=$(api "$API/workspaces/$ws" | jq -r .phase) [ "$phase" = Active ] || [ "$phase" = Failed ] && break sleep 10 done [ "$phase" = Active ] || { echo "$ws is $phase after waiting" >&2; false; } trap - ERR echo "$ws is up on $vol" ``` When you're done, take both down with the same `api` helper: ```bash api -X DELETE "$API/workspaces/$ws" > /dev/null api -X DELETE "$API/volumes/$vol" > /dev/null ``` Leave out the second line to keep your files for next time, and pass the same volume to the next launch. ## Errors A refused call has `"success": false` and the reason in `error` or `message`. `error` is usually a string, but can be an object with a `type` and `message`. | Status | Cause | |---|---| | `400` | A missing or unknown field, a value of the wrong type, or a home volume that doesn't exist when no `target_cluster` is given. | | `401` | A key that isn't valid, or no key at all. A create with no key answers `403`. | | `402` | The key's budget is spent. | | `403` | The account or key can't do this: no key on a create, no compute access, a key type these routes refuse, not the workspace's or volume's owner or an org admin, a volume that doesn't exist or is private to someone else, a home volume another workspace is using, a personal limit on a launch or start, or no room for the org on that cluster. `error` says which. | | `404` | No such workspace or volume, a workspace you can't open on a read, or a secret name that doesn't exist. | | `409` | No free GPU for a launch or start, the org's workspace or volume count is full, the storage tier is full, a personal storage limit, a restricted network on a shared workspace, a secret name that matches more than one, or a volume still in use. | | `5xx` | Something failed on our side. Retry reads. Check before retrying a launch. |