---
title: "Attach a domain to a site"
url: https://docs.corefinity.com/api/reference/domains/attach-site-domain
type: endpoint
last_updated: 2026-11-13
feature: domains
related:
  - https://docs.corefinity.com/guides/sites/go-live/add-a-domain.md
  - https://docs.corefinity.com/mcp/tools/corestack_site_attach_domain.md
---
# Attach a domain to a site

Takes the site or environment live on the hostnames you send. `confirm_domain` is the site's domain on
production, or the domain you are attaching on any other environment, typed exactly. With `point_dns` the DNS
records are written in your connected Cloudflare account before the attach starts, and each record written
counts against your company's 60 Cloudflare changes an hour.

```http
POST /api/corestack/sites/{site}/attach-domain
```

- Scope: `write`
- Two-factor: required on your account (all)
- Rate limit: 5 a minute; 60 an hour for each company
- Long-running: answers with an operation to poll
- Try it in the console: off. It overwrites data that cannot be brought back. Copy the request and run it yourself when you are sure.

## Path parameters

- `site` (integer, required): The id of a site row. A website's production site and each of its environments has its own id. Digits only.

## Body

- `canonical` (string, required)
- `confirm_domain` (string, required): On production, the site's domain. On another environment, the `canonical` you are attaching. Typed exactly.
- `confirm_replacements` (boolean): True to let `point_dns` replace DNS records that already exist. Defaults to `false`.
- `default_store` (object or any or null): The Magento store shown on the primary; omitted or null uses Magento's default.
- `hosts` (array of strings, required)
- `pending_dns` (boolean): True to attach before DNS points at the platform. Each hostname that does not point here yet needs the TXT record that proves it is yours; the refusal names the record and its value. Defaults to `false`.
- `point_dns` (boolean): True to point DNS through your connected Cloudflare account. Cannot be sent with `pending_dns`. Defaults to `false`.
- `proxied_records_checked` (boolean): True once you have checked in Cloudflare that the record of each hostname in the check's `proxied_unconfirmed` points at its `expected_ip`. Defaults to `false`.
- `serve` (object): For each extra domain on Shopware or Magento 2, redirect or storefront. Each Magento storefront needs an entry in stores. Each name to one of `redirect`, `storefront`.
- `stores` (object): Magento 2 only. Every key is a hostname in hosts with serve set to storefront; every such hostname needs an entry. One base_url address can be chosen per website or store view.
- `www` (string) One of `www`, `bare`.

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/corestack/sites/1042/attach-domain \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "canonical": "www.harbourandfinch.example.org",
    "confirm_domain": "harbourandfinch.example.org",
    "hosts": [
      "harbourandfinch.example.org",
      "www.harbourandfinch.example.org"
    ],
    "www": "www"
  }'
```

### PHP

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

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->post('https://manage.corefinity.com/api/corestack/sites/1042/attach-domain', [
        'canonical' => 'www.harbourandfinch.example.org',
        'confirm_domain' => 'harbourandfinch.example.org',
        'hosts' => [
            'harbourandfinch.example.org',
            'www.harbourandfinch.example.org',
        ],
        'www' => 'www',
    ]);

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

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/attach-domain', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    canonical: 'www.harbourandfinch.example.org',
    confirm_domain: 'harbourandfinch.example.org',
    hosts: [
      'harbourandfinch.example.org',
      'www.harbourandfinch.example.org',
    ],
    www: 'www',
  }),
});

// 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/sites/1042/attach-domain",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "canonical": "www.harbourandfinch.example.org",
        "confirm_domain": "harbourandfinch.example.org",
        "hosts": [
            "harbourandfinch.example.org",
            "www.harbourandfinch.example.org",
        ],
        "www": "www",
    },
)

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

## Responses

### 201 The attach started. Follow it by `id`.

```json
{
  "applied_at": null,
  "can_retry": false,
  "cluster": {
    "id": 1017,
    "name": "Northwind UK 1"
  },
  "committed_at": null,
  "completed_at": null,
  "created_at": "2026-11-06T09:16:41Z",
  "environment": {
    "env_id": "rs-harbourandfinch-example-org",
    "hostname": "example-org-example.cfstack.io",
    "id": 1042,
    "name": "Production",
    "role": "production",
    "role_label": "Production",
    "slug": "production"
  },
  "error": null,
  "failure_reason": null,
  "from_version": null,
  "hot": false,
  "id": 77142,
  "label": "Saved to the platform",
  "notes": [],
  "parent_operation_id": null,
  "requested_by": {
    "id": 5021,
    "name": "Eleanor Finch"
  },
  "result": null,
  "result_state": "none",
  "retried_by_operation_id": null,
  "retries_operation_id": null,
  "retry_requires": null,
  "scope": "site",
  "site": {
    "domain": "harbourandfinch.example.org",
    "id": 1042
  },
  "status": "pending",
  "status_label": "Saving change",
  "step": "committed",
  "steps": [
    {
      "key": "checks",
      "label": "DNS checked",
      "state": "done"
    },
    {
      "key": "committed",
      "label": "Saved to the platform",
      "state": "current"
    },
    {
      "key": "rolled",
      "label": "Change applied",
      "state": "todo"
    },
    {
      "key": "rewritten",
      "label": "Site URL updated",
      "state": "todo"
    },
    {
      "key": "certificate",
      "label": "Certificate issued",
      "state": "todo"
    },
    {
      "key": "live",
      "label": "Domain attached",
      "state": "todo"
    }
  ],
  "summary": "Attach www.harbourandfinch.example.org",
  "to_version": null,
  "type": "attach_domain",
  "type_label": "Attach domain"
}
```

### 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 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 `already_attached`, `busy`, `deleted`, `not_ready`, `not_running`, `not_available` (the platform cannot attach a domain yet), `platform_plugins_off`, `platform_plugins_applying`, `store_hosts`, `cli_move_build_raise` or `managed_elsewhere`. With `point_dns`, also `not_connected` (a hostname is not one your Cloudflare connection can write, or the connection is not working), `no_zone` (no hostname is in a connected zone, or Cloudflare is off for the site) and `busy` (another Cloudflare change for the company is running).

```json
{
  "code": "already_attached",
  "message": "This environment already has a domain. Change it in the Domains tab.",
  "reason": "already_attached"
}
```

### 422 `confirm_mismatch` (the domain was not typed exactly) or `invalid`: a field is missing or wrong, DNS does not point at the platform yet (`errors.hosts`), or a hostname behind Cloudflare needs `proxied_records_checked` (`errors.proxied_records_checked`). With `point_dns`, also `confirm_replacements` (existing DNS records would be replaced: send `confirm_replacements`; the check's `dns_plan` shows which) and `too_many` (more than 20 record changes in one go). Those two name the field in `errors` and carry no `field`.

```json
{
  "code": "confirm_mismatch",
  "errors": {
    "confirm_domain": [
      "Type the site's domain exactly to confirm"
    ]
  },
  "field": "confirm_domain",
  "message": "Type the site's domain exactly to confirm",
  "reason": "confirm_mismatch"
}
```

### 429 Too many requests (`rate_limited`): the endpoint's request limit, answered with `Retry-After` and `retry_after_seconds`, or, with `point_dns`, your company's 60 Cloudflare changes this hour, which the Control Panel and AI assistants spend too. That second refusal names no wait here: neither the header nor `retry_after_seconds` is sent. The hour is counted from each change, so try again later.

```json
{
  "code": "rate_limited",
  "message": "Too many Cloudflare changes this hour. Try again later.",
  "reason": "rate_limited"
}
```

### 500 Corefinity has switched commands on sites off for the moment, and this endpoint needs one to read the site. It answers a server error here, not `503 switched_off`. Nothing changed: try again later.

```json
{
  "message": "Server Error"
}
```

### 502 A check or a write outside the Control Panel could not run, or, with `point_dns`, some DNS records could not be written at Cloudflare. Nothing is undone: send the request again.

```json
{
  "message": "The DNS check could not run. Try again in a moment."
}
```

## 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 | `already_attached` | The environment already has a domain. Change it under Domains instead. |
| 409 | `not_connected` | The outside account this needs is not connected for your company. Connect it first; the message names it. |
| 422 | `confirm_mismatch` | Send the confirmation exactly as the field named in `field` asks for it. |
| 422 | `confirm_replacements` | Existing DNS records would be replaced. Confirm to continue. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 422 | `too_many` | Too many DNS changes in one go. Point the hosts in two steps. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 500 |  | Read the message; it says what happened. |
| 502 |  | Read the message; it says what happened. |

## The same task elsewhere

- Guide: [Add a domain](https://docs.corefinity.com/guides/sites/go-live/add-a-domain.md)
- MCP tool: [`corestack_site_attach_domain`](https://docs.corefinity.com/mcp/tools/corestack_site_attach_domain.md)
