Tenant Preview Domain API

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 *.sandbox.miosa.ai.

Endpoints

Method	Path	Description
`GET`	`/api/v1/tenant/preview-domain`	Get current domain and verification status
`PUT`	`/api/v1/tenant/preview-domain`	Set or replace the preview domain
`POST`	`/api/v1/tenant/preview-domain/verify`	Recheck DNS verification
`DELETE`	`/api/v1/tenant/preview-domain`	Remove the custom domain

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.miosa.ai"
  }
}

Response - `200 OK` (not configured)

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

Field	Type	Description
`preview_domain`	string\|null	Configured apex domain, or `null`
`default_domain`	string	Fallback domain used when no custom domain is set
`status`	string	`"not_configured"`, `"pending_dns"`, or `"configured"`
`dns_instructions`	object\|null	CNAME record to add at your DNS registrar

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

Field	Type	Required	Description
`preview_domain`	string	Yes	Apex domain (e.g. `"cliniciq.com"`)

{
  "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.miosa.ai"
  }
}

DNS Setup

Add a wildcard CNAME at your registrar:

Type	Name	Value
`CNAME`	`` (or `.cliniciq.com`)	`proxy.miosa.ai`

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 *.sandbox.miosa.ai.

Response - `200 OK`

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

Errors

Status	Code	Cause
400	`preview_domain is required`	Missing body field
422	`invalid_domain`	Protocol prefix, wildcard, path, or subdomain detected
404	`tenant not found`	Tenant does not exist