Tenant Preview Domain API

The preview domain API lets you map your own apex domain (e.g. example.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

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": "example.com",
  "status": "configured",
  "dns_instructions": {
    "type": "CNAME",
    "name": "*.example.com",
    "value": "proxy.miosa.ai"
  }
}

Response - 200 OK (not configured)

{
  "preview_domain": null,
  "default_domain": "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": "example.com"
}

Response - 200 OK

{
  "preview_domain": "example.com",
  "status": "pending_dns",
  "dns_status": "pending",
  "dns_instructions": {
    "type": "CNAME",
    "name": "*.example.com",
    "value": "proxy.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": "example.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

Examples