Skip to main content

​
Overview

Custom domains let you serve your SimpleHost sites from your own domain (e.g., docs.mysite.com). SSL certificates are provisioned automatically.
PlanCustom Domains
Free1
Hobby ($5/mo)5
All domain endpoints require authentication.

​
Add a Domain

POST /api/v1/domains
Adds a custom domain to your account and returns DNS configuration instructions.

​
Request

​
domain
string
required
The domain to add (e.g., docs.mysite.com or mysite.com).
curl -X POST https://simplehost.dev/api/v1/domains \
  -H "Authorization: Bearer sh_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "docs.mysite.com"}'

​
Response (201)

{
  "domain": "docs.mysite.com",
  "status": "pending",
  "dns": {
    "instructions": "Add this DNS record to docs.mysite.com:",
    "records": [
      {
        "type": "CNAME",
        "name": "docs.mysite.com",
        "value": "simplehost.dev",
        "note": "Points your domain to SimpleHost"
      },
      {
        "type": "TXT",
        "name": "_simplehost.docs.mysite.com",
        "value": "simplehost-verify=a1b2c3d4e5f6...",
        "note": "Proves you own this domain"
      }
    ]
  },
  "message": "Domain added. Configure DNS records, then call POST /api/v1/domains/:domain/verify"
}
After adding a domain, configure the DNS records at your registrar, then call the verify endpoint.

​
Verify a Domain

POST /api/v1/domains/:domain/verify
Checks DNS records and activates the domain if verification passes. 
curl -X POST https://simplehost.dev/api/v1/domains/docs.mysite.com/verify \
  -H "Authorization: Bearer sh_live_your_key_here"

​
Response (verified)

{
  "domain": "docs.mysite.com",
  "status": "active",
  "verified": true,
  "message": "Domain verified successfully! You can now create links using this domain."
}

​
Response (not yet verified)

{
  "domain": "docs.mysite.com",
  "status": "pending",
  "verified": false,
  "message": "TXT record not found. Add a TXT record for \"_simplehost.docs.mysite.com\" with value \"simplehost-verify=a1b2c3...\""
}
DNS changes can take up to 48 hours to propagate, but typically complete within a few minutes. If verification fails, wait and try again.

​
List Domains

GET /api/v1/domains
Returns all custom domains on your account. 
curl -X GET https://simplehost.dev/api/v1/domains \
  -H "Authorization: Bearer sh_live_your_key_here"

​
Response

{
  "domains": [
    {
      "domain": "docs.mysite.com",
      "status": "active",
      "sslStatus": "active",
      "isApex": false,
      "verificationTxtName": "_simplehost.docs.mysite.com",
      "verificationTxtValue": "simplehost-verify=a1b2c3...",
      "createdAt": "2026-03-20T10:00:00.000Z",
      "verifiedAt": "2026-03-20T10:05:00.000Z"
    }
  ],
  "total": 1
}

​
Delete a Domain

DELETE /api/v1/domains/:domain
Removes a custom domain from your account. 
curl -X DELETE https://simplehost.dev/api/v1/domains/docs.mysite.com \
  -H "Authorization: Bearer sh_live_your_key_here"

​
Response

{
  "domain": "docs.mysite.com",
  "deleted": true
}
Deleting a domain also removes all links associated with it. This action cannot be undone.

​
Errors

CodeStatusDescription
UNAUTHORIZED401Missing or invalid API key
INVALID_REQUEST400Invalid domain format or domain already registered
PLAN_LIMIT403Domain limit reached for your plan
NOT_FOUND404Domain not found in your account