A workspace 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 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 for those, and a workspace job 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/<name> |
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/<name> |
Returns one workspace, or 404 if it doesn't exist or you can't open it. |
POST /workspaces/<name>/start |
Starts a stopped workspace. |
POST /workspaces/<name>/stop |
Stops a running one. |
POST /workspaces/<name>/restart |
Restarts a running one. |
DELETE /workspaces/<name> |
Deletes a workspace. Its home volume stays. |
Authentication
Send a personal API key in the Authorization header, access key id and secret joined by a colon:
Authorization: Bearer <ACCESS_KEY_ID>:<SECRET_ACCESS_KEY>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 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 containersand management keys get403, and so does an org application key.
Creating a volume or a workspace also needs compute access on your account.
Pick a template
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:
{
"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 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:
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:
{
"success": true,
"body": [
{
"cluster": "gpu-cluster",
"tiers": [
{
"storageClassName": "standard",
"displayName": "Standard",
"quota": "1Ti",
"usedBytes": 107374182400,
"availableBytes": 992137445376
}
]
}
]
}Then create the volume:
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:
{
"success": true,
"total": {
"namespace": "...",
"name": "ci-home-ab1cd",
"displayName": "ci home"
}
}Launch a workspace
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. 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/<name>. |
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 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:
{
"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:
curl -s "https://privatemind.com/api/v1/workspaces/pytorch-gpu-ab1cd" \
-H "Authorization: Bearer $PMIND_KEY"{
"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
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.
stopgives back what the workspace was using, its GPU included, and keeps everything else.startasks for that room again, so it's refused when there is none, such as no free GPU on its cluster. It answersPending, so read the workspace until it saysActive, as after a launch.restartcloses 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
curl -s -X DELETE "https://privatemind.com/api/v1/workspaces/pytorch-gpu-ab1cd" \
-H "Authorization: Bearer $PMIND_KEY"{
"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:
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:
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##*{{CONTENT}}#x27;\n'}
out=${out%{{CONTENT}}#x27;\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:
api -X DELETE "$API/workspaces/$ws" > /dev/null
api -X DELETE "$API/volumes/$vol" > /dev/nullLeave 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. |