> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Custom Domain

> Integrate your website with a custom domain. Has a rate limit of 10 changes every 5 minutes and 50 every 24 hours.

**Is necessary to have at least the [Standard plan](https://squarecloud.app/en/pricing) to use this route.**

The same account may attach one domain to multiple applications (load balancing): up to 2 applications on Standard, 5 on Pro, and 10 on Enterprise. See [List Load Balancers](/en/api-reference/endpoint/apps/network/load-balancers).

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

Replacing an existing custom domain releases the previous hostname at the edge before attaching the new one, unless another application on the same account still points at it. The same validation runs whether attaching or removing (`custom: "@"`): on a workspace-shared application, the caller needs the workspace Administrator role or ownership.

A domain can only be claimed by one account at a time: attaching a hostname already held by another account returns `DOMAIN_ALREADY_EXISTS`. To see every hostname configured across your applications, see [List Domains](/en/api-reference/endpoint/apps/domains). Once attached, fetch the required validation records with [Get DNS Records](/en/api-reference/endpoint/apps/network/dns).

### Parameters

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  The ID of the application. You can find this in the URL of your application's dashboard.
</ParamField>

<ParamField body="custom" type="string" placeholder="example.com" required>
  The fully qualified domain to attach, or `@` to remove the application's current custom domain. It cannot be a Square Cloud domain (`squareweb.app`, `squarecloud.app`, ...).
</ParamField>

### Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful.. `success` if successful, `error` if not.
</ResponseField>

On failure, the response includes an error `code`:

| Status | Code                          | Meaning                                                                                  |
| ------ | ----------------------------- | ---------------------------------------------------------------------------------------- |
| `400`  | `INVALID_DOMAIN`              | The domain is not a valid fully qualified domain name.                                   |
| `400`  | `RESERVED_DOMAIN`             | Square Cloud domains cannot be used as a custom domain.                                  |
| `403`  | `UPGRADE_REQUIRED`            | The active plan does not include custom domains (Standard, Pro, or Enterprise required). |
| `403`  | `LOAD_BALANCER_LIMIT_REACHED` | The plan's limit of applications on this domain was reached.                             |
| `409`  | `DOMAIN_ALREADY_EXISTS`       | The domain is already attached to an application owned by another account.               |
| `502`  | `DNS_FAILED`                  | The domain attachment failed at the edge provider.                                       |

<ResponseExample>
  ```json theme={null}
  {
      "status": "success"
  }
  ```
</ResponseExample>