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

Verify Domain

Verify DNS configuration for a custom domain

POST/v1/projects/{projectId}/domains/{domainId}/verifyTry it
Session token

Re-check a domain's DNS and certificate state and return its current status. When the domain reaches ssl_active or ready, it becomes the project's custom domain.

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 (Pro for a wildcard hostname). After a downgrade, verifying, retrying and confirming a domain return 402 plan_required. Listing, polling status and removing a domain keep working on any plan.

Path Parameters

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

Response

Returns the domain object with one extra field. Every verify stamps lastCheckedAt with the time of the check, even when the state did not change.

NameDescription
data.readyForTraffic:boolean
true once status is ssl_active or ready.

All are relative to /v1/projects/{projectId}/domains/{domainId}:

EndpointRolePlan-gatedDescription
GET /statusmemberNoPoll the current state, with readyForTraffic and DNS guidance. Also stamps lastCheckedAt
POST /retryadminYesAsk for validation to be re-run now instead of waiting
POST /confirm-readyadminYesMark an ssl_active domain as ready for production

Error Responses

402 Payment Required

Returned when the workspace is below Starter, or below Pro for a wildcard hostname — typically after a downgrade:

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.

404 Not Found

Returned when the domain does not exist in this project.

Was this page helpful? Yes No
Request
bashJavaScriptPythonGoRubyPHPJavaC#bash
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/domains/6b1e0c9a-2f4d-4b8e-9a51-0c7d3e2f1a44/verify \
-H "Authorization: Bearer $SYNTEXT_JWT"
Responseapplication/json
json
{
"data": {
"id": "6b1e0c9a-2f4d-4b8e-9a51-0c7d3e2f1a44",
"projectId": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c",
"domain": "docs.example.com",
"status": "ssl_active",
"cnameTarget": "cname.syntext.dev",
"hostnameStatus": "active",
"sslStatus": "active",
"ownershipVerification": null,
"sslValidationRecords": [],
"verifiedAt": "2026-11-08T12:04:00Z",
"validatedAt": "2026-11-08T12:05:00Z",
"sslActivatedAt": "2026-11-08T12:07:00Z",
"readyAt": null,
"lastCheckedAt": "2026-11-08T12:07:00Z",
"createdAt": "2026-11-08T12:00:00Z",
"readyForTraffic": true
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext