API

Base URL https://api.racksystems.cloud/v1. JSON in, JSON out. Authentication is a bearer key from the console. Every response carries a request_id header. Rate limit is 600 requests per minute per key.

Preview

During preview every endpoint answers HTTP 503 with the body {"error":"Console access is invite only during preview"}. The shapes below are final.

Authentication

curl -s https://api.racksystems.cloud/v1/capacity \
  -H "Authorization: Bearer $RACK_API_KEY"

A missing or invalid key returns 401. A key without permission for the cluster returns 403.

POST /jobs

Submit a job.

Field	Type	Required	Notes
cluster	string	yes	c1
image	string	yes	OCI image reference
command	string[]	yes	Entrypoint override
gpus	integer	yes	1 to 8
plan	string	yes	on_demand, reserved, batch
max_minutes	integer	yes	1 to 10080
env	object	no	Environment variables
retry_on_preempt	boolean	no	Batch only, default false
labels	object	no	Free form, returned unchanged

import json, os, urllib.request

def rack(method, path, body=None):
    req = urllib.request.Request(
        f"https://api.racksystems.cloud/v1{path}",
        method=method,
        data=json.dumps(body).encode() if body else None,
        headers={
            "Authorization": f"Bearer {os.environ['RACK_API_KEY']}",
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(req) as r:
        return json.load(r)

job = rack("POST", "/jobs", {
    "cluster": "c1",
    "image": "ghcr.io/yourlab/train:latest",
    "command": ["python", "train.py"],
    "gpus": 4,
    "plan": "on_demand",
    "max_minutes": 1440,
})
print(job["id"])

Returns 201 with the job object. Returns 422 with a fields object when a field is invalid.

GET /jobs/

curl -s https://api.racksystems.cloud/v1/jobs/job_01j8x2 \
  -H "Authorization: Bearer $RACK_API_KEY"

{
  "id": "job_01j8x2", "status": "running", "cluster": "c1", "plan": "on_demand",
  "gpus": ["gpu2", "gpu3", "gpu4", "gpu5"], "queue_position": null,
  "started_at": "2026-09-14T21:03:11Z", "ended_at": null,
  "metered_minutes": 128, "cost_usd": 21.25, "exit_code": null
}

Status is one of queued, running, succeeded, failed, preempted, cancelled. DELETE /jobs/{id} cancels a queued or running job.

GET /clusters/c1/telemetry

Query window from 1m to 30d. Windows up to 24 h return one sample per minute, longer windows one per 5 minutes.

curl -s "https://api.racksystems.cloud/v1/clusters/c1/telemetry?window=1h" \
  -H "Authorization: Bearer $RACK_API_KEY"

Returns { "samples": [ ... ] } with the schema on the telemetry page. Samples for GPUs held by your jobs carry a job_id.

GET /capacity

{
  "clusters": [{
    "id": "c1", "region": "us-west", "gpu": "h100-sxm-80gb",
    "free": { "on_demand": 2, "batch": 5 },
    "estimated_wait_minutes": { "on_demand": 0, "batch": 9 }
  }]
}

Add ?report=2026-08 to get a monthly capacity report instead.

Errors

Errors are { "error": "message", "request_id": "..." } with a matching HTTP status. Retry 429 and 503 with backoff. Do not retry 4xx other than 429.