Infrastructure API

Programmatically provision, configure, and manage CloudNexus cloud resources. The API uses standard HTTP methods, JSON payloads, and RESTful endpoints.

Note: All requests must be authenticated using an API key or JWT token passed in the Authorization header. Rate limits are applied per project, not per user.

Authentication

CloudNexus uses API keys for server-to-server authentication. You can generate keys in the dashboard under Settings → API Access.

curl

curl -X POST https://api.cloudnexus.io/v1/instances \
  -H "Authorization: Bearer $CLOUDNEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "us-east-1",
    "type": "c2-standard-4",
    "image": "ubuntu-22.04-lts",
    "name": "prod-app-server-01",
    "firewall_groups": ["fw-web-allow"]
  }'

Create a Virtual Instance

Provisions a new cloud server in the specified region with the requested configuration.

Endpoint

HTTP

POST /v1/instances

Request Parameters

Parameter	Type	Required	Description
region	string	Required	Target deployment region (e.g., `us-east-1`, `eu-west-2`)
type	string	Required	Machine plan identifier. See Compute Plans
image	string	Required	OS or custom image ID to deploy
name	string	Optional	Human-readable server name (defaults to auto-generated UUID)
firewall_groups	array	Optional	Array of firewall rule group IDs to attach

Response

Returns a 202 Accepted with an asynchronous job identifier. The instance status can be polled via GET /v1/instances/{id}.

JSON

{
  "id": "inst_8f9a2c3d1e0b",
  "status": "provisioning",
  "region": "us-east-1",
  "type": "c2-standard-4",
  "ipv4": "104.132.58.91",
  "ipv6": "2607:f8b0:4004:800::200e",
  "created_at": "2025-01-15T08:42:11Z",
  "job_id": "job_7x8y9z0a1b2c"
}

Rate Limits & Error Handling

API requests are rate-limited to 100 requests per minute for standard tiers and 1000 RPM for enterprise. Exceeding limits returns 429 Too Many Requests.

Code	Status	Description
400	Bad Request	Malformed JSON or missing required fields
401	Unauthorized	Invalid or expired API key
403	Forbidden	Insufficient permissions for the requested action
404	Not Found	Resource does not exist or has been deleted
429	Rate Limited	Too many requests. Check `X-RateLimit-Reset` header

Best Practice: Implement exponential backoff with jitter when handling 429 or 5xx errors to ensure reliable automation.

Last updated: Jan 14, 2025