UPDATED 2026.05.11READ 20 MINEDIT ON GITHUB →

CH·04API

Endpoint reference.

Every /v1 endpoint. Base URL: https://api.demo.gpu.ai/v1. Cross-cutting behaviors (auth, errors, pagination, idempotency, rate limits) live in Conventions.

§ 04.1Catalog¶

Public, no auth required. Use these to discover what GPU types are available and at what price before you provision.

GET/v1/gpu-typesSCOPE · none

List every GPU type the marketplace knows about. Paginated.

Response item shape

gpu_typestringrequired

Canonical identifier (e.g. h100_sxm).

vram_gbintegerrequired

Per-GPU VRAM in GB.

architecturestring

NVIDIA architecture (e.g. Hopper, Ada).

curl https://api.demo.gpu.ai/v1/gpu-types

200 OK

{
  "data": [
    {
      "gpu_type":     "h100_sxm",
      "vram_gb":      80,
      "architecture": "Hopper"
    },
    {
      "gpu_type":     "a100_80gb",
      "vram_gb":      80,
      "architecture": "Ampere"
    }
  ],
  "next_cursor": null
}

GET/v1/pricingSCOPE · none

Pricing per GPU type, region, and tier (on_demand or spot), with live availability counts.

curl https://api.demo.gpu.ai/v1/pricing

200 OK

{
  "data": [
    {
      "gpu_type":       "h100_sxm",
      "region":         "US",
      "tier":           "on_demand",
      "price_per_hour": 2.99,
      "available":      14
    }
  ],
  "next_cursor": null
}

§ 04.2SSH Keys¶

Manage the SSH public keys installed on instances at boot. You need at least one before launching an instance. Scope: ssh_keys: read for reads, ssh_keys: write for writes.

GET/v1/ssh-keysSCOPE · ssh_keys: read

List your registered SSH keys. Paginated.

curl https://api.demo.gpu.ai/v1/ssh-keys \
  -H "Authorization: Bearer gpuai_live_..."

200 OK

{
  "data": [
    {
      "id":          "sshkey_01HX...",
      "name":        "laptop",
      "fingerprint": "SHA256:abc123...",
      "created_at":  "2026-05-08T17:41:42Z"
    }
  ],
  "next_cursor": null
}

POST/v1/ssh-keysSCOPE · ssh_keys: write

Request body

namestringrequired

Human-readable label.

public_keystringrequired

OpenSSH-format public key (e.g. ssh-ed25519 AAAAC3Nz...). Server validates format and rejects malformed keys.

curl -X POST https://api.demo.gpu.ai/v1/ssh-keys \
  -H "Authorization: Bearer gpuai_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "laptop",
    "public_key": "ssh-ed25519 AAAAC3Nz... me@laptop"
  }'

201 CREATED

{
  "id":          "sshkey_01HX...",
  "name":        "laptop",
  "fingerprint": "SHA256:abc123...",
  "created_at":  "2026-05-08T17:41:42Z"
}

DELETE/v1/ssh-keys/{id}SCOPE · ssh_keys: write

Delete an SSH key. Idempotent — deleting an already-gone key returns 404 not_found, not an error.

curl -X DELETE https://api.demo.gpu.ai/v1/ssh-keys/sshkey_01HX... \
  -H "Authorization: Bearer gpuai_live_..."

§ 04.3Instances¶

Provision and manage GPU instances. Scope: instances: read / write.

GET/v1/instancesSCOPE · instances: read

List your instances. Paginated.

curl "https://api.demo.gpu.ai/v1/instances?limit=25" \
  -H "Authorization: Bearer gpuai_live_..."

200 OK

{
  "data": [
    {
      "id":             "ins_01HX...",
      "name":           "training-run-42",
      "status":         "running",
      "gpu_type":       "h100_sxm",
      "gpu_count":      1,
      "region":         "US",
      "tier":           "on_demand",
      "price_per_hour": 2.99,
      "connection": {
        "hostname":    "ssh.gpu.ai",
        "port":        10042,
        "ssh_command": "ssh -p 10042 user@ssh.gpu.ai"
      },
      "created_at":  "2026-05-08T17:00:00Z",
      "ready_at":    "2026-05-08T17:01:30Z"
    }
  ],
  "next_cursor": null
}

POST/v1/instancesSCOPE · instances: write

Create an instance. Returns 202 with Operation-Id. Requires Idempotency-Key.

Request body

gpu_typestringrequired

From /v1/gpu-types.

gpu_countintegerrequired

1–8.

tierstringrequired

on_demand or spot.

ssh_key_idsstring[]

SSH key IDs to install. At least one required for SSH access.

regionstring

Preferred region; best-effort.

namestring

Friendly label for the dashboard.

max_price_per_hournumber

Reject placement above this price.

curl -X POST https://api.demo.gpu.ai/v1/instances \
  -H "Authorization: Bearer gpuai_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "gpu_type": "h100_sxm",
    "gpu_count": 1,
    "tier": "on_demand",
    "ssh_key_ids": ["sshkey_01HX..."],
    "name": "training-run-42"
  }'

# 202 Accepted
# Operation-Id: 5f1b8a9c-0d1e-2f3a-4b5c-6d7e8f9a0b1c

202 ACCEPTED

// Operation-Id: 5f1b8a9c-0d1e-2f3a-4b5c-6d7e8f9a0b1c
{
  "operation_id": "5f1b8a9c-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
  "kind":         "instance.create",
  "state":        "pending",
  "resource_id":  null,
  "created_at":   "2026-05-08T17:00:00Z",
  "updated_at":   "2026-05-08T17:00:00Z",
  "completed_at": null
}

GET/v1/instances/{id}SCOPE · instances: read

Fetch a single instance by ID.

curl https://api.demo.gpu.ai/v1/instances/ins_01HX... \
  -H "Authorization: Bearer gpuai_live_..."

PATCH/v1/instances/{id}SCOPE · instances: write

Update an instance. In v1 the only mutable field is name.

curl -X PATCH https://api.demo.gpu.ai/v1/instances/ins_01HX... \
  -H "Authorization: Bearer gpuai_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "training-run-43"}'

DELETE/v1/instances/{id}SCOPE · instances: write

Terminate an instance. Async, returns 202 with an Operation-Id. Idempotent — deleting an already-terminated instance returns 404 not_found.

curl -X DELETE https://api.demo.gpu.ai/v1/instances/ins_01HX... \
  -H "Authorization: Bearer gpuai_live_..." \
  -H "Idempotency-Key: $(uuidgen)"

# 202 Accepted
# Operation-Id: 5f1b... (poll until terminated)

§ 04.4Operations¶

Async writes (instance create/delete) return an Operation pointer that you poll until terminal. Scope: instances: read.

State	Meaning
`pending`	Accepted, not yet started. Initial state.
`in_progress`	Worker is actively executing. `resource_id` may now be populated.
`succeeded`	Terminal. The resource is in its target state.
`failed`	Terminal. See `error` for detail.
`cancelled`	Terminal. Caller aborted (rare in v1).

GET/v1/operations/{id}SCOPE · instances: read

Fetch an operation by its UUID. Operations are scoped to the API key that created them — cross-key access returns 404 not_found.

Suggested polling: backoff 1s → 2s → 4s → 8s → 16s → 30s. Operations typically complete in 30–90s for instance creates.

curl https://api.demo.gpu.ai/v1/operations/5f1b8a9c-... \
  -H "Authorization: Bearer gpuai_live_..."

200 OK · in progress

{
  "operation_id": "5f1b8a9c-...",
  "kind":         "instance.create",
  "state":        "in_progress",
  "resource_id":  "ins_01HX...",
  "created_at":   "2026-05-08T17:00:00Z",
  "updated_at":   "2026-05-08T17:00:35Z",
  "completed_at": null
}

200 OK · succeeded

{
  "operation_id": "5f1b8a9c-...",
  "state":        "succeeded",
  "resource_id":  "ins_01HX...",
  "completed_at": "2026-05-08T17:01:30Z",
  ...
}

200 OK · failed

{
  "operation_id": "5f1b8a9c-...",
  "state":        "failed",
  "error": {
    "code":   "operation_failed",
    "detail": "All suppliers rejected the placement"
  },
  ...
}

§ 04.5Usage¶

Time-bucketed GPU usage and cost. Scope: billing: read. Defaults to a 30-day window when start/end are omitted.

GET/v1/usageSCOPE · billing: read

Query parameters

bucketstring

One of hour, day, week, month. Default depends on window length.

group_bystring

instance_id or gpu_type.

startISO 8601

Inclusive lower bound.

endISO 8601

Exclusive upper bound.

cursor / limitstandard

See pagination conventions.

curl "https://api.demo.gpu.ai/v1/usage?bucket=day&group_by=gpu_type" \
  -H "Authorization: Bearer gpuai_live_..."

200 OK

{
  "data": [
    {
      "bucket_start": "2026-05-07T00:00:00Z",
      "gpu_type":     "h100_sxm",
      "gpu_seconds":  86400,
      "cost_cents":   7176
    },
    {
      "bucket_start": "2026-05-08T00:00:00Z",
      "gpu_type":     "h100_sxm",
      "gpu_seconds":  43200,
      "cost_cents":   3588
    }
  ],
  "next_cursor": null
}