Custom domains let you expose MIOSA previews, computers, and deployments under tenant-owned FQDNs. There are four related surfaces:

• Computer custom domains map one fully qualified domain, such as app.yourdomain.com, to one Computer service.
• Deployment custom domains map one fully qualified domain, such as program.drsmithclinic.com, to one Deployment.
• Tenant preview domains white-label generated preview links for the whole organization. After configuration, sandbox /expose responses use URLs such as https://5173-sbx01j9x.sandbox.cliniciq.dev.
• Workspace and project preview domains override the organization preview domain for one client workspace or one project.

MIOSA handles verification and automatic TLS certificate issuance via Caddy on-demand TLS.

Nested base paths: /api/v1/computers/{id}/domains and /api/v1/deployments/{id}/domains.

Flat frontend-compatible base path: /api/v1/custom-domains.

Quick Start

import { Miosa } from '@miosa/sdk';

const client = new Miosa();

// 1. Register the domain
const domain = await client.domains.register(computerId, {
  domain: 'app.yourcompany.com',
});
console.log(domain.verificationTarget); // e.g. "verify.miosa.ai"

// 2. Add a CNAME record at your DNS provider:
//    app.yourcompany.com → verify.miosa.ai

// 3. Trigger verification
const verified = await client.domains.verify(computerId, domain.id);
console.log(verified.status); // "verified" or "failed"

# Register
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/domains 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"domain": "app.yourcompany.com"}'

Endpoints

Computer custom domains

Deployment custom domains

Flat custom domains

Tenant preview domains

Workspace and project preview domains

White-label Managed Links

Use a tenant preview domain when generated app/artifact preview URLs should use your organization’s domain instead of the platform default miosa.app.

curl -X PUT https://api.miosa.ai/api/v1/tenant/preview-domain 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"preview_domain":"preview.yourcompany.com"}'

Then expose a sandbox port:

curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/expose 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"port":5173}'

Response:

{
  "url": "https://5173-sbx01j9x.sandbox.preview.yourcompany.com"
}

For a client workspace domain:

curl -X PUT https://api.miosa.ai/api/v1/workspaces/$WORKSPACE_ID/preview-domain 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"preview_domain":"drsmithclinic.com"}'

For a single project domain:

curl -X PUT https://api.miosa.ai/api/v1/projects/$PROJECT_ID/preview-domain 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"preview_domain":"program.drsmithclinic.com"}'

DNS must delegate wildcard traffic to the MIOSA preview router:

If no preview domain is configured, MIOSA returns the managed miosa.app fallback. This fallback remains available even after custom domains are attached.

Preview-domain precedence is project → workspace → tenant → MIOSA fallback. Exact deployment/computer custom domains still take priority over preview-domain inheritance.

Register a Domain

POST /api/v1/computers/{id}/domains

Request Body

Response — 201 Created

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "computer_id": "...",
    "deployment_id": null,
    "tenant_id": "...",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440001",
    "project_id": "770e8400-e29b-41d4-a716-446655440002",
    "fqdn": "app.yourcompany.com",
    "status": "pending",
    "verification_target": "verify.miosa.ai",
    "verified_at": null,
    "tls_issued_at": null,
    "external_workspace_id": "clinic_123",
    "external_user_id": "dr-smith-456",
    "external_project_id": "project_789",
    "created_at": "2026-04-11T00:00:00Z",
    "updated_at": "2026-04-11T00:00:00Z"
  }
}

Status Values

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/domains 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"domain": "preview.yourapp.io"}'

Register a deployment domain

curl -X POST https://api.miosa.ai/api/v1/deployments/{id}/domains 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"domain": "program.drsmithclinic.com"}'

Deployment domains inherit workspace_id, project_id, and external attribution from the deployment.

List Domains

GET /api/v1/computers/{id}/domains

Response — 200 OK

{
  "data": [
    {
      "id": "...",
      "fqdn": "app.yourcompany.com",
      "status": "active",
      "verified_at": "2026-04-11T01:00:00Z",
      "tls_issued_at": "2026-04-11T01:05:00Z",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}

curl https://api.miosa.ai/api/v1/computers/{id}/domains 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Verify a Domain

POST /api/v1/computers/{id}/domains/{domain_id}/verify

Checks that the CNAME record at fqdn resolves to verification_target. On success the domain transitions to "verified" and Caddy will issue a TLS certificate on the next HTTPS request to the FQDN.

Path Parameters

Response — 200 OK

{
  "data": {
    "id": "...",
    "fqdn": "app.yourcompany.com",
    "status": "verified",
    "verified_at": "2026-04-11T01:00:00Z"
  }
}

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/domains/{domain_id}/verify 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Remove a Domain

DELETE /api/v1/computers/{id}/domains/{domain_id}

Detaches the domain from the computer. The certificate is not revoked immediately (Caddy lets it expire naturally), but the domain will no longer route to the computer.

Response — 200 OK

{
  "data": { "id": "...", "fqdn": "app.yourcompany.com", "status": "removed" }
}

curl -X DELETE https://api.miosa.ai/api/v1/computers/{id}/domains/{domain_id} 
  -H "Authorization: Bearer $MIOSA_API_KEY"

DNS Setup Reference

After registering a domain, add the following DNS record at your registrar or DNS provider:

DNS propagation typically takes 1–60 minutes. Call verify once propagation is complete. If verification fails, wait a few minutes and retry — the endpoint is idempotent.

Common Recipes

Automate full domain onboarding

import time
from miosa import Miosa

client = Miosa()

domain = client.domains.register(computer_id, fqdn="api.yourcompany.com")
print(f"Add CNAME: {domain.fqdn} → {domain.verification_target}")
print("Waiting for DNS propagation...")

while True:
    result = client.domains.verify(computer_id, domain.id)
    if result.status == "verified":
        print("Domain verified! TLS will be issued on first HTTPS request.")
        break
    elif result.status == "failed":
        raise RuntimeError("Verification failed — check your DNS records.")
    time.sleep(30)

List all pending domains (potential stuck ACME issuances)

const computers = await client.computers.list();
for (const computer of computers.data) {
  const { data: domains } = await client.domains.list(computer.id);
  const pending = domains.filter(d => d.status === 'pending');
  if (pending.length > 0) {
    console.log(`${computer.name}: ${pending.length} domain(s) pending verification`);
  }
}