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

# Domains API

> Custom domain onboarding, DNS/SSL verification, domain settings, and custom email-domain lifecycle

# Domains API

Domains APIs manage redirect domains and optional custom email sending domains.

## Endpoint matrix

| Method   | Path                        | Purpose                                        |
| -------- | --------------------------- | ---------------------------------------------- |
| `GET`    | `/domains`                  | List workspace domains                         |
| `GET`    | `/domains/:id`              | Get one domain                                 |
| `POST`   | `/domains`                  | Create custom domain                           |
| `POST`   | `/domains/:id/verify`       | Re-check DNS/SSL verification                  |
| `PATCH`  | `/domains/:id`              | Update domain behavior/settings                |
| `DELETE` | `/domains/:id`              | Remove domain and connected provider resources |
| `POST`   | `/domains/:id/email/setup`  | Create email domain in provider                |
| `POST`   | `/domains/:id/email/verify` | Verify email DNS records                       |
| `GET`    | `/domains/:id/email/status` | Fetch current email-domain status              |
| `DELETE` | `/domains/:id/email`        | Remove custom email domain setup               |
| `POST`   | `/domains/:id/email/test`   | Send verification test email                   |

## Domain creation + DNS model

Create flow validates:

* plan domain limits
* global domain uniqueness
* normalized/punycode domain values

Generated DNS instructions include CNAME routing toward Linquid proxy infrastructure. Verification checks Cloudflare-managed custom hostname and SSL state.

## Verification/status model

Operational states include:

* verification status (`verified` boolean)
* SSL status (`pending`, `active`, `failed`)
* provider-side status hints (for diagnostics)

`POST /domains/:id/verify` is safe to re-run and used as the canonical refresh action after DNS changes.

## Domain settings update (`PATCH /domains/:id`)

Supports settings such as:

* not-found redirect URL
* expired-link redirect URL
* Apple App Site Association (AASA) JSON
* Android asset links JSON

JSON fields are validated before persistence.

## Custom email-domain flow

Email-domain setup has stricter gating:

* requires configured email provider credentials
* requires verified redirect domain first
* currently restricted to Enterprise entitlement

After setup, use `.../email/verify` until status reaches `verified`, then use `.../email/test` to validate sender path.

## Authorization and permissions

* `domains:read` for reads
* `domains:manage` for create/update/delete/verify operations

## Typical failures

* `403 LIMIT_EXCEEDED` when plan domain quota is reached
* `400 DOMAIN_EXISTS` when domain is already registered
* `400 DOMAIN_NOT_VERIFIED` before email setup
* `403 PLAN_REQUIRED` for non-Enterprise email-domain setup
* `500 CF_ERROR`/`RESEND_ERROR` for provider operation failures

Related docs:

* `/user-guides/manual/workspace/workspace-settings-and-governance-reference`
* `/user-guides/manual/data/data-retention-and-lifecycle`