> ## 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.

# Custom Domains

Configure a custom domain for your HolyDocs documentation site with automatic SSL certificate provisioning.

## Overview

Every HolyDocs project gets a default subdomain at `your-slug.holydocs.com`. You can also configure a custom domain like `docs.yourcompany.com` to serve your documentation under your own brand.

Want to serve docs at a path on your existing site (e.g., `yourcompany.com/docs`) instead of a subdomain? See [Subfolder Hosting](/subfolder-hosting).

## Setting Up a Custom Domain

**Add the domain in HolyDocs**

Go to **Settings > Domains** in your project dashboard and enter your custom domain:

    ```
    docs.yourcompany.com
    ```
  **Configure DNS**

Add a CNAME record with your DNS provider pointing your domain to `proxy.holydocs.com`:

    | Type | Name | Target |
    |---|---|---|
    | CNAME | docs | proxy.holydocs.com |

    If you are using Cloudflare DNS, you can enable the proxy (orange cloud) for additional DDoS protection.
  **Wait for verification**

HolyDocs automatically verifies your DNS configuration. This typically takes 1-5 minutes. The dashboard will show the verification status.
  **SSL provisioning**

Once DNS is verified, an SSL certificate is automatically provisioned for your domain. Your docs will be accessible over HTTPS with no additional configuration.

## Custom Domain via API

You can also configure domains programmatically:

### Get Domain Status

```bash
curl "https://api.holydocs.com/api/v1/domains/PROJECT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Or from the CLI:

```bash
holydocs api get /domains/PROJECT_ID
```

Response:

```json
{
  "data": {
    "subdomain": "my-project.holydocs.com",
    "customDomain": "docs.yourcompany.com",
    "cnameTarget": "proxy.holydocs.com",
    "analysis": {
      "hostnameReady": true,
      "cnameMatchesTarget": true,
      "sslStatus": "active"
    }
  }
}
```

### Set Custom Domain

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

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

### Verify Custom Domain

```bash
holydocs api post /domains/PROJECT_ID/verify
```

### Remove Custom Domain

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

## Domain Limits by Plan

| Plan | Custom Domains |
|---|---|
| Free | 0 |
| Starter | 1 |
| Pro | 5 |
| Business | 20 |
| Enterprise | Unlimited |

The default `*.holydocs.com` subdomain is always available and does not count toward your custom domain limit.

## Apex Domains

If you want to use an apex domain (e.g., `yourcompany.com` without a subdomain), your DNS provider must support CNAME flattening or ALIAS records:

- **Cloudflare** — Supports CNAME flattening automatically
- **AWS Route 53** — Use an ALIAS record pointing to `proxy.holydocs.com`
- **Other providers** — Check if CNAME flattening is supported; otherwise use a subdomain

## Troubleshooting

### Domain not verifying

- Confirm the CNAME record is pointing to `proxy.holydocs.com` (not your old host)
- DNS propagation can take up to 48 hours, though it usually completes in minutes
- Check for conflicting A records on the same hostname

### SSL errors

- SSL certificates are provisioned automatically after DNS verification
- Certificate provisioning typically takes 1-2 minutes after verification
- If SSL is not working after 10 minutes, try removing and re-adding the domain

### Domain already in use

Each custom domain can only be assigned to one HolyDocs project. If you see an "already in use" error, check if the domain is assigned to another project in your organization.