API Reference

Integrate with CloudNexus infrastructure using our RESTful API. All requests require authentication and return JSON responses. Base URL: https://api.cloudnexus.io/v2

🔐 Authentication

All API requests must include your API key in the Authorization header. Keys can be generated from the Developer Dashboard.

Authorization Header

Authorization: Bearer nx_live_sk_8f9d2a1b...

Never expose live keys in client-side code. Use environment variables or secure secret managers.

⏱️ Rate Limits

API requests are limited to 1,000 requests per minute per API key. Exceeding this returns a 429 Too Many Requests response.

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1698765432

🖥️ Compute API

GET /instances

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

Query Parameters

Parameter	Type	Required	Description
region	string	Optional	Filter by data center (e.g., us-east-1)
status	string	Optional	Filter by state: running, stopped, pending
limit	integer	Optional	Max items per page (default: 20, max: 100)

cURL Example

curl -X GET "https://api.cloudnexus.io/v2/instances?region=us-east-1&limit=10" \
  -H "Authorization: Bearer nx_live_sk_..."

Response: 200 OK

{
  "instances: [
    {
      "id: "inst_9x7a2b1c",
      "name: "prod-web-01",
      "status: "running",
      "region: "us-east-1",
      "cpu: 4,
      "memory_gb: 16,
      "created_at: "2024-01-15T08:32:00Z"
    }
  ],
  "pagination: {
    "next_cursor: "eyJpZCI6Imluc3RfOXg3YTJiMWMifQ==",
    "total: 42
  }
}

POST /instances

Provision a new virtual machine with specified resources, image, and networking configuration.

Parameter	Type	Required	Description
name	string	Required	Human-readable instance name
plan	string	Required	Compute tier: nano, micro, standard, performance
image_id	string	Required	OS template ID (e.g., ubuntu-22.04)
ssh_keys	string[]	Required	Array of SSH key IDs to inject

Request Body (JSON)

{
  "name: "api-worker-03",
  "plan: "standard",
  "image_id: "img_ubuntu2204_v3",
  "ssh_keys: ["key_8f9a2b1c", "key_deploy_prod"],
  "region: "eu-west-2"
}

DELETE /instances/:id

Permanently terminate an instance. All associated storage will be deleted unless snapshot retention is enabled. This action is irreversible.

cURL

curl -X DELETE "https://api.cloudnexus.io/v2/instances/inst_9x7a2b1c" \
  -H "Authorization: Bearer nx_live_sk_..."

💾 Storage API

GET /buckets

List all object storage buckets. Returns metadata including size, region, and access policy.

Response: 200 OK

{
  "buckets: [
    {
      "id: "bk_prod-assets",
      "region: "us-central1",
      "size_bytes: 4829348204,
      "access: "private",
      "created_at: "2023-11-02T14:20:00Z"
    }
  ]
}

PUT /objects/:bucket/:key

Upload or overwrite an object. Supports multipart uploads for files > 100MB. Returns ETag and content-hash on success.

Headers

Content-Type: application/octet-stream
X-Object-Metadata: {"category":"logs","retention":"30d"}

⚠️ Error Codes

CloudNexus uses standard HTTP status codes. Errors return a consistent JSON structure.

Error Response Format

{
  "error: {
    "code: "RESOURCE_NOT_FOUND",
    "message: "Instance inst_9x7a2b1c does not exist",
    "request_id: "req_7f8a9b2c1d"
  }
}

400 Bad Request - Malformed JSON, missing required parameters, or invalid values.

401 Unauthorized - Invalid or expired API key.

403 Forbidden - Insufficient permissions or IP whitelist block.

404 Not Found - Resource does not exist or ID is invalid.

429 Too Many Requests - Rate limit exceeded. Retry after X-RateLimit-Reset.

500 Internal Server Error - Unexpected failure. Contact support with request_id.