Domains Endpoint

The Domains API lets you manage the custom domains where SitemapHost serves your sitemaps. Each domain maps to a subdomain you control (e.g., sitemap.yoursite.com) and is pointed to SitemapHost via a CNAME record.

Add a Domain

Register a new custom domain with your account.

POST https://dash.sitemaphost.app/api/domains

Request

curl -X POST https://dash.sitemaphost.app/api/domains \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "hostname": "sitemap.yoursite.com"
  }'

Request Body

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "domain_abc123",
    "hostname": "sitemap.yoursite.com",
    "status": "pending_verification",
    "sslStatus": "pending",
    "cnameTarget": "cname.sitemaphost.app",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Response Fields

Domain Status Values

SSL Status Values

Error: Domain already exists (409)

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Domain 'sitemap.yoursite.com' is already registered."
  }
}

Error: Domain limit reached (422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "You have reached your plan's domain limit (2). Upgrade your plan to add more domains."
  }
}

List Domains

Retrieve all domains associated with your account.

GET https://dash.sitemaphost.app/api/domains

Request

curl https://dash.sitemaphost.app/api/domains \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "domain_abc123",
      "hostname": "sitemap.yoursite.com",
      "status": "active",
      "sslStatus": "active",
      "cnameTarget": "cname.sitemaphost.app",
      "urlCount": 15230,
      "sitemapCount": 3,
      "lastUpdated": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-10T08:00:00Z"
    },
    {
      "id": "domain_def456",
      "hostname": "sitemap.myblog.com",
      "status": "pending_verification",
      "sslStatus": "pending",
      "cnameTarget": "cname.sitemaphost.app",
      "urlCount": 0,
      "sitemapCount": 0,
      "lastUpdated": null,
      "createdAt": "2024-01-14T12:00:00Z"
    }
  ]
}

Additional Fields on List

Verify Domain DNS

Trigger a DNS verification check for a domain. SitemapHost performs a DNS lookup to confirm the CNAME record points to cname.sitemaphost.app.

POST https://dash.sitemaphost.app/api/domains/:id/verify

Request

curl -X POST https://dash.sitemaphost.app/api/domains/domain_abc123/verify \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

No request body is needed.

Response: Verification successful (200 OK)

{
  "success": true,
  "data": {
    "id": "domain_abc123",
    "hostname": "sitemap.yoursite.com",
    "status": "verified",
    "sslStatus": "provisioning",
    "verifiedAt": "2024-01-15T10:05:00Z",
    "message": "DNS verified. SSL certificate is being provisioned."
  }
}

After successful verification, SitemapHost automatically begins SSL certificate provisioning via Cloudflare Custom Hostnames. This typically completes within 1-5 minutes.

Response: Verification failed (200 OK)

{
  "success": true,
  "data": {
    "id": "domain_abc123",
    "hostname": "sitemap.yoursite.com",
    "status": "pending_verification",
    "sslStatus": "pending",
    "message": "DNS verification failed. Expected CNAME to cname.sitemaphost.app but found no matching record. DNS changes can take up to 24 hours to propagate."
  }
}

Note: Verification returning a failure is not an HTTP error -- the response is still 200 OK with a descriptive message. Check the status field to determine the result.

Common Verification Failures

Delete a Domain

Remove a domain and all associated sitemaps. This action is permanent.

DELETE https://dash.sitemaphost.app/api/domains/:id

Request

curl -X DELETE https://dash.sitemaphost.app/api/domains/domain_abc123 \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "domain_abc123",
    "hostname": "sitemap.yoursite.com",
    "deleted": true,
    "message": "Domain and all associated sitemaps have been deleted."
  }
}

Warning: Deleting a domain removes all sitemap files from R2 storage and removes the Cloudflare Custom Hostname. The domain's sitemaps will immediately stop being served. Make sure to update your robots.txt and Google Search Console before deleting.

Error: Domain not found (404)

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Domain 'domain_abc123' not found."
  }
}

Complete Workflow Example

Here is the typical workflow for adding and configuring a new domain:

1. Add the domain

curl -X POST https://dash.sitemaphost.app/api/domains \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"hostname": "sitemap.yoursite.com"}'

2. Configure DNS

Add a CNAME record in your DNS provider:

3. Verify DNS

Wait for DNS propagation (usually minutes, up to 24 hours), then verify:

curl -X POST https://dash.sitemaphost.app/api/domains/domain_abc123/verify \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

4. Wait for SSL

Poll the domain status until sslStatus is "active":

curl https://dash.sitemaphost.app/api/domains \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

5. Upload a sitemap

Once SSL is active, upload your URLs:

curl -X POST https://dash.sitemaphost.app/api/sitemap/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "domain": "sitemap.yoursite.com",
    "urls": [{"loc": "https://yoursite.com/"}]
  }'

Your sitemap is now live at https://sitemap.yoursite.com/sitemap.xml.

Next Steps

• Upload Endpoint -- Upload URLs and generate sitemaps
• Custom Domains -- Detailed domain setup guide
• DNS Troubleshooting -- Fix DNS configuration issues
• SSL Troubleshooting -- Fix SSL certificate issues