API Reference

The CloudNexus REST API allows you to programmatically manage your cloud infrastructure, provision instances, configure networking, and automate deployments. All requests are authenticated via Bearer tokens and use standard HTTP methods.

Base URL

https://api.cloudnexus.io/v1

🔐 Authentication

CloudNexus uses API keys to authenticate requests. Generate your key from the Dashboard > Settings > API Keys. Include it in the `Authorization` header as a Bearer token.

curl https://api.cloudnexus.io/v1/me \
  -H "Authorization: Bearer cn_live_4eC39HqLyjWDarjtT1zdp7dc"
                    

import requests

headers = {
    "Authorization": "Bearer cn_live_4eC39HqLyjWDarjtT1zdp7dc",
    "Content-Type": "application/json"
}

response = requests.get("https://api.cloudnexus.io/v1/me", headers=headers)
print(response.json())
                    

const axios = require("axios");

axios.get("https://api.cloudnexus.io/v1/me", {
  headers: {
    "Authorization": "Bearer cn_live_4eC39HqLyjWDarjtT1zdp7dc"
  }
}).then(res => console.log(res.data));
                    

🖥️ Instances

Manage virtual private servers. Provision, configure, scale, and terminate compute instances programmatically.

GET /v1/instances

Retrieve a paginated list of all compute instances in your account.

Query Parameters

Parameter	Type	Description
status	string	Filter by instance status (running, stopped, pending)
region	string	Filter by data center region (e.g., us-east-1, eu-west-2)
page_size	integer	Number of results per page (default: 25, max: 100)

Response

{
  "instances": [
    {
      "id": "inst_29f8b3a1",
      "name": "web-prod-01",
      "status": "running",
      "region": "us-east-1",
      "plan": "standard-4",
      "ipv4": "104.20.33.112",
      "created_at": "2025-03-14T08:22:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "page_size": 25
  }
}
                    

POST /v1/instances

Provision a new compute instance. Returns a 201 Created with instance details.

curl -X POST https://api.cloudnexus.io/v1/instances \
  -H "Authorization: Bearer cn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "worker-node-02",
    "plan": "standard-8",
    "region": "eu-west-1",
    "image": "ubuntu-22.04",
    "ssh_keys": ["ssh_key_a1b2c3"]
  }'
                    

payload = {
    "name": "worker-node-02",
    "plan": "standard-8",
    "region": "eu-west-1",
    "image": "ubuntu-22.04",
    "ssh_keys": ["ssh_key_a1b2c3"]
}

response = requests.post("https://api.cloudnexus.io/v1/instances", headers=headers, json=payload)
print(response.status_code, response.json())
                    

⚠️ Error Handling

CloudNexus uses standard HTTP status codes to indicate success or failure. 2xx codes indicate success, 4xx codes indicate client errors, and 5xx codes indicate server errors.

200 OK - Request succeeded

201 Created - Resource provisioned

400 Bad Request - Invalid parameters

401 Unauthorized - Invalid API key

403 Forbidden - Insufficient permissions

404 Not Found - Resource doesn't exist

500 Server Error - Internal failure

503 Service Unavailable - Overload

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid region specified",
    "details": [
      {
        "field": "region",
        "reason": "Must be one of: us-east-1, eu-west-1, ap-south-1"
      }
    ]
  }
}
                    