Get API key

Workspaces

View as Markdown

Create, run and delete workspaces and their volumes over HTTP.

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:

Text
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 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

cURL
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 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
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:

cURL
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

cURL
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:

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:

cURL
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

cURL
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

cURL
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:

cURL
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:

cURL
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:

cURL
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.