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.
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
projectId3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).domainIdResponse
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.
data.readyForTraffictrue once status is ssl_active or ready.Related endpoints
All are relative to /v1/projects/{projectId}/domains/{domainId}:
| Endpoint | Role | Plan-gated | Description |
|---|---|---|---|
GET /status | member | No | Poll the current state, with readyForTraffic and DNS guidance. Also stamps lastCheckedAt |
POST /retry | admin | Yes | Ask for validation to be re-run now instead of waiting |
POST /confirm-ready | admin | Yes | Mark 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:
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.