Domains API

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

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

bash
holydocs api get /domains/$PROJECT_ID

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

analysis Fields

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.

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"}'

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

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

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

bash
holydocs api post /domains/$PROJECT_ID/verify

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

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

bash
holydocs api delete /domains/$PROJECT_ID

ts
await client.domains.remove();

Error Codes

Related

• Custom Domains
• holydocs api
• API Authentication