/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Add Custom Domain

Add Custom Domain

Add a custom domain to a project

POST/v1/projects/{projectId}/domainsTry it
Session token

Add a custom domain to serve your documentation from (e.g., docs.example.com).

Note

Org membership is required. Being signed in is not enough: you must be a member of the organization that owns {projectId}. A project you cannot see returns 404, one you are not a member of returns 403 with the forbidden code — see Authentication.

Requires the admin or owner role. Adding, verifying, retrying and removing custom domains are admin actions; a member gets 403 forbidden with details.requiredRole: "admin". Any member can list domains and poll their status.

Starter plan or higher, and Pro for a wildcard hostname. Lower plans get 402 plan_required — see Plan errors.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID (e.g., 3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).

Request Body

NameDescription
domain:stringbodyRequired
The hostname, lowercase, 3–253 characters — e.g. docs.example.com. A single leading *. label makes it a wildcard hostname, such as *.docs.example.com. Wildcards need the Pro plan, and a * anywhere else is rejected.

Response

Returns 201 with the domain object plus a guidance object describing the DNS records to create.

Domain object

NameDescription
data:object
Show 15 child attributesobject
data.guidance:object
DNS instructions for this hostname.
Show 6 child attributesobject

Response

Use the record names and values from your own response — the ones above are illustrative.

DNS Configuration

  1. 01Step 1 of 31 ›Step 11.
    Add the TXT records

    Create every TXT record in guidance.dnsRecords and wait for them to validate (usually within 5 minutes). Poll GET /v1/projects/{projectId}/domains/{domainId}/status, or call Verify Domain.

  2. 02Step 2 of 32 ›Step 22.
    Add the CNAME

    Point the hostname at cname.syntext.dev.

  3. 03Step 3 of 33 ›Step 33.
    Wait for the certificate

    The certificate is issued automatically. The domain can take traffic once status is ssl_active or ready.

Error Responses

400 Bad Request

Returned when the hostname is malformed (validation_error, with each problem in details.issues — path ["domain"]).

402 Payment Required

Returned when the workspace's plan does not include custom domains (Starter or higher), or the hostname is a wildcard (Pro or higher):

json
{
"error": {
"code": "plan_required",
"message": "Custom domains require the Starter plan or higher. This workspace is on Free.",
"details": {
"feature": "custom_domains",
"requiredTier": "starter",
"currentTier": "free",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

A wildcard hostname on Starter returns the same error with feature: wildcard_domains and requiredTier: pro.

403 Forbidden

Returned when you are a member of the workspace but not an admin or owner (details.requiredRole: "admin"), or not a member of the organization that owns the project.

409 Conflict

Returned when the hostname is already registered to a project. A domain from a deleted project is released and can be added again. In the rare case its release hasn't finished yet, the 409 message says the domain is still being released: try again in a few minutes.

Was this page helpful? Yes No
Request
bashJavaScriptPythonGoRubyPHPJavaC#bash
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/domains \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-H "Content-Type: application/json" \
-d '{"domain": "docs.example.com"}'
Responseapplication/json
json
{
"data": {
"id": "6b1e0c9a-2f4d-4b8e-9a51-0c7d3e2f1a44",
"projectId": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c",
"domain": "docs.example.com",
"status": "pending_validation",
"cnameTarget": "cname.syntext.dev",
"hostnameStatus": "pending",
"sslStatus": "pending",
"ownershipVerification": {
"type": "txt",
"name": "_cf-custom-hostname.docs.example.com",
"value": "5f2c7a1e-8d3b-4e6f-9a0c-1b2d3e4f5a6b",
"status": "pending"
},
"sslValidationRecords": [],
"verifiedAt": null,
"validatedAt": null,
"sslActivatedAt": null,
"readyAt": null,
"lastCheckedAt": null,
"createdAt": "2026-11-08T12:00:00Z",
"guidance": {
"dnsRecords": [
{
"type": "TXT",
"name": "_cf-custom-hostname.docs.example.com",
"value": "5f2c7a1e-8d3b-4e6f-9a0c-1b2d3e4f5a6b",
"status": "pending",
"purpose": "Domain ownership verification"
},
{
"type": "CNAME",
"name": "docs",
"value": "cname.syntext.dev",
"status": "pending",
"purpose": "Route traffic to Syntext"
}
],
"txtRecordsVerified": false,
"cnameTarget": "cname.syntext.dev",
"warning": "Add your TXT records first and wait for them to be validated before adding your CNAME record.",
"apexNote": null,
"verificationSteps": [
"Add the TXT records shown above to your DNS configuration",
"TXT records are typically validated within 5 minutes",
"Once TXT records are verified, add the CNAME record",
"An SSL certificate will be provisioned automatically"
]
}
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext