The preview domain API lets you map your own apex domain (e.g. cliniciq.com) to sandbox preview URLs. When configured, sandboxes created under your tenant will be accessible at {sandbox-slug}.{your-domain} instead of the default *.sandboxes.miosa.ai.

Endpoints

Get Preview Domain

GET /api/v1/tenant/preview-domain

Returns the configured domain and its DNS verification status.

Auth

Authorization: Bearer msk_...

Response - 200 OK (domain configured)

{
  "preview_domain": "cliniciq.com",
  "status": "configured",
  "dns_instructions": {
    "type": "CNAME",
    "name": "*.cliniciq.com",
    "value": "proxy.sandboxes.miosa.ai"
  }
}

Response - 200 OK (not configured)

{
  "preview_domain": null,
  "default_domain": "sandboxes.miosa.ai",
  "status": "not_configured",
  "dns_instructions": null
}

Set Preview Domain

PUT /api/v1/tenant/preview-domain

Sets or replaces the custom preview domain. DNS verification is asynchronous - status transitions from pending_dns to configured once the CNAME resolves correctly.

Request Body

{
  "preview_domain": "cliniciq.com"
}

Response - 200 OK

{
  "preview_domain": "cliniciq.com",
  "status": "pending_dns",
  "dns_status": "pending",
  "dns_instructions": {
    "type": "CNAME",
    "name": "*.cliniciq.com",
    "value": "proxy.sandboxes.miosa.ai"
  }
}

DNS Setup

Add a wildcard CNAME at your registrar:

Verify DNS

POST /api/v1/tenant/preview-domain/verify

Triggers an immediate DNS re-check. Returns the current verification status without waiting for the background poller.

Response - 200 OK

{
  "preview_domain": "cliniciq.com",
  "status": "configured",
  "dns_status": "verified"
}

Delete Preview Domain

DELETE /api/v1/tenant/preview-domain

Removes the custom domain. Sandbox preview URLs revert to *.sandboxes.miosa.ai.

Response - 200 OK

{
  "preview_domain": null,
  "status": "removed"
}

Errors

Examples