Skip to main content

​
Domains API

Domains APIs manage redirect domains and optional custom email sending domains.

​
Endpoint matrix

MethodPathPurpose
GET/domainsList workspace domains
GET/domains/:idGet one domain
POST/domainsCreate custom domain
POST/domains/:id/verifyRe-check DNS/SSL verification
PATCH/domains/:idUpdate domain behavior/settings
DELETE/domains/:idRemove domain and connected provider resources
POST/domains/:id/email/setupCreate email domain in provider
POST/domains/:id/email/verifyVerify email DNS records
GET/domains/:id/email/statusFetch current email-domain status
DELETE/domains/:id/emailRemove custom email domain setup
POST/domains/:id/email/testSend verification test email

​
Domain creation + DNS model

Create flow validates:
  • plan domain limits
  • global domain uniqueness
  • normalized/punycode domain values
Generated DNS instructions include CNAME routing toward Linquid proxy infrastructure. Verification checks Cloudflare-managed custom hostname and SSL state.

​
Verification/status model

Operational states include:
  • verification status (verified boolean)
  • SSL status (pending, active, failed)
  • provider-side status hints (for diagnostics)
POST /domains/:id/verify is safe to re-run and used as the canonical refresh action after DNS changes.

​
Domain settings update (PATCH /domains/:id)

Supports settings such as:
  • not-found redirect URL
  • expired-link redirect URL
  • Apple App Site Association (AASA) JSON
  • Android asset links JSON
JSON fields are validated before persistence.

​
Custom email-domain flow

Email-domain setup has stricter gating:
  • requires configured email provider credentials
  • requires verified redirect domain first
  • currently restricted to Enterprise entitlement
After setup, use .../email/verify until status reaches verified, then use .../email/test to validate sender path.

​
Authorization and permissions

  • domains:read for reads
  • domains:manage for create/update/delete/verify operations

​
Typical failures

  • 403 LIMIT_EXCEEDED when plan domain quota is reached
  • 400 DOMAIN_EXISTS when domain is already registered
  • 400 DOMAIN_NOT_VERIFIED before email setup
  • 403 PLAN_REQUIRED for non-Enterprise email-domain setup
  • 500 CF_ERROR/RESEND_ERROR for provider operation failures
Related docs:
  • /user-guides/manual/workspace/workspace-settings-and-governance-reference
  • /user-guides/manual/data/data-retention-and-lifecycle