API Reference

CloudNexus provides a RESTful API that allows you to provision, manage, and scale cloud infrastructure programmatically. All requests must be made over HTTPS.

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

Authentication

Authenticate requests using API keys via the `Authorization` header. Replace `YOUR_API_KEY` with your personal access token from the dashboard.

Authorization: Bearer YOUR_API_KEY

const res = await fetch('https://api.cloudnexus.io/v1/instances', {
  headers: { 'Authorization': `Bearer ${process.env.CN_API_KEY}` }
});

GET /instances

Returns a paginated list of all compute instances belonging to your organization.

Query Parameters

Parameter	Type	Description
limitoptional	integer	Maximum number of items to return (default: 20, max: 100)
offsetoptional	integer	Number of items to skip for pagination
regionoptional	string	Filter instances by region slug (e.g., `us-east-1`)

Response 200 OK

curl -X GET "https://api.cloudnexus.io/v1/instances?limit=5" \\
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "inst_8x92j1k0",
      "name": "prod-api-primary",
      "status": "running",
      "region": "us-east-1",
      "specs": {
        "cpu": 4,
        "ram_gb": 16,
        "disk_gb": 200
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 5,
    "offset": 0
  }
}

POST /instances

Provisions a new compute instance with the specified configuration. Returns the instance object once created.

Request Body

Parameter	Type	Description
namerequired	string	Human-readable identifier for the instance
regionrequired	string	Target region slug (e.g., `eu-west-2`)
planrequired	string	Instance tier: `starter`, `pro`, or `enterprise`
imageoptional	string	OS base image ID or slug (default: `ubuntu-22.04`)
ssh_keysoptional	array[string]	List of SSH key IDs to inject

curl -X POST "https://api.cloudnexus.io/v1/instances" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"name": "worker-01", "region": "us-east-1", "plan": "pro"}'

{
  "name": "worker-01",
  "region": "us-east-1",
  "plan": "pro",
  "ssh_keys": ["key_abc123", "key_def456"]
}

GET /regions

Retrieves all available deployment regions with latency, capacity, and status metadata.

{
  "regions": [
    {
      "slug": "us-east-1",
      "name": "Virginia, US",
      "status": "healthy",
      "avg_latency_ms": 12,
      "capacity": true
    },
    {
      "slug": "eu-west-2",
      "name": "London, UK",
      "status": "healthy",
      "avg_latency_ms": 45,
      "capacity": true
    }
  ]
}

Schemas

Instance object

idstringUnique UUID identifier

namestringUser-defined instance name

statusenum`pending`, `provisioning`, `running`, `stopped`, `terminated`

regionstringRegion slug where instance is deployed

public_ipstring | nullAssigned IPv4 address

specsobjectCPU, RAM, and disk configuration

created_atdatetimeISO 8601 timestamp

ErrorResponse object

errorobjectContains error details

codestringMachine-readable error identifier (e.g., `VALIDATION_ERROR`)

messagestringHuman-readable explanation

detailsarray | nullAdditional context or field-specific errors