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,
      "reservation_id":  null,
      "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
}

reservation_id is null for on_demand and spot instances; for reserved instances it carries the parent contract’s ID — same value as the reservation_id in GET /v1/reservations.

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, spot, or reserved. reserved requires your org to hold an active reservation contract for the requested GPU type and region — see Reservations below. Contact sales to set one up.

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
}

Reserved-tier error codes

reservation/no_contract403

Your org does not hold a reservation contract. Use tier: "on_demand" or contact sales.

reservation/contract_inactive403

A contract exists but is not currently active (pending, suspended, expired, or outside its term window).

reservation/gpu_type_mismatch400

Your contract does not cover the requested gpu_type (or no slot in the requested region matches it).

reservation/no_capacity429

All slots are currently allocated. Retry once a slot returns to the pool, or use tier: "on_demand" for the overage. There is no automatic fallback in v1.

ssh_keys/org_mismatch403

One of the supplied ssh_key_ids belongs to a different org than the caller. Applies to every tier, not just reserved.

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.4Reservations¶

Surfaces the reserved-capacity contracts your org holds, along with live utilization and the instances currently running under each. Reservations are ops-onboarded — there is no self-serve checkout in v1; sales closes the contract and ops provisions the entitlement. Once a contract exists, provisioning against it uses the standard POST /v1/instances endpoint with tier: "reserved". Scope: instances: read.

GET/v1/reservationsSCOPE · instances: read

List your org’s reservation contracts. Returns an array of contract objects with term, status, utilization, the commitment lines, and the active instances pinned to each. Commercial terms (monthly fee, payment schedule, upstream provider) are intentionally omitted — you already have those from the signed contract.

Response item shape

reservation_idstringrequired

ULID identifying the contract. Matches the reservation_id on instance responses.

titlestringrequired

Human-readable label set by ops.

starts_atISO 8601required

Contract term start (UTC).

ends_atISO 8601required

Contract term end (UTC, exclusive).

statusstringrequired

One of pending, active, suspended, expired, cancelled. Only active accepts new tier: "reserved" provisioning.

renewal.modestringrequired

auto_renew, manual, or none.

renewal.days_until_endintegerrequired

Days remaining until ends_at.

renewal.expiring_soonbooleanrequired

true when days_until_end ≤ 14.

commitment[]arrayrequired

One entry per capacity line: gpu_type, gpu_count, region.

utilization.allocated_gpusintegerrequired

Currently-allocated GPUs across all this contract’s slots.

utilization.committed_gpusintegerrequired

Total GPUs committed across all this contract’s slots.

utilization.pctnumberrequired

allocated_gpus / committed_gpus (0.0–1.0).

instances[]arrayrequired

Non-terminated instances under this contract: instance_id, hostname, gpu_count, status.

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

200 OK

[
  {
    "reservation_id": "01HX9ZS6AB1234CONTRACT0001",
    "title":          "ACME Q3 H100",
    "starts_at":      "2026-07-01T00:00:00Z",
    "ends_at":        "2026-10-01T00:00:00Z",
    "status":         "active",
    "renewal": {
      "mode":            "manual",
      "days_until_end":  47,
      "expiring_soon":   false
    },
    "commitment": [
      { "gpu_type": "h100_sxm", "gpu_count": 8, "region": "us-west-2" }
    ],
    "utilization": {
      "allocated_gpus": 5,
      "committed_gpus": 8,
      "pct":            0.625
    },
    "instances": [
      {
        "instance_id": "ins_01HX...",
        "hostname":    "gpu-4a7f.gpu.ai",
        "gpu_count":   4,
        "status":      "running"
      },
      {
        "instance_id": "ins_01HY...",
        "hostname":    "gpu-c1d2.gpu.ai",
        "gpu_count":   1,
        "status":      "booting"
      }
    ]
  }
]

200 OK · empty

[]

§ 04.5Operations¶

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.6Usage¶

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
}