Clouds API

Programmatically create, manage, and monitor your Clouds using the REST API.

// Endpoints Overview

Method	Endpoint	Description
`GET`	`/v1/clouds`	List all clouds
`POST`	`/v1/clouds`	Create a new cloud
`GET`	`/v1/clouds/:id`	Get cloud details
`PATCH`	`/v1/clouds/:id`	Update cloud settings
`DELETE`	`/v1/clouds/:id`	Delete a cloud
`GET`	`/v1/clouds/:id/metrics`	Get cloud metrics
`GET`	`/v1/clouds/:id/logs`	Stream cloud logs
`POST`	`/v1/clouds/:id/scale`	Manually scale cloud

// The Cloud Object

{
  "id": "cloud_abc123xyz",
  "name": "production-cloud",
  "display_name": "Production Cloud",
  "status": "running",
  "region": "us-east-1",
  "tier": "pro",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T12:45:00Z",

  "resources": {
    "cpu": 4,
    "memory_gb": 8,
    "storage_gb": 200,
    "bandwidth_gb": 500
  },

  "usage": {
    "cpu_percent": 35.5,
    "memory_percent": 62.1,
    "storage_used_gb": 45.2,
    "bandwidth_used_gb": 125.8
  },

  "agents": {
    "total": 12,
    "running": 10,
    "stopped": 2
  },

  "network": {
    "endpoint": "https://production-cloud.shellhub.app",
    "ip_addresses": ["203.0.113.10", "203.0.113.11"]
  },

  "security": {
    "shellguard_enabled": true,
    "protection_level": "standard",
    "ssl_certificate": "auto"
  },

  "metadata": {
    "environment": "production",
    "team": "backend"
  }
}

Status Values

Status	Description
`provisioning`	Cloud is being created
`running`	Cloud is active and healthy
`updating`	Configuration change in progress
`stopped`	Cloud is stopped (not billed)
`error`	Cloud has an issue
`deleting`	Cloud is being deleted

// List Clouds

GET/v1/clouds

Returns a paginated list of all clouds in your account.

Query Parameters

Parameter	Type	Description
`limit`	integer	Max results per page (default: 20, max: 100)
`offset`	integer	Number of results to skip
`status`	string	Filter by status
`region`	string	Filter by region

Example Request

curl https://api.shellhub.app/v1/clouds?limit=10&status=running \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "cloud_abc123",
      "name": "production",
      "status": "running",
      "region": "us-east-1",
      "tier": "pro"
    },
    {
      "id": "cloud_def456",
      "name": "staging",
      "status": "running",
      "region": "us-east-1",
      "tier": "starter"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 10,
    "offset": 0
  }
}

// Create Cloud

POST/v1/clouds

Creates a new cloud in the specified region.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Unique name (lowercase, alphanumeric, hyphens)
`region`	string	Yes	Region code (e.g., us-east-1)
`tier`	string	No	starter, pro, or enterprise (default: starter)
`display_name`	string	No	Human-readable name
`metadata`	object	No	Custom key-value pairs

Example Request

curl -X POST https://api.shellhub.app/v1/clouds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-production-cloud",
    "region": "us-east-1",
    "tier": "pro",
    "display_name": "Production Environment",
    "metadata": {
      "environment": "production",
      "team": "backend"
    }
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "cloud_new123",
    "name": "my-production-cloud",
    "status": "provisioning",
    "region": "us-east-1",
    "tier": "pro",
    "created_at": "2024-01-15T15:00:00Z"
  }
}

// Get Cloud

GET/v1/clouds/:id

Returns detailed information about a specific cloud.

curl https://api.shellhub.app/v1/clouds/cloud_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

// Update Cloud

PATCH/v1/clouds/:id

Updates cloud settings. Only provided fields will be changed.

curl -X PATCH https://api.shellhub.app/v1/clouds/cloud_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "enterprise",
    "metadata": {
      "environment": "production",
      "cost_center": "eng-001"
    }
  }'

Note: Changing the tier may cause a brief interruption while resources are adjusted. Plan upgrades take effect immediately; downgrades take effect at the next billing cycle.

// Delete Cloud

DELETE/v1/clouds/:id

Permanently deletes a cloud and all its agents. This action cannot be undone.

curl -X DELETE https://api.shellhub.app/v1/clouds/cloud_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Warning: All agents, data, and configurations will be permanently deleted. Make sure to backup any important data before deletion.

// Get Cloud Metrics

GET/v1/clouds/:id/metrics

Returns performance metrics for the specified time range.

Query Parameters

Parameter	Type	Description
`period`	string	1h, 6h, 24h, 7d, 30d (default: 24h)
`metrics`	string[]	cpu, memory, network, requests
`interval`	string	1m, 5m, 15m, 1h (default: auto)

{
  "success": true,
  "data": {
    "period": "24h",
    "interval": "15m",
    "metrics": {
      "cpu": {
        "avg": 35.5,
        "max": 78.2,
        "min": 12.1,
        "datapoints": [
          { "timestamp": "2024-01-15T00:00:00Z", "value": 32.1 },
          { "timestamp": "2024-01-15T00:15:00Z", "value": 34.5 },
          ...
        ]
      },
      "memory": {
        "avg": 62.1,
        "max": 85.3,
        "min": 45.2
      },
      "requests": {
        "total": 125847,
        "success_rate": 99.8,
        "avg_latency_ms": 45
      }
    }
  }
}

// SDK Examples

Python

from shellhub import ShellHub

client = ShellHub(api_key="ic_live_...")

# List clouds
clouds = client.clouds.list()

# Create a cloud
cloud = client.clouds.create(
    name="my-cloud",
    region="us-east-1",
    tier="pro"
)

# Get metrics
metrics = client.clouds.get_metrics(
    cloud_id="cloud_abc123",
    period="24h"
)

Node.js

import { ShellHub } from '@shellhub/sdk';

const client = new ShellHub({ apiKey: 'ic_live_...' });

// List clouds
const clouds = await client.clouds.list();

// Create a cloud
const cloud = await client.clouds.create({
  name: 'my-cloud',
  region: 'us-east-1',
  tier: 'pro'
});

// Get metrics
const metrics = await client.clouds.getMetrics('cloud_abc123', {
  period: '24h'
});