---
title: "Create a CoreCluster"
url: https://docs.corefinity.com/api/reference/corecluster/create-cluster
type: endpoint
last_updated: 2026-11-13
feature: cluster-create
related:
  - https://docs.corefinity.com/guides/corecluster/create-a-cluster.md
  - https://docs.corefinity.com/mcp/tools/corecluster_create.md
---
# Create a CoreCluster

Creates a CoreCluster in a region on a package, with up to ten first sites, charged at the package's price
from the moment it is created. Follow it with `GET /corestack/clusters/{cluster}/progress` until it has
finished. Only a create that is accepted counts towards the rate limit, which your whole company shares.

```http
POST /api/corestack/clusters
```

- Scope: `write`
- Two-factor: required on your account (all)
- Rate limit: 10 an hour
- Long-running: answers with an operation to poll
- Try it in the console: off. It can add to your bill. Copy the request and run it yourself when you are sure.

## Body

- `compute_family` (string): The server type. `optimised` is accepted only while it is offered to your company. One of `general`, `optimised`. Defaults to `general`.
- `name` (string, required): The CoreCluster's name: letters, digits, spaces and `. & ' ( ) -`, starting with a letter or a digit. No other CoreCluster of your company may have it.
- `package` (string, required): The key of a CoreCluster package, such as `xsmall`. `GET /corestack/packages` lists them.
- `region` (string, required): A region that is open for the package. `GET /corestack/regions` lists them. One of `uk`, `us`, `nl`, `aus`.
- `sites` (array of objects): The first sites to create with the CoreCluster. Add the rest once it is ready.
  - `content` (string, required): `empty` for a site with no application installed, `fresh` for a fresh install. One of `empty`, `fresh`.
  - `domain` (string, required): The site's public domain, without `www.`. Each domain may appear once in the request.
  - `fresh` (object or any or null): The settings of a fresh install. Read only when `content` is `fresh`.
  - `mariadb_version` (string): A MariaDB version the platform offers. Left out, the platform's default.
  - `node_acknowledge` (array of strings): `["eol"]` to accept a Node.js version past its end of life, which is refused `ack_required` without it.
  - `node_major` (integer or null): The Node.js major version for the site, as a number such as `22`, from the ones offered for the platform. Left out, the default. Where a new site cannot choose one yet, it is refused `runtime_not_adopted`.
  - `php_version` (string): A PHP version the platform offers, such as `8.3`. Left out, the platform's default.
  - `platform` (string, required): A platform the package offers, such as `wordpress`, `laravel` or `magento2`.
  - `tier` (string, required): The size of the site, such as `S`, `M` or `L`. It must be one the platform has and the package offers.
  - `varnish` (object or null): Magento 2 only. Whether the site starts with Varnish. Left out, the platform decides.
    - `enabled` (boolean, required)
    - `version` (string or null): A Varnish version the platform offers, such as `7.7`. Only with `enabled` true.

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/corestack/clusters \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "compute_family": "general",
    "name": "Northwind UK 2",
    "package": "xsmall",
    "region": "uk"
  }'
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->post('https://manage.corefinity.com/api/corestack/clusters', [
        'compute_family' => 'general',
        'name' => 'Northwind UK 2',
        'package' => 'xsmall',
        'region' => 'uk',
    ]);

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/clusters', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    compute_family: 'general',
    name: 'Northwind UK 2',
    package: 'xsmall',
    region: 'uk',
  }),
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.post(
    "https://manage.corefinity.com/api/corestack/clusters",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "compute_family": "general",
        "name": "Northwind UK 2",
        "package": "xsmall",
        "region": "uk",
    },
)

data = res.json() if res.content else None
```

## Responses

### 201 The CoreCluster is being created. `sites` lists each first site with its own operation.

```json
{
  "cluster": {
    "actions": {
      "create_environment": {
        "available": false,
        "reason": "This cluster is still being created"
      },
      "create_site": {
        "available": false,
        "reason": "This cluster is still being created"
      },
      "delete": {
        "available": false,
        "reason": "This cluster is still being created"
      },
      "upgrade_package": {
        "available": false,
        "downgrade": false,
        "reason": "This cluster is still being created"
      }
    },
    "allowance": {
      "cpu_millicores": 4000,
      "disk_bytes": 214748364800,
      "memory_bytes": 17179869184
    },
    "capacity": {
      "basis": "estimate",
      "cpu": {
        "capacity_millicores": 4000,
        "level": "ok",
        "percent": 0,
        "used_p95_millicores": 0
      },
      "evaluated_at": null,
      "level": "ok",
      "memory": {
        "capacity_bytes": 17179869184,
        "level": "ok",
        "percent": 0,
        "used_p95_bytes": 0
      },
      "package": {
        "cores": 4,
        "key": "xsmall",
        "memory_bytes": 17179869184,
        "name": "Extra small"
      },
      "sites": {
        "count": 0,
        "environments": 0
      },
      "storage": {
        "capacity_bytes": 214748364800,
        "level": "ok",
        "percent": 0,
        "provisioned_bytes": 0
      }
    },
    "created_at": "2026-11-14T10:00:00Z",
    "created_by": {
      "id": 2041,
      "name": "Eleanor Finch"
    },
    "environments": 0,
    "id": 1018,
    "kind": "customer",
    "label": "Northwind UK 2",
    "location": {
      "arch": "arm64",
      "label": "London (europe-west2)"
    },
    "logs": null,
    "name": "Northwind UK 2",
    "operation": {
      "id": 5130,
      "scope": "cluster",
      "status": "committed",
      "status_label": "Waiting for the platform",
      "summary": "New cluster",
      "to_version": null,
      "type": "cluster_create",
      "type_label": "New cluster"
    },
    "package": {
      "cores": 4,
      "key": "xsmall",
      "name": "Extra small"
    },
    "pending_changes": {
      "count": 0,
      "window_starts_at": null
    },
    "ready_at": null,
    "region": {
      "key": "uk",
      "label": "United Kingdom",
      "place": "London (europe-west2)"
    },
    "reserved": {
      "cpu_limit_millicores": 0,
      "cpu_request_millicores": 0,
      "disk_bytes": 0,
      "memory_limit_bytes": 0,
      "memory_request_bytes": 0
    },
    "sites": {
      "applying": 0,
      "degraded": 0,
      "down": 0,
      "environments": 0,
      "healthy": 0,
      "live": 0,
      "preview": 0,
      "total": 0,
      "unknown": 0
    },
    "slug": "northwind-uk-2",
    "snapshots": {
      "frequency": "6h",
      "over_quota": false,
      "pruned_recently": false,
      "quota_bytes": 429496729600,
      "retention_days": 30,
      "usage_bytes": null
    },
    "ssh_host": "ssh-northwind-uk-2.example.net",
    "state": "creating",
    "state_label": "Creating",
    "state_reason": null,
    "synced": {
      "inventory_at": "2026-11-14T10:00:00Z",
      "live_at": null,
      "usage_at": null
    },
    "usage": {
      "cpu_millicores": null,
      "disk_used_bytes": null,
      "memory_bytes": null,
      "observed_at": null,
      "source": null
    }
  },
  "operation": {
    "applied_at": null,
    "can_retry": false,
    "cluster": {
      "id": 1018,
      "name": "Northwind UK 2"
    },
    "committed_at": "2026-11-14T10:00:01Z",
    "completed_at": null,
    "created_at": "2026-11-14T10:00:00Z",
    "environment": null,
    "error": null,
    "failure_reason": null,
    "from_version": null,
    "hot": false,
    "id": 5130,
    "install": null,
    "label": "SSH gateway ready",
    "notes": [],
    "parent_operation_id": null,
    "requested_by": {
      "id": 2041,
      "name": "Eleanor Finch"
    },
    "result": null,
    "result_state": "none",
    "retried_by_operation_id": null,
    "retries_operation_id": null,
    "retry_requires": null,
    "scope": "cluster",
    "site": null,
    "status": "committed",
    "status_label": "Publishing the SSH gateway",
    "step": "gateway_ready",
    "steps": [
      {
        "key": "requested",
        "label": "Requested",
        "state": "done"
      },
      {
        "key": "gateway_ready",
        "label": "SSH gateway ready",
        "state": "current"
      },
      {
        "key": "ready",
        "label": "Ready",
        "state": "todo"
      }
    ],
    "subject": null,
    "summary": "New cluster",
    "to_version": null,
    "type": "cluster_create",
    "type_label": "New cluster"
  },
  "sites": []
}
```

### 202 The create was accepted and its first step is still being confirmed. The body is the same as for `201`, with the operation's `status` `pending`.

```json
{
  "cluster": {
    "actions": {
      "create_environment": {
        "available": false,
        "reason": "This cluster is still being created"
      },
      "create_site": {
        "available": false,
        "reason": "This cluster is still being created"
      },
      "delete": {
        "available": false,
        "reason": "This cluster is still being created"
      },
      "upgrade_package": {
        "available": false,
        "downgrade": false,
        "reason": "This cluster is still being created"
      }
    },
    "allowance": {
      "cpu_millicores": 4000,
      "disk_bytes": 214748364800,
      "memory_bytes": 17179869184
    },
    "capacity": {
      "basis": "estimate",
      "cpu": {
        "capacity_millicores": 4000,
        "level": "ok",
        "percent": 0,
        "used_p95_millicores": 0
      },
      "evaluated_at": null,
      "level": "ok",
      "memory": {
        "capacity_bytes": 17179869184,
        "level": "ok",
        "percent": 0,
        "used_p95_bytes": 0
      },
      "package": {
        "cores": 4,
        "key": "xsmall",
        "memory_bytes": 17179869184,
        "name": "Extra small"
      },
      "sites": {
        "count": 0,
        "environments": 0
      },
      "storage": {
        "capacity_bytes": 214748364800,
        "level": "ok",
        "percent": 0,
        "provisioned_bytes": 0
      }
    },
    "created_at": "2026-11-14T10:00:00Z",
    "created_by": {
      "id": 2041,
      "name": "Eleanor Finch"
    },
    "environments": 0,
    "id": 1018,
    "kind": "customer",
    "label": "Northwind UK 2",
    "location": {
      "arch": "arm64",
      "label": "London (europe-west2)"
    },
    "logs": null,
    "name": "Northwind UK 2",
    "operation": {
      "id": 5130,
      "scope": "cluster",
      "status": "pending",
      "status_label": "Saving change",
      "summary": "New cluster",
      "to_version": null,
      "type": "cluster_create",
      "type_label": "New cluster"
    },
    "package": {
      "cores": 4,
      "key": "xsmall",
      "name": "Extra small"
    },
    "pending_changes": {
      "count": 0,
      "window_starts_at": null
    },
    "ready_at": null,
    "region": {
      "key": "uk",
      "label": "United Kingdom",
      "place": "London (europe-west2)"
    },
    "reserved": {
      "cpu_limit_millicores": 0,
      "cpu_request_millicores": 0,
      "disk_bytes": 0,
      "memory_limit_bytes": 0,
      "memory_request_bytes": 0
    },
    "sites": {
      "applying": 0,
      "degraded": 0,
      "down": 0,
      "environments": 0,
      "healthy": 0,
      "live": 0,
      "preview": 0,
      "total": 0,
      "unknown": 0
    },
    "slug": "northwind-uk-2",
    "snapshots": {
      "frequency": "6h",
      "over_quota": false,
      "pruned_recently": false,
      "quota_bytes": 429496729600,
      "retention_days": 30,
      "usage_bytes": null
    },
    "ssh_host": "ssh-northwind-uk-2.example.net",
    "state": "creating",
    "state_label": "Creating",
    "state_reason": null,
    "synced": {
      "inventory_at": "2026-11-14T10:00:00Z",
      "live_at": null,
      "usage_at": null
    },
    "usage": {
      "cpu_millicores": null,
      "disk_used_bytes": null,
      "memory_bytes": null,
      "observed_at": null,
      "source": null
    }
  },
  "operation": {
    "applied_at": null,
    "can_retry": false,
    "cluster": {
      "id": 1018,
      "name": "Northwind UK 2"
    },
    "committed_at": null,
    "completed_at": null,
    "created_at": "2026-11-14T10:00:00Z",
    "environment": null,
    "error": null,
    "failure_reason": null,
    "from_version": null,
    "hot": false,
    "id": 5130,
    "install": null,
    "label": "Requested",
    "notes": [],
    "parent_operation_id": null,
    "requested_by": {
      "id": 2041,
      "name": "Eleanor Finch"
    },
    "result": null,
    "result_state": "none",
    "retried_by_operation_id": null,
    "retries_operation_id": null,
    "retry_requires": null,
    "scope": "cluster",
    "site": null,
    "status": "pending",
    "status_label": "Preparing the cluster",
    "step": "requested",
    "steps": [
      {
        "key": "requested",
        "label": "Requested",
        "state": "current"
      },
      {
        "key": "gateway_ready",
        "label": "SSH gateway ready",
        "state": "todo"
      },
      {
        "key": "ready",
        "label": "Ready",
        "state": "todo"
      }
    ],
    "subject": null,
    "summary": "New cluster",
    "to_version": null,
    "type": "cluster_create",
    "type_label": "New cluster"
  },
  "sites": []
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the scope (`scope_required`, with the `scope` to use), your company requires two-factor authentication and you have not set it up, or your account has no company that can use Managed Clusters, for example because the company was closed (`company_unavailable` or `company_not_enabled`, whichever the route checks first). For Managed Clusters routes; any other route uses `ForbiddenScopeOrTwoFactor`.

```json
{
  "code": "company_unavailable",
  "message": "Your company is unavailable.",
  "reason": "company_unavailable"
}
```

### 404 The feature is not on for your company.

```json
{
  "code": "feature_off",
  "message": "Not found.",
  "reason": "feature_off"
}
```

### 409 Nothing was created. `reason` says why: `region_unavailable` (the region is not open or has no room for the package; it may carry a `cause`), `compute_blocked` (the region cannot take the CoreCluster now; the answer adds `tier` and `dimension`), `cluster_busy` (another CoreCluster is being created for your company, or the package or region changed while the request was checked) or `duplicate` (a first site's domain was taken while the request was checked).

```json
{
  "code": "cluster_busy",
  "message": "The package or the region changed while the request was checked. Check it and try again.",
  "reason": "cluster_busy"
}
```

### 422 A field is missing or wrong (`invalid`). `field` names it; a first site's field is named by its row, such as `sites.0.tier`. A field that is not listed in the request schema is refused the same way. A name whose address an earlier CoreCluster had, a deleted one included, is not available. A first site's Node.js choice has reasons of its own, with the row's field in `errors` and no `field`: `runtime_not_adopted` (a new site cannot choose a version here yet), `node_major_unavailable`, `node_platform_minimum` and `node_major_existing_only` (the version is not offered to a new site of this platform), `ack_required` (the version is past its end of life; `required` lists what `node_acknowledge` must carry) and `feature_off` (choosing a version is switched off).

```json
{
  "code": "invalid",
  "errors": {
    "sites.0.tier": [
      "Choose a size"
    ]
  },
  "field": "sites.0.tier",
  "message": "Choose a size",
  "reason": "invalid"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

### 502 The platform could not be checked or written to, so nothing was created. Try again in a minute.

```json
{
  "message": "The platform could not be checked just now. Try again in a minute."
}
```

### 503 The region cannot take a new CoreCluster at the moment (`temporarily_unavailable`). Nothing was created. Try again later.

```json
{
  "code": "temporarily_unavailable",
  "message": "This region is not ready",
  "reason": "temporarily_unavailable"
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 404 | `feature_off` | This feature is not on for your organisation yet. |
| 409 | `cluster_busy` | Another change to the cluster is running. Wait for it to finish, then try again. |
| 409 | `compute_blocked` | There is no server capacity for this size at the moment. Choose another size, or contact support. |
| 409 | `duplicate` | The same thing already exists here. Use the existing one, or choose another name or value. |
| 409 | `region_unavailable` | The region has no room for this at the moment. Choose another region, or try again later. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 422 | `runtime_not_adopted` | A Node.js version cannot be chosen for a new site here yet. Leave it out to use the default. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 502 |  | Read the message; it says what happened. |
| 503 | `temporarily_unavailable` | The Control Panel could not answer just now. Nothing was started; try again shortly. |

## The same task elsewhere

- Guide: [Create a cluster](https://docs.corefinity.com/guides/corecluster/create-a-cluster.md)
- MCP tool: [`corecluster_create`](https://docs.corefinity.com/mcp/tools/corecluster_create.md)
