HTTP

Everything the Python SDK and super CLI do goes through a versioned JSON API at https://api.supercomputer.sh/v1. Use it directly from any language or from curl. This page documents the routes a user API key can call. Internal and admin routes are not covered.

Authentication

Every request carries a user API key as a bearer token. Keys start with super_sk_; get one from super login or the dashboard.

curl -s https://api.supercomputer.sh/v1/auth/identity \
  -H "Authorization: Bearer $SUPERCOMPUTER_API_KEY"
# {"user_id":"u_...","role":"member","team_ids":[]}

Request bodies are JSON with Content-Type: application/json. Timestamps are RFC 3339. Money is in USD micros (1000000 = $1.00). SKU names are the public short names from GET /v1/skus (for example h100, cpu).

Errors

Errors are JSON with an error message, often a machine-readable code, and a request_id to quote in support requests.

{"error": "job_not_found", "code": "job_not_found", "request_id": "..."}

Image specs

image_spec is optional. A session or job that names no image boots the default image for its SKU: the CUDA training image (torch, torchvision, transformers, vLLM pinned) on any GPU box, a slim Python image on a CPU box. These are the images the CLI and SDK boot by default, already baked across the fleet, so they start fastest.

To boot something else, image_spec is a JSON document, sent as a string, describing the image to build: a base registry reference and an ordered list of layers. The smallest valid spec is a bare registry image:

{"base": "pytorch/pytorch:2.9.1-cuda12.8-cudnn9-runtime",
 "layers": [{"type": "base", "params": {"image": "pytorch/pytorch:2.9.1-cuda12.8-cudnn9-runtime"}}]}

Layer types are base, apt_install (packages), pip_install (packages, optional index_url), run_commands (commands) and env (variables). The Python SDK's Image class builds these; call json.dumps(image.to_dict()) to get the string. Images are cached across the fleet by the hash of the spec text, so send a spec byte for byte as you sent it before to hit the cache.

Sessions

A session is a persistent /workspace filesystem that a host brings online on demand. Create one, poll it until it is ready, then run work on it.

Create a session

POST /v1/sessions

Send an Idempotency-Key header to make retries safe; see retrying session creation.

curl -s -X POST https://api.supercomputer.sh/v1/sessions \
  -H "Authorization: Bearer $SUPERCOMPUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"sku": "h100"}'

Replies:

• 202 with status: "queued" or "allocating" and retry_after_s: no host yet. Poll GET /v1/sessions/{sid}.
• 200 with status: "active": the allocation. Fields: sid, cid, hid, host_addr, cert_sha256, token, token_exp, engine, ephemeral.

host_addr, token and cert_sha256 are what the SDK uses to open the host WebSocket for exec, spawn and streaming. That protocol is not documented here; use the Python SDK to run commands, and the HTTP routes below for everything around them.

Read a session

GET /v1/sessions/{sid}

The status code tracks the lifecycle so pollers never infer it from shape:

Every shape carries sid, status, activity, detail, sku_preference, setup_acked, client_attached, created_at and the stage timestamps.

List sessions

GET /v1/sessions?status=active&limit=100&before=<rfc3339>&include_retired=1

status defaults to active. Returns {"sessions": [...], "limit", "has_more", "next_before"}; pass next_before as before for the next page. Limit is capped at 500.

Lifecycle actions

Files on a live session

These go through the host, for callers that cannot open the WebSocket.

• POST /v1/sessions/{sid}/files with {"files": [{"path", "content_b64", "mode"}]} writes files into /workspace. Reply: {"ok", "written", "skipped"}.
• GET /v1/sessions/{sid}/files/{path} returns the file bytes, typed by extension. Files over the host inline cap return 413 file_too_large; read those through /v1/fs after the next publish.

Processes and logs

Durable, served from object storage, so they work after the host is gone.

• GET /v1/sessions/{sid}/processes returns {"processes": [...], "session_status"}. Each process has process_id, command (argv list), status, exit_code, started_at_ms, ended_at_ms, output_bytes.
• GET /v1/sessions/{sid}/processes/{pid}/logs?stream=stdout|stderr|both&output=all|tail&output_bytes=N&offset=N returns raw log bytes.
• GET /v1/sessions/{sid}/logs returns the tail of every process's log, concatenated under ==> command [pid] status <== headers.

Cost and history

• GET /v1/sessions/{sid}/cost returns {"sid", "compute_usd_micros", "billable_seconds", "intervals": [{"state", "billable", "started_at", "ended_at", "seconds", "sku", "price_usd_micros_per_hour", "amount_usd_micros", "open"}]}.
• GET /v1/sessions/{sid}/history?limit=N returns {"sid", "status", "lifecycle", "activity", "events": [...], "count", "truncated"}.

Jobs

A job fans one or more commands out as a durable sweep. Each task runs in its own session. See Batch for the model.

Submit a job

POST /v1/jobs

Reply: 200 {"job": {...}, "created": true|false}. Inline workspace manifests are also accepted but require uploading blobs first; use the SDK for that path.

curl -s -X POST https://api.supercomputer.sh/v1/jobs \
  -H "Authorization: Bearer $SUPERCOMPUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{"name": "lr-sweep", "sku": "h100",
 "commands": ["python train.py --lr 1e-3", "python train.py --lr 3e-4"]}
EOF

Read and manage jobs

{id} accepts a job id or a job name you own.

Job states: waiting, canarying, running, canceling, succeeded, succeeded_partial, failed, canceled. Task states: pending, launching, running, succeeded, failed, canceled. Each task carries index, command, state, attempts, exit_code, error_sig, session_id, process_id.

Volumes

Named, versioned filesystems you mount into sessions.

Filesystem browse

Session workspaces and volumes are served read-only from object storage:

• GET /v1/fs/{sid}/ and GET /v1/volumes/{name}/fs/ list a directory as HTML. Add ?format=json for {"files": [{"path", "size", "hash"}]} under that prefix.
• GET /v1/fs/{sid}/path/to/file redirects to a short-lived signed download URL. Range requests work.
• POST /v1/fs/{sid}/mount-url returns {"token", "path", "expires_at"}. Mount https://api.supercomputer.sh{path} with rclone or any WebDAV-less HTTP mount; no header needed. Ephemeral sessions return 410.

An active session lists files as of its last background sync. A closing session waits for the final manifest.

Catalog

• GET /v1/skus returns {"skus": [{"name", "label", "vram_gb", "vcpus", "ram_gb", "cost_per_hr", "availability", "effective_concurrency"}], "catalog_status"}. availability is live when idle hosts exist now.
• GET /v1/billing/prices returns {"prices": [...]}, the current rate card by SKU.
• GET /v1/health is unauthenticated: {"ok": true, "service": "dispatcher-v2"}.
• GET /v1/auth/identity returns {"user_id", "role", "team_ids"} for the key in use.

Billing

Copy groups

POST /v1/copy-groups takes a session create body plus "size": 2..4 and places that many identical sessions together for multi-node work. Reply: 202 {"group_id", "sessions": [...]}. GET /v1/copy-groups/{id} returns {"group", "sessions"} and keeps queued members alive.

Client headers

The SDK sends X-Supercomputer-Client and X-Supercomputer-Client-Version. They are optional. A client that sends a version below the deployment's floor gets 426 client_too_old; a request with no version header is never refused on that basis.