Skip to main content
POST/vault/hyok/clusters

Create Cluster

Groups registered hosts into a cluster.

A project attaches to a cluster, not to a single host.

A cluster with no hosts is created inactive.

Needs ORG_ADMIN.

Parameters
orgId *query

The organisation's id.

Request body
hostIdsstring[]

IDs of registered hosts to group into this cluster (may be empty → the cluster is created inactive).

name *string

Human-readable cluster name.

Example: "luna-prod-eu"
region *string

The region the cluster's hosts are in.

A project in another region can't attach to the cluster.

Example: "de01"
Responses
HTTPK9O CodeDescription
201The cluster was created.
400The name or the region is empty.
401The request carries no authenticated caller.
500An internal error. Retry later.
Response body (201)
attachedProjectIds *string[]

Project IDs currently in HYOK mode using this cluster.

createdAt *string <date-time>

Cluster creation timestamp.

Example: "2026-11-01T08:00:00.000Z"
hostIds *string[]

IDs of hosts in this cluster.

id *string

Cluster identifier — UUID prefixed "hyokcluster_".

Example: "hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e"
name *string

Human-readable cluster name.

Example: "luna-prod-eu"
orgId *string

Owning org.

Example: "org_8kP3wQ9zLm2X"
region *string

Region — must match the Kibo project's region pin at attach time.

Example: "de01"
status *"active" | "warning" | "degraded" | "inactive"

HYOK cluster operational status.

cURL
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/vault/hyok/clusters' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "luna-prod-eu",
  "hostIds": [
    "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c"
  ],
  "region": "de01"
}'

Showing example in cURL

Request example
{
  "name": "luna-prod-eu",
  "hostIds": [
    "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c"
  ],
  "region": "de01"
}
Response example (201)
{
  "attachedProjectIds": [
    "3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b"
  ],
  "createdAt": "2026-11-01T08:00:00.000Z",
  "hostIds": [
    "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c"
  ],
  "id": "hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e",
  "name": "luna-prod-eu",
  "orgId": "org_8kP3wQ9zLm2X",
  "region": "de01",
  "status": "active"
}

More in HYOK Clusters & Hosts