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",
  "region": "us-west-0",
  "version": "1.28.4",
  "controlNodes": 1,
  "workerNodes": 3,
  "package": "basic"
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "production-cluster",
  "region": "sjc0",
  "status": "running",
  "kubernetesVersion": "1.29.4",
  "createdAt": "2026-05-29T12:34:56Z",
  "description": "Primary production Kubernetes cluster.",
  "nodePool": {
    "controlNodes": 1,
    "workerNodes": 3,
    "autoscalingEnabled": false,
    "control": {
      "package": "standard-2-4",
      "cpuCores": 2,
      "memoryMb": 4096
    },
    "worker": {
      "package": "standard-2-4",
      "cpuCores": 2,
      "memoryMb": 4096
    },
    "cpuCores": 2,
    "memoryMb": 4096,
    "minWorkers": 2,
    "maxWorkers": 10
  },
  "package": "standard-2-4",
  "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

regionstringRequired

Region where to deploy the cluster

versionstringRequired

Kubernetes version to use (semantic version)

controlNodesdoubleRequired>=1

Number of control plane nodes: a whole number, 1 or more.

workerNodesdoubleRequired>=1

Number of worker nodes: a whole number, 1 or more.

packagestringOptional

Package label to use for every node in the cluster. Use controlPackage or workerPackage to give one node type a different package. Required unless you send both controlPackage and workerPackage. Leave it out when you send both.

controlPackagestringOptional

Package label for the control-plane nodes. Overrides package.

workerPackagestringOptional

Package label for the worker nodes. Overrides package.

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.

descriptionstring

Description of the cluster.

nodePoolobject

Node-pool configuration for the cluster.

packagestringDeprecated

Package label of the worker nodes (deprecated, use nodePool.control.package and nodePool.worker.package).

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