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"
          }
        }
      ]
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 10,
  "totalPages": 5
}

Deployments

Create Deployment

Create a new GPU instance deployment.

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).

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"
      }
    ]
  }
}

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",
  "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",
    "ipAddress": "192.168.1.100",
    "user": "ubuntu",
    "status": "running",
    "sshCommand": "ssh ubuntu@192.168.1.100",
    "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",
  "ipAddress": "192.168.1.100",
  "user": "ubuntu",
  "status": "running",
  "sshCommand": "ssh ubuntu@192.168.1.100",
  "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"
  }
}

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
}

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

Standard Limits:

100 requests per 15 minutes per IP address
Enhanced rate limiting for authentication endpoints

Headers:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Timestamp when limit resets

Handling Rate Limits:

Check response headers to track usage
Implement exponential backoff for retries
Cache frequently accessed data (GPU offers, providers)

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

SSH Keys

Get SSH Keys

Add SSH Key

Get SSH Key Details

Delete SSH Key

Get Balance

Error Reference

Common HTTP Status Codes

Status Values

Deployment Statuses

Status Lifecycle

Rate Limits

Security

Best Practices

Additional Resources

Common Workflows

Complete Deployment Flow

Need Help?