Skip to main content

​
Domains API

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

​
Endpoint matrix

​
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