v1.2.0 Stable

API Documentation

The CloudNexus REST API allows you to programmatically provision, manage, and scale cloud infrastructure. All requests must be made over HTTPS and use JSON payloads. HTTP request bodies should be `application/json`.

💡

Quick Start: Generate your API keys from the CloudNexus Dashboard. All endpoints return standardized JSON responses with predictable error handling.

Authentication

Access the API using API keys. Include your key in the `Authorization` header as a Bearer token. Never expose private keys in client-side code.

Header

Authorization: Bearer cnx_sk_live_8f9d2a1b4c5e6f7g8h9i0j

Keys are scoped by environment (`live` or `test`) and permissions (`admin`, `read-only`, or `scoped`). Rate limits are applied per key.

Base URL

All API requests are relative to the production endpoint:

Production

https://api.cloudnexus.io/v1

Sandbox: `https://api-sandbox.cloudnexus.io/v1` (for testing without charges)

Core Resources

Servers

Provision and manage VPS instances with NVMe storage, dedicated resources, and instant deployment.

GET /servers List all servers

Query Parameters

Parameter	Type	Description
`status`	string	Filter by `running`, `stopped`, `provisioning`
`region`	string	Filter by datacenter slug (e.g., `us-east-1`)
`limit`	integer	Max items per page (default: 20)

Response (200)
{
  "data": [
    {
      "id": "srv_8x9y2z3a4b",
      "name": "prod-web-01",
      "status": "running",
      "region": "us-east-1",
      "specs": {
        "cpu": 4,
        "ram_gb": 16,
        "storage_gb": 200
      },
      "ipv4": "192.168.1.45",
      "created_at": "2025-01-12T08:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "next_page": "/v1/servers?page=2"
  }
}

POST /servers Create a server

Request Body
{
  "name": "api-worker-01",
  "region": "eu-west-2",
  "plan": "standard-8",
  "image": "ubuntu-22.04",
  "ssh_keys": ["key_abc123"],
  "auto_backup": true
}

Managed Databases

Deploy PostgreSQL, MySQL, and Redis clusters with automated backups, point-in-time recovery, and read replicas.

POST /databases/scale Scale database cluster

Request Body
{
  "database_id": "db_9f8e7d6c5b",
  "new_tier": "production-high",
  "read_replicas": 3,
  "maintenance_window": "2025-02-01T02:00:00Z"
}

Global CDN

Purge caches, configure routing rules, and inspect edge analytics across 300+ locations.

POST /cdn/zones/{zone_id}/purge Purge CDN cache

Request Body
{
  "paths": ["/assets/v2/*", /static/images/*.webp],
  "etag_match": "a1b2c3d4",
  "async": true
}

Pagination

List endpoints use cursor-based pagination for consistency at scale. Use the `cursor` and `limit` parameters to navigate results.

Example Request

GET /v1/servers?limit=50&cursor=eyJpZCI6InNydl85eDl5MnoifQ==

Responses include `meta.next_cursor` and `meta.prev_cursor` for navigation.

Rate Limits

API requests are limited to prevent abuse and ensure platform stability. Limits vary by plan and key scope.

Free/Trial: 100 requests/minute
Professional: 1,000 requests/minute
Enterprise: Custom limits (up to 10,000+/min)

Rate limit headers are included in every response:

Response Headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1708492800

⚠️

Exceeding limits returns 429 Too Many Requests. Implement exponential backoff in your integration.

Error Handling

CloudNexus uses standard HTTP status codes and returns detailed error objects in the response body. Always check for errors before processing data.

Code	Meaning	Description
`400`	Bad Request	Missing parameters, invalid JSON, or malformed query
`401`	Unauthorized	Invalid or expired API key
`403`	Forbidden	Insufficient permissions for this resource
`404`	Not Found	Resource does not exist or has been deleted
`409`	Conflict	Resource state conflict (e.g., server already running)
`429`	Too Many Requests	Rate limit exceeded. Retry after `X-RateLimit-Reset`
`500`	Server Error	Unexpected infrastructure failure. Contact support.

Error Response Structure
{
  "error": {
    "code": "insufficient_resources",
    "message": "Region eu-west-2 has reached capacity for standard-16 plan.",
    "details": {
      "region": "eu-west-2",
      "suggested_alternatives": ["eu-west-3", "us-east-1"]
    },
    "request_id": "req_8a9b0c1d2e"
  }
}