↗ Open in Editor

Compute API

Programmatically provision, manage, and scale virtual machines, bare metal servers, and high-performance container runtimes across 50+ global regions.

Base URL: https://api.cloudnexus.com/v1

Authentication

All Compute API requests require an active API key. Include it in the Authorization header using Bearer token authentication:

Header

Authorization: Bearer cn_live_sk_8f3a2b9c4d1e5f6a7b8c9d0e

⚠️

Never expose live API keys in client-side code or public repositories. Use cn_test_ prefixed keys for development environments.

GET /compute/instances List all compute instances

Returns a paginated list of compute instances accessible by your API key. Supports filtering by region, status, and tags.

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number for pagination (default: 1)
per_page	integer	Optional	Items per page (max: 100, default: 20)
region	string	Optional	Filter by region slug (e.g., `us-east-1`)
status	string	Optional	Filter by status: `running`, `stopped`, `provisioning`

Example Request

cURL

curl -X GET \"https://api.cloudnexus.com/v1/compute/instances?page=1&per_page=10\" \\
  -H "Authorization: Bearer cn_live_sk_..." \\
  -H "Content-Type: application/json"

Example Response

JSON

{
  "data": [
    {
      "id": "inst_9x7k2m4p1q8r5s0t",
      "name": "prod-api-node-01",
      "type": "standard-4x8",
      "region": "us-east-1",
      "status": "running",
      "ipv4": "198.51.100.42",
      "created_at": "2024-11-15T08:32:10Z"
    }
  ],
  "pagination": {
    "total": 47,
    "page": 1,
    "per_page": 10,
    "total_pages": 5
  }
}

POST /compute/instances Create a new compute instance

Provisions a new virtual machine or bare metal server. Returns a job ID that can be polled for deployment status.

Request Body

Field	Type	Required	Description
name	string	Required	Human-readable instance name
type	string	Required	Instance spec: `standard-2x4`, `compute-8x16`, `memory-4x32`
region	string	Required	Target deployment region
image	string	Required	Base OS image slug or custom snapshot ID
ssh_keys	array	Optional	List of SSH key IDs to inject
tags	object	Optional	Key-value metadata for resource organization

Example Request

JSON

{
  "name": "worker-node-alpha",
  "type": "compute-8x16",
  "region": "eu-west-2",
  "image": "ubuntu-22.04-lts",
  "ssh_keys": ["key_7f8g9h0j1k2l"],
  "tags": {
    "environment": "production",
    "team": "platform"
  }
}

💡

Provisioning typically takes 15-45 seconds. Use the returned job_id with the Jobs API to track deployment progress.

POST /compute/instances/:id/actions Execute instance actions

Perform lifecycle operations on an existing instance. Actions are executed asynchronously.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The unique instance identifier

Request Body

Field	Type	Required	Description
action	string	Required	One of: `start`, `stop`, `reboot`, `resize`, `snapshot`
type	string	Optional	Required only for `resize`. Target instance type.

Example Request

JSON

{
  "action": "resize",
  "type": "memory-4x32"
}

Error Handling & Rate Limits

The Compute API follows standard HTTP status codes and returns JSON error objects. Rate limits are enforced at 120 requests/minute for standard keys and 1000 requests/minute for enterprise tiers.

Code	Meaning	Details
400	Bad Request	Invalid parameters or malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for requested action
404	Not Found	Instance or resource does not exist
429	Too Many Requests	Rate limit exceeded. Check `Retry-After` header.
500	Internal Error	Platform-side failure. Contact support if persistent.