API Reference

The Substrate REST API lets you manage GPU compute instances programmatically. All endpoints return JSON and use standard HTTP status codes.

Base URL

https://api.onsubstrate.run/v1

Authentication

All requests must include an Authorization header with a Bearer token. You can generate API keys from the Substrate dashboard.

Authorization: Bearer sk_live_...

Endpoints

GET/v1/instances

List all instances in your account. Returns an array of instance objects sorted by creation date (newest first).

Response

{
  "instances": [
    {
      "id": "inst_abc123",
      "name": "training-node-1",
      "status": "running",
      "gpu_cores": 4,
      "vram_gb": 24,
      "ram_gb": 64,
      "storage_gb": 100,
      "region": "us-east-1",
      "endpoint": "inst_abc123.compute.onsubstrate.run",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Status codes

200Success
401Unauthorized — invalid or missing API key

POST/v1/instances

Create a new GPU compute instance. Substrate composes hardware to match the exact resource configuration you specify.

Request body

{
  "gpu_cores": 4,
  "vram_gb": 24,
  "ram_gb": 64,
  "storage_gb": 100,
  "region": "us-east-1",
  "name": "training-node-1"
}

region and name are optional. Region defaults to us-east-1.

Response

{
  "id": "inst_abc123",
  "name": "training-node-1",
  "status": "provisioning",
  "gpu_cores": 4,
  "vram_gb": 24,
  "ram_gb": 64,
  "storage_gb": 100,
  "region": "us-east-1",
  "endpoint": "inst_abc123.compute.onsubstrate.run",
  "created_at": "2025-01-15T10:30:00Z"
}

Status codes

201Instance created
400Invalid parameters
401Unauthorized
422Insufficient resources available

GET/v1/instances/:id

Get detailed information about a specific instance, including live resource utilization metrics.

Response

{
  "id": "inst_abc123",
  "name": "training-node-1",
  "status": "running",
  "gpu_cores": 4,
  "vram_gb": 24,
  "ram_gb": 64,
  "storage_gb": 100,
  "region": "us-east-1",
  "endpoint": "inst_abc123.compute.onsubstrate.run",
  "created_at": "2025-01-15T10:30:00Z",
  "metrics": {
    "cpu_utilization": 0.45,
    "gpu_utilization": 0.92,
    "memory_used_gb": 48.2,
    "uptime_seconds": 86400
  }
}

Status codes

200Success
401Unauthorized
404Instance not found

PATCH/v1/instances/:id

Update an instance. You can modify the instance name or resize resources. Resource changes may require a brief restart.

Request body

{
  "name": "training-node-updated",
  "gpu_cores": 8,
  "vram_gb": 48
}

All fields are optional. Only include fields you want to change.

Response

{
  "id": "inst_abc123",
  "name": "training-node-updated",
  "status": "running",
  "gpu_cores": 8,
  "vram_gb": 48,
  "ram_gb": 64,
  "storage_gb": 100,
  "region": "us-east-1",
  "endpoint": "inst_abc123.compute.onsubstrate.run",
  "created_at": "2025-01-15T10:30:00Z"
}

Status codes

200Instance updated
400Invalid parameters
401Unauthorized
404Instance not found
422Insufficient resources for resize

DELETE/v1/instances/:id

Permanently delete an instance and all associated storage. This action is irreversible.

Response

{
  "deleted": true
}

Status codes

200Instance deleted
401Unauthorized
404Instance not found

GET/v1/instances/:id/metrics

Get real-time resource utilization metrics for a running instance. Metrics are updated every 10 seconds.

Response

{
  "cpu_utilization": 0.45,
  "gpu_utilization": 0.92,
  "memory_used_gb": 48.2,
  "uptime_seconds": 86400
}

Status codes

200Success
401Unauthorized
404Instance not found
409Instance is not running