---
title: "Create a site in a CoreCluster"
url: https://docs.corefinity.com/api/reference/sites/create-cluster-site
type: endpoint
last_updated: 2026-11-13
feature: site-create
related:
  - https://docs.corefinity.com/guides/sites/create-and-manage/create-a-site.md
  - https://docs.corefinity.com/mcp/tools/corestack_in_corecluster_site_create.md
---
# Create a site in a CoreCluster

Creates a site in one of your CoreClusters, sized by `tier`, with no further environments; add those afterwards.
The answer is `201` when the create has started, or `202` while it waits for room; follow `operation.id` until it completes.

```http
POST /api/corestack/clusters/{cluster}/sites
```

- Scope: `write`
- Also needs `exec` when To be shown the generated HTTP authentication password in `credentials`, when the request asks for `http_auth`. Without it the create still succeeds and the password is null
- Two-factor: required on your account (all)
- Rate limit: 100 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.

## Path parameters

- `cluster` (integer, required): The id of a CoreCluster. Digits only.

## Body

- `acknowledge` (array of strings): What the chosen line asks you to acknowledge.
- `app_version` (string): The `key` of a line from the application versions list. Left out, the recommended line. Taken only while application versions are on for your company.
- `content` (string, required): `fresh` installs the platform; `empty` creates a site for your own code. One of `fresh`, `empty`.
- `domain` (string, required): The site's public domain in lower case, without `www`. You choose `www` or not when you attach the domain.
- `edition` (string): The edition of the line, such as `open_source`. Taken only while application versions are on for your company.
- `fresh` (object): Settings of a fresh install, read only when `content` is `fresh`. All are optional; a field that is not listed here is refused.
  - `admin_email` (string): The admin's email address, 190 characters at most, with no space, quote, `<`, `>` or backslash. It is saved in lower case. Left out, the platform's default, else your own address.
  - `admin_username` (string): 3 to 32 characters: a lower-case letter first, then lower-case letters, digits or `_`. `admin` is refused. Left out, the platform's default, else `siteadmin`.
  - `currency` (string): Taken only for a platform whose fresh install has a currency, and then one of the currencies it offers; refused as a field that is not part of the request for every other platform.
  - `locale` (string): One of the locales the platform installs, `en_GB` or `en_US` unless the platform offers its own list. Left out, the platform's default, else `en_GB`.
  - `site_title` (string): The site's title, 100 characters at most, with no control characters (a line break is one). Left out, or blank (a blank title is read as left out), the platform's default, else the domain.
- `http_auth` (boolean): Create the site behind HTTP authentication, with one whole-site rule and a generated login. Defaults to `false`.
- `mariadb_version` (string): Left out, the platform's default.
- `node_acknowledge` (array of strings): `["eol"]` to choose a major that no longer receives fixes; otherwise leave it out or send `[]`.
- `node_major` (integer): The Node.js major version for the site, as a whole number (`22`, never `"22"`), and one of the majors offered to new sites of the platform. Left out, the default major. Refused while choosing a Node.js version is switched off, and where a new site cannot take one yet.
- `php_version` (string): Such as `8.3`. Left out, the platform's default.
- `platform` (string, required): `wordpress`, `magento2`, `laravel`, `shopware`, or another platform offered to your company.
- `search` (boolean): Shopware only: whether search is on.
- `tier` (string, required): The size, such as `S`, `M` or `L`. Required in a CoreCluster; refused on a Corefinity platform, where the package sets the size.
- `varnish` (object): Magento 2 only, where offered: start the site with Varnish.
  - `enabled` (boolean, required)
  - `version` (string)

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/corestack/clusters/1017/sites \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "empty",
    "domain": "journal.harbourandfinch.example.com",
    "php_version": "8.3",
    "platform": "wordpress",
    "tier": "S"
  }'
```

### PHP

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

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->post('https://manage.corefinity.com/api/corestack/clusters/1017/sites', [
        'content' => 'empty',
        'domain' => 'journal.harbourandfinch.example.com',
        'php_version' => '8.3',
        'platform' => 'wordpress',
        'tier' => 'S',
    ]);

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

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/clusters/1017/sites', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: 'empty',
    domain: 'journal.harbourandfinch.example.com',
    php_version: '8.3',
    platform: 'wordpress',
    tier: 'S',
  }),
});

// 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/1017/sites",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "content": "empty",
        "domain": "journal.harbourandfinch.example.com",
        "php_version": "8.3",
        "platform": "wordpress",
        "tier": "S",
    },
)

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

## Responses

### 201 The create has started.

```json
{
  "operation": {
    "applied_at": null,
    "can_retry": false,
    "cluster": {
      "id": 1017,
      "name": "Northwind UK 1"
    },
    "committed_at": "2026-11-19T09:00:02+00:00",
    "completed_at": null,
    "created_at": "2026-11-19T09:00:00+00:00",
    "environment": {
      "env_id": "rs-northwind-journal-harbourandfinch-example-com",
      "hostname": "journal-harbourandfinch-example-com.northwind.cfstack.example.net",
      "id": 1051,
      "name": "Production",
      "role": "production",
      "role_label": "Production",
      "slug": "production"
    },
    "error": null,
    "failure_reason": null,
    "from_version": null,
    "hot": false,
    "id": 5122,
    "notes": [],
    "parent_operation_id": null,
    "requested_by": {
      "id": 2012,
      "name": "Daniel Reyes"
    },
    "result": null,
    "result_state": "none",
    "retried_by_operation_id": null,
    "retries_operation_id": null,
    "retry_requires": null,
    "scope": "site",
    "site": {
      "domain": "journal.harbourandfinch.example.com",
      "id": 1051
    },
    "status": "committed",
    "status_label": "Waiting for the platform",
    "steps": [
      {
        "key": "reserved",
        "label": "Port and address reserved",
        "state": "done"
      },
      {
        "key": "committed",
        "label": "Saved to the platform",
        "state": "done"
      },
      {
        "key": "picked_up",
        "label": "Picked up by the platform",
        "state": "current"
      },
      {
        "key": "starting",
        "label": "Site started",
        "state": "todo"
      },
      {
        "key": "ready",
        "label": "Ready",
        "state": "todo"
      }
    ],
    "subject": null,
    "summary": "New site journal.harbourandfinch.example.com",
    "to_version": null,
    "type": "provision",
    "type_label": "New site"
  },
  "site": {
    "access_summary": {
      "apply_state": "applied",
      "company_keys": 0,
      "keys": 0,
      "users": 1
    },
    "actions": {
      "attach_domain": {
        "available": true,
        "reason": null
      },
      "delete": {
        "available": true,
        "reason": null
      },
      "restore_deleted": {
        "available": false,
        "reason": "This site is not deleted"
      }
    },
    "adoption": "adopted",
    "cloudflare": {
      "connected": false,
      "zone": null
    },
    "cluster": {
      "id": 1017,
      "name": "Northwind UK 1"
    },
    "commands": [],
    "compute_family": "general",
    "counts": {
      "crons": 1
    },
    "crons_enabled": false,
    "database": {
      "host": "127.0.0.1",
      "name": "wordpress",
      "password_revealable": true,
      "port": 3306,
      "username": "application",
      "via": "SSH tunnel"
    },
    "deleted": null,
    "deploy_mode": "manual",
    "deploy_mode_label": "Manual",
    "deployments_summary": {
      "last": null,
      "mode": "manual"
    },
    "domain": "journal.harbourandfinch.example.com",
    "domains_summary": {
      "aliases": 0,
      "dns": "unknown",
      "noindex": false,
      "primary": "journal.harbourandfinch.example.com",
      "tls": "none",
      "www": null
    },
    "email_summary": {
      "sending_domain": null,
      "state": "preview"
    },
    "environment": {
      "env_id": "rs-northwind-journal-harbourandfinch-example-com",
      "hostname": "journal-harbourandfinch-example-com.northwind.cfstack.example.net",
      "id": 1051,
      "name": "Production",
      "role": "production",
      "role_label": "Production",
      "slug": "production"
    },
    "environments": [
      {
        "env_id": "rs-northwind-journal-harbourandfinch-example-com",
        "hostname": "journal-harbourandfinch-example-com.northwind.cfstack.example.net",
        "id": 1051,
        "name": "Production",
        "role": "production",
        "role_label": "Production",
        "slug": "production"
      }
    ],
    "health": "applying",
    "hosting": {
      "cluster_kind": "customer",
      "label": "CoreCluster Northwind UK 1"
    },
    "http_auth_summary": {
      "apply_state": "applied",
      "enabled": false,
      "rules": 0,
      "users": 0
    },
    "id": 1051,
    "kind": "corestack",
    "lifecycle": "provisioning",
    "limits": {
      "cpu_millicores": 2000,
      "disk_bytes": 10737418240,
      "memory_bytes": 4294967296
    },
    "logs": null,
    "maintenance": {
      "bypass_corefinity": 1,
      "bypass_ips": [],
      "enabled": false,
      "since": null
    },
    "mariadb": {
      "version": "11.8"
    },
    "mode": "staging",
    "mode_label": "No domain",
    "operation": null,
    "operations": [],
    "package": null,
    "pending_changes": {
      "count": 0,
      "outcome_at": null,
      "state": null,
      "window_starts_at": null
    },
    "php": {
      "version": "8.3"
    },
    "platform": {
      "key": "wordpress",
      "label": "WordPress"
    },
    "platform_url": "https://journal-harbourandfinch-example-com.northwind.cfstack.example.net",
    "preview": {
      "label": "Platform address",
      "protected": false,
      "url": "https://journal-harbourandfinch-example-com.northwind.cfstack.example.net"
    },
    "primary_url": null,
    "production_hosts": [],
    "provisioning": null,
    "removed": false,
    "restore": null,
    "settings": {
      "auto_deploy": false,
      "http_auth_enabled": false,
      "scheduled_snapshots": true
    },
    "site": {
      "domain": "journal.harbourandfinch.example.com",
      "id": 1051
    },
    "site_id": "rs-northwind-journal-harbourandfinch-example-com",
    "snapshots": {
      "count": 0,
      "effective_frequency": "off",
      "effective_label": "Off",
      "latest": null,
      "latest_ready_at": null,
      "next_scheduled_at": null,
      "overridden": false,
      "stored_gb": 0
    },
    "ssh": {
      "command": "ssh -p 20031 web@ssh-northwind.example.net",
      "host": "ssh-northwind.example.net",
      "key_management": false,
      "keys": [],
      "port": 20031,
      "sftp_command": "sftp -P 20031 web@ssh-northwind.example.net",
      "tunnel_command": "ssh -N -L 3306:127.0.0.1:3306 -p 20031 web@ssh-northwind.example.net",
      "user": "web",
      "users": 1
    },
    "tier": "S",
    "uat_size": null,
    "usage": {
      "cpu_millicores": 180,
      "disk_used_bytes": 2147483648,
      "memory_bytes": 912261120,
      "observed_at": "2026-11-24T09:10:00Z",
      "source": "live"
    }
  }
}
```

### 202 The create is accepted and has not started yet.

```json
{
  "operation": {
    "applied_at": null,
    "can_retry": false,
    "cluster": {
      "id": 1017,
      "name": "Northwind UK 1"
    },
    "committed_at": "2026-11-19T09:00:02+00:00",
    "completed_at": null,
    "created_at": "2026-11-19T09:00:00+00:00",
    "environment": {
      "env_id": "rs-northwind-journal-harbourandfinch-example-com",
      "hostname": "journal-harbourandfinch-example-com.northwind.cfstack.example.net",
      "id": 1051,
      "name": "Production",
      "role": "production",
      "role_label": "Production",
      "slug": "production"
    },
    "error": null,
    "failure_reason": null,
    "from_version": null,
    "hot": false,
    "id": 5122,
    "notes": [],
    "parent_operation_id": null,
    "requested_by": {
      "id": 2012,
      "name": "Daniel Reyes"
    },
    "result": null,
    "result_state": "none",
    "retried_by_operation_id": null,
    "retries_operation_id": null,
    "retry_requires": null,
    "scope": "site",
    "site": {
      "domain": "journal.harbourandfinch.example.com",
      "id": 1051
    },
    "status": "pending",
    "status_label": "Saving change",
    "steps": [
      {
        "key": "reserved",
        "label": "Port and address reserved",
        "state": "done"
      },
      {
        "key": "committed",
        "label": "Saved to the platform",
        "state": "done"
      },
      {
        "key": "picked_up",
        "label": "Picked up by the platform",
        "state": "current"
      },
      {
        "key": "starting",
        "label": "Site started",
        "state": "todo"
      },
      {
        "key": "ready",
        "label": "Ready",
        "state": "todo"
      }
    ],
    "subject": null,
    "summary": "New site journal.harbourandfinch.example.com",
    "to_version": null,
    "type": "provision",
    "type_label": "New site"
  },
  "site": {
    "access_summary": {
      "apply_state": "applied",
      "company_keys": 0,
      "keys": 0,
      "users": 1
    },
    "actions": {
      "attach_domain": {
        "available": true,
        "reason": null
      },
      "delete": {
        "available": true,
        "reason": null
      },
      "restore_deleted": {
        "available": false,
        "reason": "This site is not deleted"
      }
    },
    "adoption": "adopted",
    "cloudflare": {
      "connected": false,
      "zone": null
    },
    "cluster": {
      "id": 1017,
      "name": "Northwind UK 1"
    },
    "commands": [],
    "compute_family": "general",
    "counts": {
      "crons": 1
    },
    "crons_enabled": false,
    "database": {
      "host": "127.0.0.1",
      "name": "wordpress",
      "password_revealable": true,
      "port": 3306,
      "username": "application",
      "via": "SSH tunnel"
    },
    "deleted": null,
    "deploy_mode": "manual",
    "deploy_mode_label": "Manual",
    "deployments_summary": {
      "last": null,
      "mode": "manual"
    },
    "domain": "journal.harbourandfinch.example.com",
    "domains_summary": {
      "aliases": 0,
      "dns": "unknown",
      "noindex": false,
      "primary": "journal.harbourandfinch.example.com",
      "tls": "none",
      "www": null
    },
    "email_summary": {
      "sending_domain": null,
      "state": "preview"
    },
    "environment": {
      "env_id": "rs-northwind-journal-harbourandfinch-example-com",
      "hostname": "journal-harbourandfinch-example-com.northwind.cfstack.example.net",
      "id": 1051,
      "name": "Production",
      "role": "production",
      "role_label": "Production",
      "slug": "production"
    },
    "environments": [
      {
        "env_id": "rs-northwind-journal-harbourandfinch-example-com",
        "hostname": "journal-harbourandfinch-example-com.northwind.cfstack.example.net",
        "id": 1051,
        "name": "Production",
        "role": "production",
        "role_label": "Production",
        "slug": "production"
      }
    ],
    "health": "applying",
    "hosting": {
      "cluster_kind": "customer",
      "label": "CoreCluster Northwind UK 1"
    },
    "http_auth_summary": {
      "apply_state": "applied",
      "enabled": false,
      "rules": 0,
      "users": 0
    },
    "id": 1051,
    "kind": "corestack",
    "lifecycle": "provisioning",
    "limits": {
      "cpu_millicores": 2000,
      "disk_bytes": 10737418240,
      "memory_bytes": 4294967296
    },
    "logs": null,
    "maintenance": {
      "bypass_corefinity": 1,
      "bypass_ips": [],
      "enabled": false,
      "since": null
    },
    "mariadb": {
      "version": "11.8"
    },
    "mode": "staging",
    "mode_label": "No domain",
    "operation": null,
    "operations": [],
    "package": null,
    "pending_changes": {
      "count": 0,
      "outcome_at": null,
      "state": null,
      "window_starts_at": null
    },
    "php": {
      "version": "8.3"
    },
    "platform": {
      "key": "wordpress",
      "label": "WordPress"
    },
    "platform_url": "https://journal-harbourandfinch-example-com.northwind.cfstack.example.net",
    "preview": {
      "label": "Platform address",
      "protected": false,
      "url": "https://journal-harbourandfinch-example-com.northwind.cfstack.example.net"
    },
    "primary_url": null,
    "production_hosts": [],
    "provisioning": null,
    "removed": false,
    "restore": null,
    "settings": {
      "auto_deploy": false,
      "http_auth_enabled": false,
      "scheduled_snapshots": true
    },
    "site": {
      "domain": "journal.harbourandfinch.example.com",
      "id": 1051
    },
    "site_id": "rs-northwind-journal-harbourandfinch-example-com",
    "snapshots": {
      "count": 0,
      "effective_frequency": "off",
      "effective_label": "Off",
      "latest": null,
      "latest_ready_at": null,
      "next_scheduled_at": null,
      "overridden": false,
      "stored_gb": 0
    },
    "ssh": {
      "command": "ssh -p 20031 web@ssh-northwind.example.net",
      "host": "ssh-northwind.example.net",
      "key_management": false,
      "keys": [],
      "port": 20031,
      "sftp_command": "sftp -P 20031 web@ssh-northwind.example.net",
      "tunnel_command": "ssh -N -L 3306:127.0.0.1:3306 -p 20031 web@ssh-northwind.example.net",
      "user": "web",
      "users": 1
    },
    "tier": "S",
    "uat_size": null,
    "usage": {
      "cpu_millicores": 180,
      "disk_used_bytes": 2147483648,
      "memory_bytes": 912261120,
      "observed_at": "2026-11-24T09:10:00Z",
      "source": "live"
    }
  }
}
```

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

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

### 403 The token lacks the `write` scope (`scope_required`), two-factor authentication is required and not set up (`two_factor_required`), your account has no company that can use Managed Clusters (`company_not_enabled`), you may not create sites for this company (`forbidden`), or you may not use its billing (`billing_forbidden`).

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

### 404 The id does not exist or is something you cannot see, or the feature is not on for your company (`feature_off`).

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

### 409 The create conflicts with the state of the CoreCluster or the site, and nothing was created. `reason` says how: `duplicate` (the domain is already a site in the CoreCluster, or is hosted somewhere else on the platform), `cleaning_up` (a site of this domain is still being removed; try again in a minute), `placement` (the CoreCluster cannot take a site of this platform yet) or `platform_cluster` (the id is a Corefinity platform, where sites are created with a package). Other reasons mean the CoreCluster cannot take the site at the moment, and `message` says what to do: `capacity_blocked`, `compute_blocked`, `storage_blocked`, `cluster_not_ready`, `package_restricted`, `not_v3`, `not_configured` and `stale`.

```json
{
  "code": "cleaning_up",
  "message": "This site is being cleaned up. Try again in a minute.",
  "reason": "cleaning_up"
}
```

### 422 A field is missing or wrong (`invalid`), or a rule of the create refuses it with a reason of its own, naming the field. `billing_account_id` and `trial` are never part of an API create.

```json
{
  "code": "invalid",
  "errors": {
    "fresh.admin_username": [
      "Admin username: 3–32 characters, a letter first, then letters, digits or `_`"
    ]
  },
  "field": "fresh.admin_username",
  "message": "Admin username: 3–32 characters, a letter first, then letters, digits or `_`",
  "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 read to check the new site, or to prepare it, so nothing was created. Try again in a minute. The body carries a `message` and no `reason`.

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

### 503 The create could not be judged, so nothing was created; try again in a few minutes. `catalogue_unavailable`: the list of application versions cannot be read. `commerce_check_unavailable`: an Adobe Commerce create, whose Marketplace keys could not be checked with the Magento repository.

```json
{
  "code": "catalogue_unavailable",
  "message": "Application versions are unavailable right now. Try again in a few minutes.",
  "reason": "catalogue_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 | `forbidden` | The person is not allowed to do this. |
| 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 | `cleaning_up` | The site, the environment or its last restore is still being cleaned up or removed. Try again in a few minutes. |
| 409 | `duplicate` | The same thing already exists here. Use the existing one, or choose another name or value. |
| 409 | `placement` | The CoreCluster cannot take a site of this platform yet. Choose another placement, or ask Corefinity support. |
| 409 | `platform_cluster` | The cluster is the CoreStack platform, which has no settings or sites of its own to change this way. Change or create the site itself instead. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 502 |  | Read the message; it says what happened. |
| 503 | `catalogue_unavailable` | Application versions are unavailable right now. Try again in a few minutes. |
| 503 | `commerce_check_unavailable` | We could not check your Magento Marketplace keys. Try again in a few minutes. |

## The same task elsewhere

- Guide: [Create a site](https://docs.corefinity.com/guides/sites/create-and-manage/create-a-site.md)
- MCP tool: [`corestack_in_corecluster_site_create`](https://docs.corefinity.com/mcp/tools/corestack_in_corecluster_site_create.md)
