Custom Domains

Attach your own domain names to web services and static sites on Runsite. Each service can have one or more custom domains with automatic TLS.

Adding a Domain

POST /api/custom-domains?web_service_id={web_service_id}
Content-Type: application/json

{
  "domain": "app.example.com"
}

After adding, you need to configure DNS and verify ownership.

DNS Configuration

Point your domain at Runsite using either of the following records:

Use case	Record	Name	Value
Root or apex (example.com)	A	example.com	Platform IP (shown in dashboard)
Subdomain (app.example.com)	CNAME	app.example.com	<your-service>.runsite.app (web) or <your-site>.runsite.site (static)

The exact value to use is shown in the Custom domain dialog when you add the domain.

Verification

After configuring DNS, trigger verification:

POST /api/custom-domains/{domain_id}/verify?web_service_id={web_service_id}

Response:

{
  "domain": "app.example.com",
  "verified": true,
  "expected_ip": "203.0.113.1",
  "actual_ips": ["203.0.113.1"],
  "message": "Domain verified successfully"
}

If verification fails, the response shows the expected and actual DNS records to help debug the issue.

Managing Domains

List domains for a service

GET /api/custom-domains?web_service_id={web_service_id}

Get domain details

GET /api/custom-domains/{domain_id}?web_service_id={web_service_id}

Remove a domain

DELETE /api/custom-domains/{domain_id}?web_service_id={web_service_id}

Domain Status

Status	Description
pending	Domain added, DNS not yet verified
verified	DNS verified, TLS provisioning in progress
active	Domain fully active with TLS
failed	Verification or TLS provisioning failed