---
title: "Brand domains"
description: "Connect, check and remove a brand's own domain, and what each plan allows."
---

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

# Brand domains

A brand can have its own domain, such as `brand.example.com`. These calls need the `brands:domains` scope, and the token's creator must be an owner or admin of the workspace named in `X-Workspace-Key`. A brand has at most one domain, as in the app.

## Connect a domain

`PUT /brands/{brand}/domain` connects a domain, or replaces the brand's current one.

```bash
curl -X PUT -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"domain": "brand.example.com"}' \
  https://tarkle.com/api/v1/brands/acme-bank/domain
```

`domain` is a plain hostname. A web address, a path, a port or spaces answer `400 invalid_request`. Send an international name as punycode (`xn--...`).

The answer (`200`) holds:

- `status`: `ownership_verification_required`, `dns_configuration_required`, `certificate_pending` or `active`.
- `dns_records`: the records to add at your DNS host, each with `type`, `host`, `value`, `purpose` and `status`. Verification records come first, then routing.
- `id`, `brand_id`, `domain`, `certificate_status`, `last_checked_at` and `created_at`.

Sending the same domain again is safe. When you replace a domain, the new one is attached first and the old one is detached afterwards.

## Check the setup

`GET /brands/{brand}/domain` re-checks the domain with the hosting provider, stores what it finds and returns the same fields. Call it after you add the DNS records, until `status` is `active`. `provider_unavailable` is `true` when the provider could not be reached; the stored values are returned. `404 not_found` means the brand has no domain.

## Remove a domain

`DELETE /brands/{brand}/domain` detaches the domain from hosting and from the brand. The brand page stays. The answer is `{"deleted": true, "domain": "..."}`.

## Plans

The API follows the plan rules of the app. Free workspaces have no brand domain, so a connect call answers `403 forbidden` with `details.entitlement` set to `BRAND_PAGE_DOMAIN_LIMIT`. Pro and Agency have no limit. A workspace that is at its limit cannot replace a domain either.

## Errors

| Answer | Meaning |
| --- | --- |
| `409 domain_taken` | Another brand or another part of Tarkle uses the domain, or it is attached elsewhere. `details.reason` says which. |
| `422 domain_rejected` | The hosting provider refused the domain. |
| `503 unavailable` | The hosting provider is unavailable. Nothing was saved. Try again. |
| `502 domain_provider_error` | On remove: the provider could not detach the domain. The brand keeps it. |

Connecting and removing a domain are recorded in the Activity as `brand.domain_set` and `brand.domain_removed`, with the token's name and the domain.

Source: https://tarkle.com/docs/api/brands/domain/index.mdx