Add a custom domain to serve your documentation from (e.g., docs.example.com).
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
projectId3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).Request Body
domaindocs.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
dataidprojectIddomaindocs.example.com or *.docs.example.com.statuspending_validation → hostname_active → ssl_active → ready, or failed. Traffic is safe once the status is ssl_active or ready.cnameTargetcname.syntext.dev.hostnameStatuspending or active.sslStatuspending or active.ownershipVerification{ type, name, value, status }.sslValidationRecords{ type, name, value, status }.verifiedAtvalidatedAtsslActivatedAtreadyAtlastCheckedAtGET …/status) and every verify, whatever the outcome. null until the first check.createdAtdata.guidancednsRecords{ type, name, value, status, purpose }. The certificate and ownership TXT records come first, and the CNAME to cname.syntext.dev comes last.txtRecordsVerifiedTXT record has validated.cnameTargetwarningTXT records validate. Add those before the CNAME.apexNoteexample.com), where many DNS providers need ALIAS/ANAME or CNAME flattening.verificationStepsResponse
Use the record names and values from your own response — the ones above are illustrative.
DNS Configuration
- 01Step 1 of 31 ›Step 11.Add the TXT records
Create every
TXTrecord inguidance.dnsRecordsand wait for them to validate (usually within 5 minutes). PollGET /v1/projects/{projectId}/domains/{domainId}/status, or call Verify Domain. - 02Step 2 of 32 ›Step 22.Add the CNAME
Point the hostname at
cname.syntext.dev. - 03Step 3 of 33 ›Step 33.Wait for the certificate
The certificate is issued automatically. The domain can take traffic once
statusisssl_activeorready.
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):
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.