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

# Domains API

REST API endpoints for configuring and verifying custom domains on HolyDocs projects.

## Overview

The Domains API manages the single custom domain attached to a project. HolyDocs always keeps the default `*.holydocs.com` subdomain available; the custom domain is an additional hostname with DNS verification and Cloudflare-managed SSL.

**Base path:** `https://api.holydocs.com/api/v1/domains/:projectId`

Copy as context

## Get Domain Configuration

```bash
GET /api/v1/domains/:projectId
```

**cURL**

```bash
    curl "https://api.holydocs.com/api/v1/domains/$PROJECT_ID" \
      -H "Authorization: Bearer $HOLYDOCS_API_KEY"
    ```
  **CLI**

```bash
    holydocs api get /domains/$PROJECT_ID
    ```
  **SDK**

```ts
    import { HolyDocs } from '@holydocs/sdk';

    const client = new HolyDocs({
      apiKey: process.env.HOLYDOCS_API_KEY!,
      projectId: process.env.HOLYDOCS_PROJECT!,
    });

    const domain = await client.domains.get();
    ```

### Response

```json
{
  "data": {
    "subdomain": "my-project.holydocs.com",
    "customDomain": "docs.mycompany.com",
    "cnameTarget": "proxy.holydocs.com",
    "analysis": {
      "hostname": "docs.mycompany.com",
      "cnameTarget": "proxy.holydocs.com",
      "currentCname": "proxy.holydocs.com",
      "cnameMatchesTarget": true,
      "hostnameId": "cf_hostname_123",
      "hostnameStatus": "active",
      "sslStatus": "active",
      "hostnameReady": true,
      "ownershipVerification": null
    }
  }
}
```

### Response Fields

| Field | Type | Description |
|---|---|---|
| `subdomain` | string | Default HolyDocs subdomain |
| `customDomain` | string \| null | Configured custom domain, if any |
| `cnameTarget` | string | DNS target to point your CNAME or flattened ALIAS at |
| `analysis` | object \| null | Current DNS and hostname-registration state |

### `analysis` Fields

| Field | Type | Description |
|---|---|---|
| `hostname` | string | The custom hostname being analyzed |
| `currentCname` | string \| null | Current DNS CNAME result |
| `cnameMatchesTarget` | boolean | Whether DNS points at HolyDocs |
| `hostnameId` | string \| null | Cloudflare custom-hostname ID, when registered |
| `hostnameStatus` | string \| null | Cloudflare hostname state, such as `pending` or `active` |
| `sslStatus` | string \| null | SSL/DCV state |
| `hostnameReady` | boolean | `true` when the hostname is active and SSL is active |
| `ownershipVerification` | object \| null | Cloudflare ownership-verification details when required |

## Set Custom Domain

Configure or replace the custom domain on a project.

```bash
PUT /api/v1/domains/:projectId
```

### Request Body

```json
{
  "customDomain": "docs.mycompany.com"
}
```

### Validation

- Lowercase alphanumeric characters and hyphens only
- Valid domain segments separated by dots
- Regex rule: start with a lowercase alphanumeric character, allow internal hyphens, and repeat dot-separated labels.

**cURL**

```bash
    curl -X PUT "https://api.holydocs.com/api/v1/domains/$PROJECT_ID" \
      -H "Authorization: Bearer $HOLYDOCS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"customDomain":"docs.mycompany.com"}'
    ```
  **CLI**

```bash
    holydocs api put /domains/$PROJECT_ID \
      --json '{"customDomain":"docs.mycompany.com"}'
    ```
  **SDK**

```ts
    await client.domains.set('docs.mycompany.com');
    ```

### Response

Returns the same shape as `GET /domains/:projectId`, including the latest `analysis`.

When Cloudflare SaaS bindings are configured on the backend, HolyDocs attempts to register the hostname immediately. If DNS is not pointed yet, `analysis.hostnameReady` remains `false` until verification succeeds.

## Analyze Domain

Force a fresh DNS and hostname-state lookup without changing the domain.

```bash
POST /api/v1/domains/:projectId/analyze
```

```bash
holydocs api post /domains/$PROJECT_ID/analyze
```

## Verify Domain

Force a verification pass. If DNS already points at HolyDocs and the hostname has not been registered yet, HolyDocs attempts registration during this call.

```bash
POST /api/v1/domains/:projectId/verify
```

**cURL**

```bash
    curl -X POST "https://api.holydocs.com/api/v1/domains/$PROJECT_ID/verify" \
      -H "Authorization: Bearer $HOLYDOCS_API_KEY"
    ```
  **CLI**

```bash
    holydocs api post /domains/$PROJECT_ID/verify
    ```
  **SDK**

```ts
    const analysis = await client.domains.verify();
    ```

## Domain Connect Launch

If the domain is managed by Cloudflare DNS, generate a signed Domain Connect launch URL that opens the one-click DNS flow in the Cloudflare dashboard.

```bash
POST /api/v1/domains/:projectId/domain-connect
```

```bash
holydocs api post /domains/$PROJECT_ID/domain-connect
```

## Remove Custom Domain

```bash
DELETE /api/v1/domains/:projectId
```

**cURL**

```bash
    curl -X DELETE "https://api.holydocs.com/api/v1/domains/$PROJECT_ID" \
      -H "Authorization: Bearer $HOLYDOCS_API_KEY"
    ```
  **CLI**

```bash
    holydocs api delete /domains/$PROJECT_ID
    ```
  **SDK**

```ts
    await client.domains.remove();
    ```

## Error Codes

| Code | Status | Description |
|---|---|---|
| `NOT_FOUND` | 404 | Project not found |
| `VALIDATION_ERROR` | 400 | Invalid hostname format or no custom domain configured |
| `ALREADY_EXISTS` | 409 | Domain is already attached to another project |
| `FEATURE_NOT_AVAILABLE` | 403 | Your plan cannot attach another custom domain |

## Related

- [Custom Domains](/custom-domains)
- [holydocs api](/cli/api)
- [API Authentication](/api/authentication)