CloudNexus API

Programmatically manage your cloud infrastructure. The API follows RESTful conventions, uses standard HTTP status codes, and returns JSON payloads. All requests must be made over HTTPS.

🔐 Authentication

CloudNexus uses API keys for authentication. You can generate and manage your keys in the Dashboard → API Keys section. Include your key in the Authorization header as a Bearer token.

Example

Authorization: Bearer cnx_live_4f3b2c1d0e9a8f7e6d5c4b3a2f1e0d9c

# Never expose your secret key in client-side code.
# Use environment variables or secure vaults.

⚠️

API keys with cnx_live_ prefix affect production resources. Use cnx_test_ for sandbox environments.

⏱️ Rate Limits

API requests are rate-limited to ensure platform stability. Limits vary by plan:

Starter: 60 requests/minute
Professional: 300 requests/minute
Enterprise: 1,000+ requests/minute (custom)

Rate limit status is returned in response headers:

Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1702834567

🖥️ Compute Endpoints

GET /v1/instances List all compute instances

Returns a paginated list of all instances in your account. Supports filtering by region, status, and tags.

Query Parameters

Parameter	Type	Required	Description
region	string	Optional	Filter by data center region
status	string	Optional	Filter by status (running, stopped, provisioning)
page	integer	Optional	Page number for pagination
limit	integer	Optional	Items per page (max 100)

POST /v1/instances Create a new instance

Provisions a new virtual machine with the specified configuration. Deployment typically completes within 30-60 seconds.

Request Body

Parameter	Type	Required	Description
name	string	Required	Instance identifier
plan	string	Required	Compute tier (starter, pro, enterprise)
region	string	Required	Deployment region
image	string	Required	OS image ID or snapshot
tags	array	Optional	Metadata tags for organization

Example Request

curl JavaScript Python

curl -X POST https://api.cloudnexus.com/v1/instances \\
  -H "Authorization: Bearer cnx_live_4f3b2c1d0e9a8f7e6d5c4b3a2f1e0d9c" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "prod-api-01",
    "plan": "pro",
    "region": "us-east-1",
    "image": "ubuntu-22.04-lts",
    "tags": ["web", "production"]
  }'

GET /v1/instances/:id Get instance details

Returns detailed configuration, metrics, and status for a specific instance.

DELETE /v1/instances/:id Destroy an instance

Permanently deletes an instance and all associated ephemeral storage. Snapshots are preserved unless explicitly removed.

ℹ️

Deleted instances cannot be recovered. Ensure you have recent snapshots before proceeding.

🚨 Error Handling

CloudNexus uses standard HTTP status codes. Error responses include a structured JSON body with a machine-readable code and human-readable message.

Common Status Codes

200 Success

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Rate Limited

500 Internal Error

Error Response Format

JSON Response

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Account balance is below minimum threshold.",
    "details": {
      "current_balance": "$2.45",
      "required": "$5.00"
    },
    "request_id": "req_8f7e6d5c4b3a2f1e"
  }
}

📦 SDKs & Tools

Official SDKs are available for popular languages. Community-maintained wrappers are also supported.

npm pip go

npm install @cloudnexus/sdk
pip install cloudnexus
go get github.com/cloudnexus/go-sdk