Templates
A template is the launch recipe an instance is deployed from: an image, a launch mode, ports, environment variables and an optional onstart script. See Templates for the concept and Launch modes for what each mode does.
List templates
curl -s "$SUPERHEAT_API/v1/templates?tab=recommended&mode=jupyter" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
GET /v1/templates returns one page: {"items": [...], "next_cursor": "…"}. List rows carry readme and onstart as null; fetch a single template for them.
| Parameter | Values | Default | Returns |
|---|---|---|---|
tab | recommended, mine, recent, popular, serverless | recommended | recommended: Superheat's curated system templates. mine: templates owned by the active organization. recent: templates the organization has deployed, most recent first. popular: system and public templates by use count. serverless: a placeholder that returns no items. |
mode | ssh, jupyter, args, vm | none | Only templates with that launch mode |
arch | string | none | Only templates whose constraints.arch matches |
cuda | string | none | Only templates whose constraints.cuda_min matches exactly |
q | string, up to 200 characters | none | Case-insensitive substring match on name, description or image |
limit | 1 to 200 | 100 | Templates per page |
cursor | string | none | The next_cursor of the previous page |
tab is a closed set: a value outside it is rejected with 422 and a validation list naming the parameter. mode, arch and cuda are free-form string matches of up to 32 characters — a value nothing uses returns an empty list rather than an error.
next_cursor is null on the last page. Otherwise pass it back unchanged, with the same filters, to get the next one; treat it as opaque. A client that does not page gets the first 100, which covers every curated template:
CURSOR=""
while :; do
PAGE=$(curl -s "$SUPERHEAT_API/v1/templates?tab=popular&limit=200${CURSOR:+&cursor=$CURSOR}" \
-H "Authorization: Bearer $SUPERHEAT_KEY")
echo "$PAGE" | jq -r '.items[].name'
CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty')
[ -z "$CURSOR" ] && break
done
A cursor the API did not issue is rejected with 422 INVALID_CURSOR.
Template fields
{
"id": "b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56",
"hash_id": "th_4c9e21b7f0a35d68c1e47b902d6af38150c9b7e4a2d81f6035c9e7b402a1d8f6",
"name": "PyTorch (Jupyter)",
"description": "PyTorch with a JupyterLab notebook server, ready to open.",
"image": "vastai/pytorch",
"tag": "[Automatic]",
"docker_image": "vastai/pytorch",
"repo": null,
"href": null,
"launch_mode": "jupyter",
"args_str": null,
"onstart": null,
"env": [],
"ports": [
{"container_port": 8080, "protocol": "http", "label": "Jupyter", "public": true},
{"container_port": 22, "protocol": "tcp", "label": "SSH", "public": true}
],
"constraints": {"cuda_min": "12.1", "min_vram_mb": 8000, "recommended_disk_gb": 40},
"jupyter_dir": "/workspace",
"use_jupyter_lab": true,
"registry_user": null,
"has_registry_password": false,
"readme": null,
"visibility": "system",
"owner_org_id": null,
"created_by": null,
"use_count": 1420,
"coming_soon": false,
"sort_order": 2,
"is_active": true,
"created_at": "2026-05-02T09:14:00.000Z",
"updated_at": "2026-07-11T16:38:21.442Z",
"tags": ["Jupyter", "SSH", "CUDA 12.1", "Automatic"]
}
| Field | Type | Meaning |
|---|---|---|
id | uuid | Stable identity. Pass this as template_id when you deploy. |
hash_id | string, th_ prefix | Content hash of the launch recipe. Re-minted whenever the recipe changes. |
image, tag, docker_image | string | The image, its tag, and the two joined. A tag of [Automatic] resolves to a CUDA-matched tag at launch. |
launch_mode | ssh, jupyter, args, vm | How the container is started |
args_str | string or null | Arguments for args mode |
onstart | string or null | Script delivered to the container as the SUPERHEAT_ONSTART environment variable, never as a file. null in list rows and in the template embedded in an instance |
env | array | {key, value, secret}. Secret values read back as null unless your organization owns the template. |
ports | array | {container_port, protocol, label, public, auth} with protocol tcp, udp, http or https. auth is proxy, app or null — whether the port requires the instance access token; see Requiring the access token |
constraints | object | Any of cuda_min, cuda_max, min_vram_mb, arch, vm_capable, recommended_disk_gb, selectors |
jupyter_dir, use_jupyter_lab | string or null, boolean | JupyterLab working directory and whether Lab is used |
registry_user, has_registry_password | string or null, boolean | Private registry username, and whether a password is stored. The password itself is never returned. |
visibility | system, private, public | system templates are curated by Superheat and immutable through the API |
owner_org_id, created_by | uuid or null | Owning organization and author. Both are null on system templates. |
use_count, coming_soon, sort_order, is_active | integer, boolean, integer, boolean | Catalog metadata |
tags | array of strings | Facet chips derived from the launch mode and constraints |
Port behavior follows the launch mode: ssh templates carry container port 22, jupyter templates carry 22 and 8080, and every other port you declare is labeled as an app port.
The JupyterLab token is minted by the platform and passed down to the workload. You do not set it, and an env override named JUPYTER_TOKEN is ignored — the platform overlay always wins over renter-supplied environment variables. The same token is the instance access token, which a port can require through its auth field; see Requiring the access token.
Get one template
curl -s "$SUPERHEAT_API/v1/templates/b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
You can read system templates, public templates from any organization, and your own organization's private templates. Anything else returns 404 TEMPLATE_NOT_FOUND — including a private template belonging to another organization, which is reported as missing rather than forbidden.
Get a template by hash
curl -s "$SUPERHEAT_API/v1/templates/by-hash/th_4c9e21b7f0a35d68c1e47b902d6af38150c9b7e4a2d81f6035c9e7b402a1d8f6" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
hash_id is the share and launch token. It is stable across cosmetic edits such as the name, description or readme, and is re-minted whenever the launch recipe changes — the image, tag, mode, args, onstart, env, ports, constraints, Jupyter settings or registry user.
Pin hash_id in a pipeline when you need the exact recipe you tested. If the owner changes the recipe, the old hash stops resolving with 404 TEMPLATE_NOT_FOUND, which is a loud failure rather than a silent switch to a different image. Pin id when you want to follow the template's edits. See Share and duplicate.
Duplicate a template
curl -s -X POST "$SUPERHEAT_API/v1/templates/b1f4a6d2-90c7-5e33-8a2b-1d7c4e0f9a56/duplicate" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
Returns 201 with the new template. Duplicating is how you get an editable copy of a system template, since system templates cannot be modified.
| Property of the copy | Value |
|---|---|
| Owner | The active organization |
| Visibility | private |
| Name | <source name> (copy), with (copy 2), (copy 3) and so on if that name is taken |
id and hash_id | Freshly minted |
| Secret env values | Kept when your organization owned the source; blank when it did not |
| Private registry credentials | Kept when your organization owned the source; dropped when it did not |
Everything else — image, tag, launch mode, args, onstart, ports, constraints, Jupyter settings and readme — is copied as-is. Re-enter your own secrets and registry credentials on the copy before you deploy it.