API overview

Everything the console does, it does by calling this API. You can browse offers, deploy an instance, watch its logs, stop it and destroy it from a script, with the same organization and the same balance behind it.

Base URL

All endpoints live under the /v1 prefix on the Superheat API host. Requests and responses are JSON. Set two variables so the examples in this section run as written:

export SUPERHEAT_API="https://<your-superheat-api-host>"
export SUPERHEAT_KEY="shk_your_key_here"

Every path below is written relative to that host — /v1/offers means $SUPERHEAT_API/v1/offers.

What the API covers

Area	Endpoints	Documented in
Health	`GET /v1/health`	This page
Catalog	`GET /v1/offers`, `GET /v1/offers/{id}`, `GET /v1/catalog/status`	Offers
Templates	`GET /v1/templates`, `GET /v1/templates/{id}`, `GET /v1/templates/by-hash/{hash_id}`, `POST /v1/templates/{id}/duplicate`	Templates
Instances	`POST /v1/instances`, `GET /v1/instances`, `GET /v1/instances/{id}`, `POST /v1/instances/{id}/stop`, `POST /v1/instances/{id}/start`, `DELETE /v1/instances/{id}`, `GET /v1/instances/{id}/logs`	Instances
Keys	`GET /v1/api-keys`, `POST /v1/api-keys`, `DELETE /v1/api-keys/{id}`	API keys

What the API does not do

Not available	Do this instead
Adding credits with an API key	Checkout is admin-only and rejects API keys. Top up in the console under Billing.
Account endpoints with an API key	`/v1/me` and `/v1/ssh-keys` require a signed-in session. Add SSH keys in the console before you automate deploys.
Streaming logs	Poll `GET /v1/instances/{id}/logs?tail=N`. The console polls it every three seconds.
Choosing a machine, a host or a placement	You rent an offer. Superheat decides where it runs.
Setting your own price	Prices are set by Superheat and snapshotted onto the instance when you rent.

Money fields

Fields whose names end in _microusd are integers counting millionths of a dollar. Divide by 1,000,000 for dollars: 2290000 is $2.29 per hour, and a spend_microusd of 410000 is $0.41 spent so far.

Your first request

GET /v1/health needs no credentials, so it is the fastest way to confirm you can reach the API:

curl -s -i "$SUPERHEAT_API/v1/health"

{
  "status": "ok",
  "version": "0.1.0",
  "commit": "9f2c1ab",
  "app_env": "production",
  "provisioner": "dispatch",
  "inventory_sync_enabled": true,
  "database": true
}

Field	Type	Meaning
`status`	string	`ok`, or `degraded` when a check failed
`version`	string	API version
`commit`	string or null	Git commit the deployed API was built from, `null` outside a deployed build
`app_env`	string	Which environment answered, for example `production`
`provisioner`	string	`dispatch` for real hardware, `simulated` for a fake fleet
`inventory_sync_enabled`	boolean	Whether the catalog is being refreshed from live inventory
`database`	boolean	Whether a real query round-tripped to the database just now

The handler runs a SELECT 1 against the database with a 3-second ceiling rather than returning a fixed literal. If that fails it answers 503 with the same body shape, status of degraded and database of false — so check the HTTP status, not just the presence of a body. The three environment fields are there so that an API quietly serving a simulated fleet is visible from outside; provisioner of simulated means the instances you deploy are not real machines.

Everything else needs a bearer token. Create an API key first (API keys), then list the three cheapest offers:

curl -s "$SUPERHEAT_API/v1/offers?sort=price_asc" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

{
  "items": [
    {
      "id": "5d2f9c31-8b64-4c0e-9a77-2e0f1b6a4c11",
      "gpu_model": "H100 SXM",
      "num_gpus": 1,
      "vram_gb": 80,
      "tflops": 198.0,
      "cuda_version": "12.8",
      "vm_capable": false,
      "disk_quota_capable": false,
      "price_per_hour_microusd": 2290000,
      "storage_price_per_gb_hour_microusd": 250,
      "max_duration_hours": null,
      "status": "available",
      "available_units": 3,
      "capacity_units": 8,
      "machine": {
        "hostname": "sh-us-tx-01",
        "region": "US-TX",
        "country_code": "US",
        "cpu_model": "Intel Xeon Platinum 8480+",
        "cpu_cores": 112,
        "ram_gb": 2048,
        "disk_type": "nvme",
        "disk_gb": 15000,
        "net_up_mbps": 8000,
        "net_down_mbps": 8000,
        "pcie_gen": 5,
        "pcie_width": 16,
        "reliability": 0.998,
        "verified": true,
        "next_maintenance": null
      }
    }
  ]
}

From there, Instances walks the full deploy-and-connect path.

Organization scope

Every object belongs to an organization, never to a user directly. A request without an X-Org-Id header runs against your personal organization; an API key always runs against the organization it was created in. See Authentication.

Base URL​

What the API covers​

What the API does not do​

Money fields​

Your first request​

Organization scope​