Quickstart

You need an ADMIN_TOKEN to authenticate against the API. Set it as an environment variable:

export TOKEN="your-admin-token-here"

POST a slug and target origin. The slug must be 2–63 lowercase alphanumeric characters or hyphens, and must not be on the reserved list.

curl -X POST https://xdns.wtf/api/tenants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "myapp",
    "target_origin": "https://myapp.vercel.app"
  }'

You'll receive:

{
  "ok": true,
  "fqdn": "myapp.xdns.wtf",
  "target_origin": "https://myapp.vercel.app"
}

Your subdomain is live immediately. All paths and query strings are preserved:

curl https://myapp.xdns.wtf/
# → proxied from https://myapp.vercel.app

# Paths and query strings work:
curl https://myapp.xdns.wtf/api/users?page=2
# → https://myapp.vercel.app/api/users?page=2

The Worker adds X-XDNS-Tenant: myapp to all upstream requests so your origin can identify the routing source.

Verify the configuration of any active tenant:

curl https://xdns.wtf/api/tenants/myapp \
  -H "Authorization: Bearer $TOKEN"

{
  "slug": "myapp",
  "target_origin": "https://myapp.vercel.app",
  "subnet_id": null,
  "status": "active",
  "created_at": 1740600000
}

When you're done, DELETE the tenant. Routing stops immediately — no DNS flush required.

curl -X DELETE https://xdns.wtf/api/tenants/myapp \
  -H "Authorization: Bearer $TOKEN"

# { "ok": true }