POST
/vault/hyok/clustersCreate 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
| hostIds | string[] | IDs of registered hosts to group into this cluster (may be empty → the cluster is created |
| 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
| HTTP | K9O Code | Description |
|---|---|---|
| 201 | The cluster was created. | |
| 400 | The name or the region is empty. | |
| 401 | The request carries no authenticated caller. | |
| 500 | An 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 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"
}