---
title: "Add custom domain"
method: POST
path: "/api/apps/{app_id}/custom-domains"
---

# Add custom domain

`POST /api/apps/{app_id}/custom-domains`

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Attaches a domain you own to the app. Nothing serves on it until you link it with [Link custom domain](/api-reference/link-custom-domain).

Adding a domain and linking it are separate steps. DNS propagation happens outside Base44, so a linked domain can sit unverified for as long as its nameservers take. The domain's DNS has to point at Base44 before verification can pass, and the Base44 editor's domain settings show the records to set.

If a domain was released by another workspace, the call is rejected with a TXT record to publish. Publish it at the domain's DNS provider and send the same request again to prove you control the domain. A domain your own workspace released is re-added straight away.

Don't retry a request that timed out without checking first. If the domain was added, a second request is rejected as already attached, so look for it in [List custom domains](/api-reference/list-custom-domains) before you send the request again.

Adding domains is limited to 30 requests an hour per caller. Some workspaces have a different limit.

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time.</Warning>

## Path parameters

- `app_id` string, required — ID of the app the domain belongs to.

## Request body

- CreateDomainBody
  - `domain` string, required — The domain to add. A scheme, a trailing slash, and a leading `www.` are removed, and it's stored in lower case.

## Response `200`

The domain, attached to the app but not yet linked.

- CustomDomainResource — A custom domain attached to an app.
  - `id` string, required — ID of the domain. Pass it as `domain_id` to the other domain endpoints.
  - `domain` string, required — The domain name, normalized to lower case with any scheme, trailing slash and leading `www.` removed.
  - `app_id` string, required — ID of the app the domain serves.
  - `disabled` boolean, required — Whether Base44 has stopped serving the domain. A disabled domain stays attached to the app and keeps its DNS, and serves a placeholder page instead of the app.
  - `last_status_check` string, date-time, nullable — When [Get custom domain status](/api-reference/get-custom-domain-status) last ran for this domain, as a UTC timestamp in ISO 8601 format, or `null` if it never has.
  - `last_status_payload` CustomDomainStatusPayload — What the hosting provider last reported about the domain.
    - `verificationStatus` string, nullable — Whether the provider has verified the domain's DNS. Only `verified` means the domain serves the app, and anything else means it doesn't yet. Absent until [Get custom domain status](/api-reference/get-custom-domain-status) has run once.
  - `redirect_target_domain` string, nullable — The domain that visitors to this one are sent to with a 301 redirect. The value is `null` when this domain serves the app itself.
  - `provider_id` string, nullable — Names the registrar when the domain was bought through Base44's Wix flow. The value is `null` otherwise, which covers both a domain you own elsewhere and one bought through the Entri flow, so this isn't a purchased-versus-external signal.

## Other responses

- `400` — The domain is already attached to an app, contains a social media platform's name, or you have reached the limit of 350 custom domains. Base44's hosting provider can also reject it.
- `401` — Missing or invalid credentials.
- `402` — This workspace's plan doesn't include custom domains.
- `403` — You don't have access to this app, or you used a workspace API key. These endpoints take a personal API key.
- `404` — App not found.
- `409` — Another workspace released this domain. Publish the TXT record in `detail.verification` and retry.
- `422` — `domain` is missing or empty.
- `429` — Rate limit reached, either yours or Base44's hosting provider's. Retry later.

## Changes

- **2026-09-24** `eb89d67965ff` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/base44/apis/base44-app-management-api/changes/api/apps/:app_id/custom-domains/post.md)

---

[API](https://skmtc.dev/base44/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/base44/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/base44/apis/base44-app-management-api/revisions/5e69adeb8667?raw)