API Reference

Complete guide to using the Spheron AI API for programmatic access to GPU instances.

Quick Start

1. Get Your API Key

Generate an API key from your Spheron dashboard.

2. Make Your First API Call

Test your connection by listing available providers:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.spheron.ai/api/providers

3. List Available GPUs

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.spheron.ai/api/gpu-offers?limit=5"

4. Deploy Your First Instance

curl -X POST "https://app.spheron.ai/api/deployments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "tensordock",
    "offerId": "rtx-4090-tensordock-1",
    "gpuType": "rtx-4090",
    "gpuCount": 1,
    "region": "us-east-1",
    "operatingSystem": "ubuntu-22.04",
    "instanceType": "DEDICATED",
    "sshKeyId": "your_ssh_key_id"
  }'

Base URL

https://app.spheron.ai

Authentication

Include your API key in the Authorization header for all authenticated requests:

Authorization: Bearer YOUR_API_KEY

Security Note: Treat API keys like passwords. Never expose them in client-side code or public repositories. See Security Best Practices for more information.

Endpoints

Get Providers

Get list of all available GPU providers (public endpoint).

Method: GET Path: /api/providers

Response Example:

[
  "tensordock",
  "voltagepark",
  "datacrunch",
  "sesterce"
]

Get GPU Offers

Get available GPU offers with filtering and pagination. Optional auth to show discounts.

Method: GET Path: /api/gpu-offers

Headers:

Authorization: Bearer YOUR_API_KEY (optional)

Parameters:

Name	Type	Required	Description
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 10)
`search`	string	No	Search term for GPU models
`sortBy`	string	No	Sort field (default: popularity)
`sortOrder`	string	No	asc or desc (default: asc)
`instanceType`	string	No	Filter by type: 'SPOT', 'DEDICATED', or 'BARE_METAL' (case-insensitive)

Response Example:

{
  "data": [
    {
      "gpuType": "rtx-4090",
      "gpuModel": "RTX 4090",
      "baseGpuType": "rtx-4090",
      "interconnectVariants": ["PCIe"],
      "hasMultipleVariants": false,
      "displayName": "RTX 4090",
      "popularity": 85,
      "totalAvailable": 12,
      "lowestPrice": 0.45,
      "highestPrice": 0.65,
      "averagePrice": 0.55,
      "providers": ["tensordock", "voltagepark"],
      "offers": [
        {
          "provider": "tensordock",
          "offerId": "rtx-4090-tensordock-1-dedicated",
          "name": "RTX 4090",
          "description": "High-performance gaming and AI GPU",
          "vcpus": 8,
          "memory": 32,
          "storage": 100,
          "gpuCount": 1,
          "price": 0.50,
          "available": true,
          "clusters": ["us-east-1", "us-west-2"],
          "region": "us-east-1",
          "gpu_memory": 24,
          "os_options": ["ubuntu-20.04", "ubuntu-22.04"],
          "maintenance": false,
          "interconnectType": "PCIe",
          "interconnectDescription": "PCIe interface",
          "instanceType": "DEDICATED",
          "supportsCloudInit": true,
          "extras": {
            "deployment_type": "vm",
            "networking_type": "standard"
          }
        },
        {
          "provider": "datacrunch",
          "offerId": "rtx-4090-datacrunch-1-spot",
          "name": "RTX 4090 SPOT",
          "description": "Cost-effective SPOT instance (lower price, may be interrupted)",
          "vcpus": 8,
          "memory": 32,
          "storage": 100,
          "gpuCount": 1,
          "price": 0.25,
          "spot_price": 0.25,
          "available": true,
          "clusters": ["us-east-1", "eu-west-1"],
          "region": "us-east-1",
          "gpu_memory": 24,
          "os_options": ["ubuntu-20.04", "ubuntu-22.04"],
          "maintenance": false,
          "interconnectType": "PCIe",
          "interconnectDescription": "PCIe interface",
          "instanceType": "SPOT",
          "supportsCloudInit": true,
          "extras": {
            "deployment_type": "vm",
            "networking_type": "standard"
          },
          "note": "For SPOT instances: price = spot_price (discounted rate with possible interruption)"
        },
        {
          "provider": "voltage-park",
          "offerId": "baremetal_h100_8_ethernet",
          "name": "H100 8x GPU Bare Metal (Ethernet)",
          "description": "8x H100 GPUs, 832 vCPUs, 8192GB RAM, 144000GB Storage. Bare Metal with 100 Gbps Ethernet networking.",
          "vcpus": 832,
          "memory": 8192,
          "storage": 144000,
          "gpuCount": 8,
          "price": 15.84,
          "available": true,
          "clusters": ["dalas-united states"],
          "region": "dalas-united states",
          "gpu_memory": 80,
          "os_options": ["Ubuntu 20.04 LTS", "Ubuntu 22.04 LTS"],
          "maintenance": false,
          "interconnectType": "NVLink",
          "interconnectDescription": "NVLink high-speed GPU interconnect",
          "instanceType": "BARE_METAL",
          "supportsCloudInit": true,
          "extras": {
            "deployment_type": "cluster",
            "networking_type": "ethernet",
            "kubernetes_addon": {
              "available": true,
              "total_cost_per_hour": 0.384
            }
          },
          "note": "Bare-metal offers may include kubernetes_addon in extras showing addon availability and cost per hour (with commission included)"
        }
      ]
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 10,
  "totalPages": 5
}

Deployments

Create Deployment

Create a new GPU instance deployment. Optionally add Kubernetes cluster for Voltage Park bare-metal instances.

Method: POST Path: /api/deployments

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Parameters:

Name	Type	Required	Description
`provider`	string	Yes	Provider name (e.g., tensordock, voltagepark, datacrunch, sesterce)
`offerId`	string	Yes	Unique offer ID from the GPU offers endpoint
`gpuType`	string	Yes	GPU type identifier (e.g., rtx-4090, h100)
`gpuCount`	number	Yes	Number of GPUs to deploy
`region`	string	Yes	Deployment region/cluster
`operatingSystem`	string	Yes	Operating system (e.g., ubuntu-20.04, ubuntu-22.04)
`instanceType`	string	Yes	Instance type: 'SPOT', 'DEDICATED', or 'BARE_METAL' (case-insensitive)
`sshKeyId`	string	No	SSH key ID from your saved keys (either this or ssh_public_key required)
`ssh_public_key`	string	No	Inline SSH public key content (either this or sshKeyId required). A temporary key will be created.
`teamId`	string	No	Team ID for team deployments (optional)
`name`	string	No	Optional name for the deployment
`cloudInit`	object	No	Cloud-Init configuration object. Supports fields: runcmd (string[]), packages (string[]), writeFiles (array of objects with path, content, owner, permissions).
`kubernetesAddon`	object	No	Kubernetes add-on configuration (Voltage Park bare-metal only). Object with 'version' (string, e.g., '1.35') and optional 'authentication_config_b64' (base64-encoded Kubernetes AuthenticationConfiguration YAML). Additional hourly cost applies per GPU.

Request Body Example:

{
  "provider": "tensordock",
  "offerId": "rtx-4090-tensordock-1",
  "gpuType": "rtx-4090",
  "gpuCount": 1,
  "region": "us-east-1",
  "operatingSystem": "ubuntu-20.04",
  "instanceType": "DEDICATED",
  "sshKeyId": "ssh_key_id_here",
  "teamId": "team_id_optional",
  "name": "My GPU Instance",
  "note": "Alternatively, use 'ssh_public_key' instead of 'sshKeyId' to create a temporary SSH key",
  "cloudInit": {
    "runcmd": [
      "echo 'Hello from cloud-init'",
      "apt-get update"
    ],
    "packages": ["curl", "git"],
    "writeFiles": [
      {
        "path": "/etc/motd",
        "content": "Welcome to your instance!",
        "owner": "root:root",
        "permissions": "0644"
      }
    ]
  },
  "kubernetesAddon": {
    "version": "1.35",
    "authentication_config_b64": "YXBpVmVyc2lvbjogYXBpc2VydmVyLmNvbmZpZy5rOHMuaW8vdjFiZXRhMQpraW5kOiBBdXRoZW50aWNhdGlvbkNvbmZpZ3VyYXRpb24Kand0OiBbXQ==",
    "note": "Optional - only for Voltage Park BARE_METAL/CLUSTER instances. authentication_config_b64 is optional. Additional hourly cost applies."
  }
}

Response Example:

{
  "id": "deployment_id",
  "name": "My GPU Instance",
  "userId": "user_id",
  "teamId": "team_id",
  "gpuModelId": "rtx-4090-rtx-4090-tensordock-1",
  "providerId": "tensordock",
  "gpuCount": 1,
  "region": "us-east-1",
  "operatingSystem": "ubuntu-20.04",
  "instanceType": "DEDICATED",
  "sshKeyId": "ssh_key_id_here",
  "tempSshKeyId": null,
  "sshKeyName": "My SSH Key",
  "sshKeyFingerprint": "SHA256:abc123...",
  "ipAddress": null,
  "user": null,
  "status": "deploying",
  "startedAt": null,
  "stoppedAt": null,
  "lastCreditDeduction": null,
  "totalCost": 0,
  "hourlyRate": 0.50,
  "originalHourlyRate": 0.50,
  "discountPercentage": 0,
  "hasDiscount": false,
  "vcpus": 8,
  "memory": 32,
  "storage": 100,
  "sshCommand": null,
  "sshPort": null,
  "portForwards": [],
  "kubernetesAddon": {
    "version": "1.35",
    "kubeconfig": "apiVersion: v1\nclusters:...",
    "k8s_cluster_id": "550e8400-e29b-41d4-a716-446655440000",
    "service_links": ["https://grafana-cluster-id.voltagepark.com"],
    "restore": false,
    "note": "kubeconfig, k8s_cluster_id, and service_links populate once cluster is running. Only present when kubernetesAddon is requested."
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Deployments

Get list of your deployments with optional filtering.

Method: GET Path: /api/deployments

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`userId`	string	No	Filter by user ID (must be your own)
`teamId`	string	No	Filter by team ID
`status`	string	No	Filter by status: 'active' (running/deploying), 'inactive' (terminated/failed), or specific status ('running', 'deploying', 'terminated', 'failed')

Response Example:

[
  {
    "id": "deployment_id",
    "name": "My GPU Instance",
    "userId": "user_id",
    "teamId": "team_id",
    "gpuModelId": "rtx-4090-tensordock-1",
    "providerId": "tensordock",
    "gpuCount": 1,
    "region": "us-east-1",
    "operatingSystem": "ubuntu-20.04",
    "instanceType": "DEDICATED",
    "sshKeyId": "ssh_key_id_here",
    "tempSshKeyId": null,
    "sshKeyName": "My SSH Key",
    "sshKeyFingerprint": "SHA256:abc123...",
    "ipAddress": "192.168.1.100",
    "user": "ubuntu",
    "status": "running",
    "startedAt": "2024-01-15T10:30:00Z",
    "stoppedAt": null,
    "lastCreditDeduction": "2024-01-15T11:30:00Z",
    "totalCost": 12.50,
    "hourlyRate": 0.50,
    "hasDiscount": false,
    "discountPercentage": 0,
    "originalHourlyRate": 0.50,
    "vcpus": 8,
    "memory": 32,
    "storage": 100,
    "sshCommand": "ssh ubuntu@192.168.1.100",
    "sshPort": 22,
    "portForwards": [],
    "kubernetesAddon": {
      "version": "1.35",
      "kubeconfig": "apiVersion: v1\nclusters:...",
      "k8s_cluster_id": "550e8400-e29b-41d4-a716-446655440000",
      "service_links": ["https://grafana-cluster-id.voltagepark.com"],
      "restore": false,
      "note": "Only present for deployments with Kubernetes addon"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

Get Deployment Details

Get details of a specific deployment by ID.

Method: GET Path: /api/deployments/{deploymentId}

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`deploymentId`	string	Yes	Deployment ID

Response Example:

{
  "id": "deployment_id",
  "name": "My GPU Instance",
  "userId": "user_id",
  "teamId": "team_id",
  "gpuModelId": "rtx-4090-tensordock-1",
  "providerId": "tensordock",
  "gpuCount": 1,
  "region": "us-east-1",
  "operatingSystem": "ubuntu-20.04",
  "instanceType": "DEDICATED",
  "sshKeyId": "ssh_key_id_here",
  "tempSshKeyId": null,
  "sshKeyName": "My SSH Key",
  "sshKeyFingerprint": "SHA256:abc123...",
  "ipAddress": "192.168.1.100",
  "user": "ubuntu",
  "status": "running",
  "startedAt": "2024-01-15T10:30:00Z",
  "stoppedAt": null,
  "lastCreditDeduction": "2024-01-15T11:30:00Z",
  "totalCost": 12.50,
  "hourlyRate": 0.50,
  "hasDiscount": false,
  "discountPercentage": 0,
  "originalHourlyRate": 0.50,
  "vcpus": 8,
  "memory": 32,
  "storage": 100,
  "sshCommand": "ssh ubuntu@192.168.1.100",
  "sshPort": 22,
  "portForwards": [],
  "kubernetesAddon": {
    "version": "1.35",
    "kubeconfig": "apiVersion: v1\nclusters:...",
    "k8s_cluster_id": "550e8400-e29b-41d4-a716-446655440000",
    "service_links": ["https://grafana-cluster-id.voltagepark.com"],
    "restore": false,
    "note": "Only present for deployments with Kubernetes addon"
  },
  "extras": {},
  "createdAt": "2024-01-15T10:30:00Z"
}

Terminate Deployment

Terminate a deployment and its associated cloud instance.

Method: DELETE Path: /api/deployments/{deploymentId}

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`deploymentId`	string	Yes	Deployment ID to terminate

Response Example:

{
  "message": "Instance destruction initiated",
  "deployment": {
    "id": "deployment_id",
    "status": "terminated",
    "stoppedAt": "2024-01-15T12:30:00Z"
  }
}

Kubernetes

Get Kubernetes Versions

Get available Kubernetes versions for Voltage Park bare-metal deployments.

Method: GET Path: /api/kubernetes/versions

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`provider`	string	Yes	Provider name (currently only 'voltage-park' is supported)

Response Example:

{
  "versions": [
    { "version": "1.35", "available": true },
    { "version": "1.34", "available": true },
    { "version": "1.33", "available": true },
    { "version": "1.32", "available": true }
  ]
}

Get Kubernetes Cluster Health

Get health status of a Kubernetes cluster by cluster ID.

Method: GET Path: /api/kubernetes/{clusterId}/health

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`clusterId`	string	Yes	Kubernetes cluster ID (UUID)

Response Example:

{
  "health": {
    "controlPlaneNodes": { "healthy": 3, "total": 3, "status": "healthy" },
    "workerNodes": { "healthy": 8, "total": 8, "status": "healthy" },
    "networkComponents": { "healthy": 2, "total": 2, "status": "healthy" },
    "overallHealth": "healthy"
  }
}

SSH Keys

Get SSH Keys

Get list of your SSH keys.

Method: GET Path: /api/ssh-keys

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`userId`	string	No	Filter by user ID (must be your own)
`teamId`	string	No	Filter by team ID

Response Example:

[
  {
    "id": "ssh_key_id",
    "userId": "user_id",
    "teamId": "team_id",
    "name": "My SSH Key",
    "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...",
    "fingerprint": "sha256:abc123def456...",
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

Add SSH Key

Add a new SSH key.

Method: POST Path: /api/ssh-keys

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body:

{
  "name": "My SSH Key",
  "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... user@hostname",
  "teamId": "team_id_optional"
}

Response Example:

{
  "id": "ssh_key_id",
  "userId": "user_id",
  "teamId": "team_id",
  "name": "My SSH Key",
  "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...",
  "fingerprint": "sha256:abc123def456...",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get SSH Key Details

Get a specific SSH key by ID.

Method: GET Path: /api/ssh-keys/{id}

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`id`	string	Yes	SSH key ID

Response Example:

{
  "id": "ssh_key_id",
  "userId": "user_id",
  "teamId": "team_id",
  "name": "My SSH Key",
  "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...",
  "fingerprint": "sha256:abc123def456...",
  "createdAt": "2024-01-15T10:30:00Z"
}

Delete SSH Key

Delete an SSH key.

Method: DELETE Path: /api/ssh-keys/{id}

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`id`	string	Yes	SSH key ID to delete

Response Example:

{
  "success": true
}

Volumes

List Volumes

List all persistent storage volumes for a team with pagination and status filtering.

Method: GET Path: /api/volumes

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`teamId`	string	No	Filter by team ID (defaults to current team)
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 20)
`status`	string	No	Filter by status: 'available', 'attached', 'deleting', or 'deleted'

Response Example:

{
  "data": [{
    "id": "volume_internal_id",
    "volumeId": "vol_abc123",
    "name": "my-data-volume",
    "userId": "user_id",
    "teamId": "team_id",
    "providerId": "voltage-park",
    "sizeInGb": 100,
    "usedCapacityBytes": 52428800000,
    "virtualIp": "192.168.100.50",
    "attachedToDeploymentIds": ["deployment_id_1"],
    "attachedToOrderIds": ["order_123"],
    "status": "attached",
    "hourlyRate": 0.0137,
    "lastPriceUpdate": "2026-02-07T10:30:00Z",
    "deleteWithInstance": false,
    "createdAt": "2026-02-07T10:00:00Z",
    "lastAttachedAt": "2026-02-07T10:15:00Z"
  }],
  "total": 5,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

Create Volume

Create a new persistent storage volume. Optionally attach to an existing deployment during creation.

Method: POST Path: /api/volumes

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Parameters:

Name	Type	Required	Description
`name`	string	Yes	Volume name (lowercase alphanumeric with hyphens/underscores, max 60 chars)
`sizeInGb`	number	Yes	Volume size in GB (1-10000)
`provider`	string	Yes	Provider name (e.g., 'voltage-park')
`teamId`	string	No	Team ID (defaults to current team)
`deploymentId`	string	No	Optional deployment ID to attach during creation
`deleteWithInstance`	boolean	No	Delete volume when instance terminates (default: false). Note: Voltage Park volumes include a 'virtualIp' field needed for mounting.

Request Body Example:

{
  "name": "my-data-volume",
  "sizeInGb": 100,
  "provider": "voltage-park",
  "teamId": "team_id_optional",
  "deploymentId": "deployment_id_optional",
  "deleteWithInstance": false
}

Response Example:

{
  "id": "volume_internal_id",
  "volumeId": "vol_abc123",
  "name": "my-data-volume",
  "userId": "user_id",
  "teamId": "team_id",
  "providerId": "voltage-park",
  "sizeInGb": 100,
  "usedCapacityBytes": 0,
  "virtualIp": "192.168.100.50",
  "attachedToDeploymentIds": [],
  "attachedToOrderIds": [],
  "status": "available",
  "hourlyRate": 0.0137,
  "lastPriceUpdate": "2026-02-07T10:00:00Z",
  "deleteWithInstance": false,
  "createdAt": "2026-02-07T10:00:00Z"
}

Get Volume Details

Get volume details with fresh usage data from provider.

Method: GET Path: /api/volumes/{volumeId}

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`volumeId`	string	Yes	Volume ID to retrieve

Response Example:

{
  "id": "volume_internal_id",
  "volumeId": "vol_abc123",
  "name": "my-data-volume",
  "userId": "user_id",
  "teamId": "team_id",
  "providerId": "voltage-park",
  "sizeInGb": 100,
  "usedCapacityBytes": 52428800000,
  "virtualIp": "192.168.100.50",
  "attachedToDeploymentIds": ["deployment_id_1"],
  "attachedToOrderIds": ["order_123"],
  "status": "attached",
  "hourlyRate": 0.0137,
  "lastPriceUpdate": "2026-02-07T10:00:00Z",
  "deleteWithInstance": false,
  "createdAt": "2026-02-07T10:00:00Z",
  "lastAttachedAt": "2026-02-07T10:15:00Z"
}

Update Volume

Update volume properties. Can rename, expand size (no shrinking), or change lifecycle settings.

Method: PATCH Path: /api/volumes/{volumeId}

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Parameters:

Name	Type	Required	Description
`volumeId`	string	Yes	Volume ID to update

Request Body Example:

{
  "name": "renamed-volume",
  "sizeInGb": 200,
  "deleteWithInstance": true
}

Response Example:

{
  "id": "volume_internal_id",
  "volumeId": "vol_abc123",
  "name": "renamed-volume",
  "sizeInGb": 200,
  "virtualIp": "192.168.100.50",
  "hourlyRate": 0.0274,
  "lastPriceUpdate": "2026-02-07T11:00:00Z",
  "deleteWithInstance": true
}

Delete Volume

Delete a volume. Volume must be detached from all deployments first.

Method: DELETE Path: /api/volumes/{volumeId}

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`volumeId`	string	Yes	Volume ID to delete

Response Example:

{
  "success": true
}

Attach Volume

Attach a volume to a running deployment. Volume and deployment must be from the same provider.

Method: POST Path: /api/volumes/{volumeId}/attach

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Parameters:

Name	Type	Required	Description
`volumeId`	string	Yes	Volume ID to attach

Request Body Example:

{
  "deploymentId": "deployment_id_here"
}

Response Example:

{
  "id": "volume_internal_id",
  "volumeId": "vol_abc123",
  "status": "attached",
  "virtualIp": "192.168.100.50",
  "attachedToDeploymentIds": ["deployment_id_here"],
  "attachedToOrderIds": ["order_123"],
  "lastAttachedAt": "2026-02-07T12:00:00Z"
}

Detach Volume

Detach a volume from a deployment. Volume data is preserved and can be attached to another deployment.

Method: POST Path: /api/volumes/{volumeId}/detach

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Parameters:

Name	Type	Required	Description
`volumeId`	string	Yes	Volume ID to detach

Request Body Example:

{
  "deploymentId": "deployment_id_here"
}

Response Example:

{
  "id": "volume_internal_id",
  "volumeId": "vol_abc123",
  "status": "available",
  "virtualIp": "192.168.100.50",
  "attachedToDeploymentIds": [],
  "attachedToOrderIds": [],
  "lastDetachedAt": "2026-02-07T13:00:00Z"
}

Get Volume Pricing

Get storage pricing per GB per hour for a specific provider.

Method: GET Path: /api/volumes/pricing

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`provider`	string	No	Provider name (default: 'voltage-park')

Response Example:

{
  "provider": "voltage-park",
  "hourlyRatePerGb": 0.000137
}

Teams

Get Balance

Get account balance - returns all teams by default.

Method: GET Path: /api/balance

Headers:

Authorization: Bearer YOUR_API_KEY

Parameters:

Name	Type	Required	Description
`teamId`	string	No	Get balance for specific team ID only
`all`	boolean	No	Set to 'false' to get current team only (default: true)

Response Example:

{
  "teams": [
    {
      "teamId": "team_1",
      "teamName": "My Personal Team",
      "balance": 25.50,
      "isCurrentTeam": true,
      "role": "owner"
    },
    {
      "teamId": "team_2",
      "teamName": "Company Team",
      "balance": 150.75,
      "isCurrentTeam": false,
      "role": "admin"
    }
  ],
  "currency": "USD"
}

Error Reference

All error responses follow this format:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

Common HTTP Status Codes

200 OK - Request succeeded

201 Created - Resource created successfully

400 Bad Request - Invalid parameters or request body

{
  "error": "Missing required field: gpuType",
  "code": "VALIDATION_ERROR"
}

401 Unauthorized - Invalid or missing API key

{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED"
}

403 Forbidden - Insufficient permissions

{
  "error": "Insufficient permissions to access this resource",
  "code": "FORBIDDEN"
}

404 Not Found - Resource doesn't exist

{
  "error": "Deployment not found",
  "code": "NOT_FOUND"
}

429 Too Many Requests - Rate limit exceeded

{
  "error": "Rate limit exceeded. Try again in 15 minutes",
  "code": "RATE_LIMIT_EXCEEDED"
}

500 Internal Server Error - Server error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Status Values

Deployment Statuses

deploying
Instance is being provisioned. Usually takes 30-60 seconds.

running
Instance is active and accessible via SSH.

failed
Deployment failed. Check error details in the deployment object.

terminated
Instance has been terminated and is no longer accessible.

Status Lifecycle

deploying → running → terminated
    ↓
  failed

Transitions:

deploying → running: Successful deployment
deploying → failed: Deployment error
running → terminated: Manual termination or deletion
Any status can transition to failed if errors occur

Rate Limits

All API endpoints are subject to rate limiting to ensure fair usage and system stability. Rate limits are tracked per IP address for unauthenticated requests and per user (Firebase UID) for authenticated requests.

Rate Limit Headers

All responses include these headers:

X-RateLimit-Limit: 250
X-RateLimit-Remaining: 245
X-RateLimit-Reset: 2025-12-29T14:00:00.000Z

Rate Limits by Endpoint

GPU Offers & Providers

GET /api/providers
GET /api/gpu-offers

Limit: 250 requests per 15 minutes
Scope: Per IP address
Authentication: Optional (authenticated users see team discounts)

Deployments

POST /api/deployments

Default Limit: 10 deployments per 15 minutes
Scope: Per authenticated user
Custom Limits: Admins can increase limits for enterprise users
Authentication: Required

GET /api/deployments
GET /api/deployments/{deploymentId}
DELETE /api/deployments/{deploymentId}

Limit: 250 requests per 15 minutes
Scope: Per IP address
Authentication: Required

SSH Keys

GET /api/ssh-keys
GET /api/ssh-keys/{id}
POST /api/ssh-keys
DELETE /api/ssh-keys/{id}

Limit: 250 requests per 15 minutes
Scope: Per IP address
Authentication: Required

Balance & Teams

GET /api/balance

Limit: 250 requests per 15 minutes
Scope: Per IP address
Authentication: Required

Rate Limit Response

When rate limit is exceeded (HTTP 429):

{
  "error": "Too many requests",
  "message": "Too many requests from this IP, please try again later.",
  "retryAfter": 900
}

Custom Rate Limits (Enterprise)

Enterprise customers can request custom deployment creation limits:

Contact: info@spheron.ai
Configurable: Deployment creation limit (default: 10 per 15 min)
Options: Custom limit or unlimited deployments

Quick Reference

Endpoint	Rate Limit	Window	Scope	Custom Limits
General API	250 requests	15 min	IP	No
Deployment Creation	10 requests	15 min	User	Yes
All Other API Endpoints	250 requests	15 min	IP	No

Security

Best Practices

Treat API keys like passwords:

Never expose keys in client-side code
Don't commit keys to version control
Use environment variables for credentials
Rotate keys regularly

Key Management:

Generate keys from dashboard settings
Set expiry dates for keys
Revoke compromised keys immediately
Use separate keys for different environments

Connection Security:

All API requests must use HTTPS
Verify SSL certificates
Don't disable certificate validation

Additional Resources

For comprehensive security guidelines, see Security Best Practices.

Common Workflows

Complete Deployment Flow

# 1. Check available GPU offers
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.spheron.ai/api/gpu-offers?search=rtx-4090&limit=5"
 
# 2. Add SSH key (if not already added)
curl -X POST "https://app.spheron.ai/api/ssh-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Key", "publicKey": "ssh-rsa AAA..."}'
 
# 3. Deploy instance
curl -X POST "https://app.spheron.ai/api/deployments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "tensordock",
    "offerId": "rtx-4090-tensordock-1",
    "gpuType": "rtx-4090",
    "gpuCount": 1,
    "region": "us-east-1",
    "operatingSystem": "ubuntu-22.04",
    "instanceType": "DEDICATED",
    "sshKeyId": "your_ssh_key_id"
  }'
 
# 4. Monitor deployment status
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.spheron.ai/api/deployments/deployment_id"
 
# 5. Terminate when done
curl -X DELETE "https://app.spheron.ai/api/deployments/deployment_id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Need Help?

Documentation: Browse our guides
Community: Join our Discord
Security: Review Security Best Practices
Connecting: See Connecting to Instances

API documentation last updated: December 2025

Table of Contents

Quick Start

1. Get Your API Key

2. Make Your First API Call

3. List Available GPUs

4. Deploy Your First Instance

Base URL

Authentication

Endpoints

Get Providers

Get GPU Offers

Deployments

Create Deployment

Get Deployments

Get Deployment Details

Terminate Deployment

Kubernetes

Get Kubernetes Versions

Get Kubernetes Cluster Health

SSH Keys

Get SSH Keys

Add SSH Key

Get SSH Key Details

Delete SSH Key

Volumes

List Volumes

Create Volume

Get Volume Details

Update Volume

Delete Volume

Attach Volume

Detach Volume

Get Volume Pricing

Teams

Get Balance

Error Reference

Common HTTP Status Codes

Status Values

Deployment Statuses

Status Lifecycle

Rate Limits

Rate Limit Headers

Rate Limits by Endpoint

GPU Offers & Providers

Deployments

SSH Keys

Balance & Teams

Rate Limit Response

Custom Rate Limits (Enterprise)

Quick Reference

Security

Best Practices

Additional Resources

Common Workflows

Complete Deployment Flow

Need Help?