Create a new Kubernetes cluster

POST

https://api.americancloud.com/api/v1/kubernetes

POST

/api/v1/kubernetes

curl -X POST https://api.americancloud.com/api/v1/kubernetes \
     -H "X-API-Client-ID: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "my-cluster",
  "package": "my-package",
  "region": "us-west-0",
  "version": "1.28.4",
  "controlNodes": 1,
  "workerNodes": 3
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "production-cluster",
  "region": "sjc0",
  "status": "running",
  "kubernetesVersion": "1.29.4",
  "createdAt": "2026-05-29T12:34:56Z",
  "package": "standard-2-4",
  "description": "Primary production Kubernetes cluster.",
  "nodePool": {
    "controlNodes": 1,
    "workerNodes": 3,
    "autoscalingEnabled": false,
    "cpuCores": 2,
    "memoryMb": 4096,
    "minWorkers": 2,
    "maxWorkers": 10
  },
  "ipAddress": "203.0.113.5",
  "ipAddressId": "123e4567-e89b-12d3-a456-426614174000",
  "deletedAt": "2026-05-29T12:34:56Z",
  "nodes": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "k8s-worker-01",
      "role": "worker",
      "state": "running",
      "cpuCores": 2,
      "memoryMb": 4096,
      "rootVolume": {
        "name": "k8s-node-root",
        "sizeGb": 50
      },
      "createdAt": "2026-05-29T12:34:56Z",
      "ipAddress": "192.168.1.10"
    }
  ]
}

Creates a new Kubernetes cluster for the authenticated account. To preview pricing without creating anything, use POST /kubernetes/cost-estimate.

Authentication

X-API-Client-IDstring

API Client ID

X-API-Client-Secretstring

API Client Secret

Request

This endpoint expects an object.

namestringRequired

Name of the cluster

packagestringRequired

Package label to use for the cluster

regionstringRequired

Region where to deploy the cluster

versionstringRequired

Kubernetes version to use (semantic version)

controlNodesdoubleRequired

Number of control plane nodes

workerNodesdoubleRequired

Number of worker nodes

descriptionstringOptional

Description of the cluster

networkIdstringOptionalformat: "uuid"

Network ID to use for the cluster

keypairstringOptional

SSH keypair name to use for cluster nodes

Response

The cluster has been successfully created

idstringformat: "uuid"

Unique identifier for the cluster.

namestring

Human-readable name for the cluster.

regionstring

Region the cluster is deployed in.

statusstring

Current lifecycle state of the cluster.

kubernetesVersionstring

Kubernetes version the cluster is running.

createdAtdatetime

When the cluster was created.

packagestring

Package label describing the per-node CPU/memory/disk preset.

descriptionstring

Description of the cluster.

nodePoolobject

Node-pool configuration for the cluster.

ipAddressstringOptionalformat: "ipv4"

Public IP address attached to the cluster.

ipAddressIdstringOptionalformat: "uuid"

Identifier of the public IP attached to the cluster.

deletedAtdatetimeOptional

When the cluster was deleted. Omitted if the cluster still exists.

nodeslist of objectsOptional

Cluster nodes. Only included when details=true.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error