API Overview
The CloudNexus REST API enables you to programmatically manage your cloud infrastructure. Create, scale, and monitor instances, networks, databases, and storage resources with predictable, versioned endpoints.
Base URL & Versions
All API requests are sent over HTTPS. Calls made without encryption will fail.
https://api.cloudnexus.com/v2
The API is versioned via the URL path. The current stable version is v2. Breaking changes will only be introduced in major version updates.
Authentication
Authenticate your requests by including an API key in the Authorization header using the Bearer scheme.
Authorization: Bearer <your_api_key>
You can manage and rotate API keys in the CloudNexus Dashboard → Settings → API Keys.
Compute & Instances
Manage virtual machines, containers, and serverless functions. Provision resources in any of our 50+ global regions.
Retrieve a paginated list of all compute instances in your account.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
region | string | No | Filter by region ID (e.g., us-east-1) |
status | string | No | Filter by status: running, stopped, provisioning |
limit | integer | No | Number of results (default: 20, max: 100) |
cursor | string | No | Pagination cursor from previous response |
{
"data": [
{
"id": "inst_8f9a2b3c4d",
"name": "prod-api-01",
"region": "us-east-1",
"status": "running",
"cpu": 4,
"memory_gb": 16,
"ipv4": "192.168.10.45",
"created_at": "2025-01-15T08:30:00Z"
}
],
"pagination": {
"next_cursor": "eyJpZCI6MTAwfQ==",
"has_more": true
}
}
Provision a new compute instance. Supports custom images, SSH keys, and network configurations.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Human-readable identifier |
region | string | Yes | Target deployment region |
plan | string | Yes | Instance type: micro, standard-4, memory-16 |
image | string | Yes | OS image slug or custom ID |
ssh_keys | array | No | Array of SSH key IDs to attach |
user_data | string | No | Base64-encoded cloud-init script |
Gracefully restart a running instance. Returns immediately; instance status will transition to rebooting.
{
"id": "inst_8f9a2b3c4d",
"status": "rebooting",
"message": "Restart initiated successfully"
}
Networking & Firewalls
Configure VPCs, load balancers, private networks, and security rules. All traffic is isolated by default.
List all private networks and VPCs associated with your account.
| Parameter | Type | Required | Description |
|---|---|---|---|
vpc_id | string | No | Filter by parent VPC |
environment | string | No | Tag filter: production, staging |
Storage & Volumes
Attach persistent block storage, manage snapshots, and configure lifecycle policies for automated backups.
Retrieve all block storage volumes. Supports filtering by attachment state and region.
Error Handling
The API uses standard HTTP status codes and returns detailed error objects in JSON format.
| Code | Meaning | Common Causes |
|---|---|---|
400 | Bad Request | Invalid JSON, missing required fields, malformed query params |
401 | Unauthorized | Missing/invalid API key, expired token |
403 | Forbidden | Insufficient permissions, region access blocked |
404 | Not Found | Resource ID doesn't exist, endpoint typo |
409 | Conflict | Duplicate name, resource already in requested state |
422 | Unprocessable | Validation failed, invalid image slug, quota exceeded |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Error | Upstream service failure, infrastructure issue |
{
"error": {
"code": 422,
"message": "Validation failed",
"details": [
{
"field": "region",
"message": "Invalid region identifier"
}
]
}
}
Rate Limiting
API requests are rate-limited to ensure fair usage and platform stability. Limits vary by plan and endpoint type.
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 582
X-RateLimit-Reset: 1737849600
Retry-After: 42 /* Only present on 429 responses */
Pro Tier: 600 requests/minute
Enterprise: 2,000+ requests/minute (custom)
Implement exponential backoff when receiving 429 responses. Respect the Retry-After header to avoid repeated failures.
SDKs & Tools
Accelerate development with our official client libraries and CLI tools.