Kubernetes API

List clusters

GET /api/v1/kubernetes

const { data: clusters } = await puchify.kubernetes.list({ status: "running" })

clusters = puchify.kubernetes.list(status="running")

clusters, err := client.Kubernetes.List(ctx, &puchify.KubernetesListParams{
  Status: puchify.String("running"),
})

puchify kubernetes list --status running

curl https://api.puchify.com/api/v1/kubernetes \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Query parameters:

Parameter	Type	Description
`cursor`	string	Pagination cursor
`limit`	integer (1-100)	Results per page (default 50)
`status`	string	Filter by status (`creating`, `running`, `deleting`, `deleted`)
`sort`	`name` \| `created_at`	Sort field
`order`	`asc` \| `desc`	Sort direction

Create a cluster

POST /api/v1/kubernetes

const { data: cluster } = await puchify.kubernetes.create({
  name: "prod-cluster",
  region: "us-east",
  version: "1.29",
  node_count: 3,
})

cluster = puchify.kubernetes.create(
  name="prod-cluster",
  region="us-east",
  version="1.29",
  node_count=3,
)

cluster, err := client.Kubernetes.Create(ctx, &puchify.CreateKubernetesInput{
  Name: "prod-cluster", Region: "us-east",
  Version: puchify.String("1.29"), NodeCount: puchify.Int(3),
})

puchify kubernetes create --name prod-cluster --region us-east --version 1.29 --node-count 3

curl -X POST https://api.puchify.com/api/v1/kubernetes \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-cluster","region":"us-east","version":"1.29","node_count":3}'

Request body:

Field	Type	Required	Description
`name`	string	yes	Cluster name (2-40 chars, lowercase alphanumeric + dashes)
`region`	string	yes	Region ID
`version`	string	no	K8s version (default: `1.29`)
`node_count`	integer	no	Initial node count (default: 3, min: 1, max: 100)

Get a cluster

GET /api/v1/kubernetes/{id}

const { data: cluster } = await puchify.kubernetes.get("k8s_abc123")

cluster = puchify.kubernetes.get("k8s_abc123")

cluster, err := client.Kubernetes.Get(ctx, "k8s_abc123")

puchify kubernetes get k8s_abc123

curl https://api.puchify.com/api/v1/kubernetes/k8s_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Update a cluster

PATCH /api/v1/kubernetes/{id}

const { data: cluster } = await puchify.kubernetes.update("k8s_abc123", {
  node_count: 5,
})

cluster = puchify.kubernetes.update("k8s_abc123", node_count=5)

cluster, err := client.Kubernetes.Update(ctx, "k8s_abc123", &puchify.UpdateKubernetesInput{
  NodeCount: puchify.Int(5),
})

puchify kubernetes update k8s_abc123 --node-count 5

curl -X PATCH https://api.puchify.com/api/v1/kubernetes/k8s_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"node_count":5}'

Request body:

Field	Type	Required	Description
`node_count`	integer	no	New node count (scales up/down)
`version`	string	no	Upgrade cluster to a new K8s version

Delete a cluster

DELETE /api/v1/kubernetes/{id}

await puchify.kubernetes.delete("k8s_abc123")

puchify.kubernetes.delete("k8s_abc123")

err := client.Kubernetes.Delete(ctx, "k8s_abc123")

puchify kubernetes delete k8s_abc123

curl -X DELETE https://api.puchify.com/api/v1/kubernetes/k8s_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Get kubeconfig

GET /api/v1/kubernetes/{id}/kubeconfig

const { data: kubeconfig } = await puchify.kubernetes.getKubeconfig("k8s_abc123")

kubeconfig = puchify.kubernetes.get_kubeconfig("k8s_abc123")

kubeconfig, err := client.Kubernetes.GetKubeconfig(ctx, "k8s_abc123")

puchify kubernetes kubeconfig k8s_abc123

curl https://api.puchify.com/api/v1/kubernetes/k8s_abc123/kubeconfig \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Returns the kubeconfig YAML for kubectl access.

List node pools

GET /api/v1/kubernetes/{id}/node-pools

Scale a node pool

POST /api/v1/kubernetes/{id}/node-pools/{pool_id}/scale

Field	Type	Required	Description
`node_count`	integer	yes	Target number of nodes

Polling for readiness

const cluster = await puchify.kubernetes.waitFor("k8s_abc123", "running", {
  timeout: 600_000,    // 10 minutes (cluster provisioning is slow)
  pollInterval: 10_000,
})

cluster = puchify.kubernetes.wait_for("k8s_abc123", "running", timeout=600)

cluster, err := puchify.WaitFor(ctx, client.Kubernetes.Get, "k8s_abc123", "running",
  puchify.WithTimeout(10*time.Minute),
)

Response shape

{
  "data": {
    "id": "k8s_abc123",
    "name": "prod-cluster",
    "status": "running",       // creating | running | deleting | deleted
    "version": "1.29",
    "region": "us-east",
    "node_count": 5,
    "api_endpoint": "https://k8s_abc123.k8s.puchify.com",
    "node_pools": [
      {
        "id": "np_001",
        "name": "default",
        "node_count": 5,
        "plan": "shared-2",
        "status": "running"
      }
    ],
    "created_at": "2026-05-28T10:30:00Z",
    "updated_at": "2026-05-28T10:32:00Z"
  },
  "meta": {
    "persistence": "synced",
    "provider": "connected"
  }
}

Error codes

Code	Description
`404`	Cluster not found
`409`	Conflict — cluster is in a transient state (e.g., provisioning or deleting)
`422`	Invalid version, plan, or region combination

Kubernetes API

On this page