OpenRelay API Documentation

This guide takes you from zero to a running GPU VM using nothing but curl.

Get your credentials

Create an API key (see Authentication) and grab your organization id. Both are visible in the dashboard, or call /v1/me:

export OPENRELAY_API_KEY="vl_your_api_key"

curl https://api.openrelay.inc/v1/me \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

{
  "user": { "id": "usr_…", "email": "you@example.com" },
  "memberships": [
    { "organizationId": "org_…", "role": "owner", "name": "Acme Inc" }
  ]
}

export ORG_ID="org_…"

Browse the catalog

See what GPUs are available and what they cost:

curl https://api.openrelay.inc/v1/gpu-availability \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

curl https://api.openrelay.inc/v1/pricing \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

Note a gpuModelId with available capacity — you'll use it next.

Launch a GPU VM

Create a VM. At minimum it needs a name; specify a gpuModelId and an imageUrl to pick hardware and the container image to run.

curl -X POST https://api.openrelay.inc/v1/orgs/$ORG_ID/vms/create \
  -H "Authorization: Bearer $OPENRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-vm",
    "gpuModelId": "rtx-4090",
    "gpuCount": 1,
    "imageUrl": "ghcr.io/my-org/my-image:latest",
    "diskSizeGb": 100,
    "envVars": { "MODEL": "llama-3" }
  }'

The response includes the new VM's id and initial status.

Poll until it's running

Provisioning takes a little while. Poll the VM until status becomes running:

curl https://api.openrelay.inc/v1/vms/$VM_ID \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

{
  "id": "vm_…",
  "name": "my-first-vm",
  "status": "running",
  "endpointUrl": "https://my-first-vm-….run.openrelay.inc",
  "pricePerHourCents": 59
}

Prefer webhooks over polling — subscribe to vm.running and get a callback the moment your VM is live.

Connect

Attach an SSH key to reach the box, or hit the endpointUrl your container exposes. To stop billing, stop or terminate the VM:

curl -X POST https://api.openrelay.inc/v1/vms/$VM_ID/terminate \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

Next steps

Run an autoscaling endpoint instead of a single box → Clusters
Automate top-ups and avoid interruptions → Billing
React to lifecycle events → Webhooks
Explore every endpoint interactively → API Reference

Quickstart