dnshe-freedomains

What this skill does

# DNSHE Free Domains & Anycast DNS

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

DNSHE ([dnshe.com](https://www.dnshe.com)) provides free subdomains under `us.ci`, `cc.cd`, `de5.net`, and `ccwu.cc` backed by enterprise Anycast DNS. It supports A, AAAA, CNAME, MX, TXT, NS, SRV, and CAA records, a 180-day renewal window, and a REST API for full automation — no credit card required.

---

## Getting Started

### 1. Register an Account
Go to [dnshe.com](https://www.dnshe.com) and sign up. No credit card needed.

### 2. Claim a Subdomain
Search for your desired prefix (e.g., `myproject`) and pair it with a suffix:

| Suffix | Use Case |
|---|---|
| `*.us.ci` | CI/CD pipelines, API endpoints, SaaS |
| `*.cc.cd` | Portfolios, creative projects |
| `*.de5.net` | Tech blogs, dev environments, docs |
| `*.ccwu.cc` | Personal pages, community projects |

### 3. Add DNS Records
From the dashboard, add your records (A, CNAME, TXT, etc.). Propagation happens in seconds via Anycast.

---

## REST API Reference

All API interactions require an API token obtained from the DNSHE dashboard under account settings.

### Authentication
All requests use a Bearer token in the `Authorization` header:
```
Authorization: Bearer $DNSHE_API_TOKEN
```

Store your token as an environment variable:
```bash
export DNSHE_API_TOKEN="your_token_here"
export DNSHE_BASE_URL="https://www.dnshe.com/api/v1"
```

---

## Key API Operations

### List Your Domains
```bash
curl -s -X GET "$DNSHE_BASE_URL/domains" \
  -H "Authorization: Bearer $DNSHE_API_TOKEN" \
  -H "Content-Type: application/json"
```

### Register a Subdomain
```bash
curl -s -X POST "$DNSHE_BASE_URL/domains" \
  -H "Authorization: Bearer $DNSHE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "myproject",
    "suffix": "us.ci"
  }'
```

### Add a DNS Record
```bash
curl -s -X POST "$DNSHE_BASE_URL/domains/myproject.us.ci/records" \
  -H "Authorization: Bearer $DNSHE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "@",
    "value": "203.0.113.42",
    "ttl": 300
  }'
```

### Update a DNS Record
```bash
curl -s -X PUT "$DNSHE_BASE_URL/domains/myproject.us.ci/records/{record_id}" \
  -H "Authorization: Bearer $DNSHE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "@",
    "value": "203.0.113.99",
    "ttl": 300
  }'
```

### Delete a DNS Record
```bash
curl -s -X DELETE "$DNSHE_BASE_URL/domains/myproject.us.ci/records/{record_id}" \
  -H "Authorization: Bearer $DNSHE_API_TOKEN"
```

### Renew a Domain
```bash
curl -s -X POST "$DNSHE_BASE_URL/domains/myproject.us.ci/renew" \
  -H "Authorization: Bearer $DNSHE_API_TOKEN"
```

---

## Code Examples

### Python: Full Domain Setup Script
```python
import os
import requests

API_TOKEN = os.environ["DNSHE_API_TOKEN"]
BASE_URL = "https://www.dnshe.com/api/v1"

HEADERS = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json",
}

def register_subdomain(subdomain: str, suffix: str) -> dict:
    resp = requests.post(
        f"{BASE_URL}/domains",
        headers=HEADERS,
        json={"subdomain": subdomain, "suffix": suffix},
    )
    resp.raise_for_status()
    return resp.json()

def add_record(domain: str, record_type: str, name: str, value: str, ttl: int = 300) -> dict:
    resp = requests.post(
        f"{BASE_URL}/domains/{domain}/records",
        headers=HEADERS,
        json={"type": record_type, "name": name, "value": value, "ttl": ttl},
    )
    resp.raise_for_status()
    return resp.json()

def renew_domain(domain: str) -> dict:
    resp = requests.post(
        f"{BASE_URL}/domains/{domain}/renew",
        headers=HEADERS,
    )
    resp.raise_for_status()
    return resp.json()

def list_domains() -> list:
    resp = requests.get(f"{BASE_URL}/domains", headers=HEADERS)
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    # Register subdomain
    result = register_subdomain("myproject", "us.ci")
    print("Registered:", result)

    # Point it to a server
    record = add_record("myproject.us.ci", "A", "@", "203.0.113.42")
    print("Record added:", record)

    # Add a www CNAME
    cname = add_record("myproject.us.ci", "CNAME", "www", "myproject.us.ci")
    print("CNAME added:", cname)
```

### Python: Automated Renewal Script (Cron-friendly)
```python
import os
import requests
from datetime import datetime, timedelta

API_TOKEN = os.environ["DNSHE_API_TOKEN"]
BASE_URL = "https://www.dnshe.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_TOKEN}"}

def renew_expiring_domains(days_threshold: int = 30):
    """Renew any domain expiring within `days_threshold` days."""
    resp = requests.get(f"{BASE_URL}/domains", headers=HEADERS)
    resp.raise_for_status()
    domains = resp.json()

    now = datetime.utcnow()
    threshold = now + timedelta(days=days_threshold)

    for domain in domains:
        # Adjust field name to match actual API response
        expires_at = datetime.fromisoformat(domain.get("expires_at", "").replace("Z", ""))
        if expires_at <= threshold:
            name = domain["domain"]
            renew_resp = requests.post(f"{BASE_URL}/domains/{name}/renew", headers=HEADERS)
            if renew_resp.ok:
                print(f"✅ Renewed: {name}")
            else:
                print(f"❌ Failed to renew {name}: {renew_resp.text}")

if __name__ == "__main__":
    renew_expiring_domains(days_threshold=30)
```

### JavaScript/Node.js: Domain Management Client
```javascript
const fetch = require('node-fetch'); // or use built-in fetch in Node 18+

const API_TOKEN = process.env.DNSHE_API_TOKEN;
const BASE_URL = 'https://www.dnshe.com/api/v1';

const headers = {
  'Authorization': `Bearer ${API_TOKEN}`,
  'Content-Type': 'application/json',
};

async function registerSubdomain(subdomain, suffix) {
  const res = await fetch(`${BASE_URL}/domains`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ subdomain, suffix }),
  });
  if (!res.ok) throw new Error(`Register failed: ${await res.text()}`);
  return res.json();
}

async function addRecord(domain, type, name, value, ttl = 300) {
  const res = await fetch(`${BASE_URL}/domains/${domain}/records`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ type, name, value, ttl }),
  });
  if (!res.ok) throw new Error(`Add record failed: ${await res.text()}`);
  return res.json();
}

async function listDomains() {
  const res = await fetch(`${BASE_URL}/domains`, { headers });
  if (!res.ok) throw new Error(`List failed: ${await res.text()}`);
  return res.json();
}

async function renewDomain(domain) {
  const res = await fetch(`${BASE_URL}/domains/${domain}/renew`, {
    method: 'POST',
    headers,
  });
  if (!res.ok) throw new Error(`Renew failed: ${await res.text()}`);
  return res.json();
}

// Example usage
(async () => {
  const domain = await registerSubdomain('myapp', 'cc.cd');
  console.log('Registered:', domain);

  const record = await addRecord('myapp.cc.cd', 'A', '@', '203.0.113.42');
  console.log('A record added:', record);

  // Add TXT for domain verification / Let's Encrypt
  const txt = await addRecord('myapp.cc.cd', 'TXT', '_acme-challenge', 'your-challenge-value');
  console.log('TXT record added:', txt);
})();
```

### GitHub Actions: Auto-Renewal Workflow
```yaml
# .github/workflows/dnshe-renew.yml
name: DNSHE Domain Auto-Renewal

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am UTC
  workflow_dispatch:

jobs:
  renew:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install requests

      - name: Run renewal script
        env:
          DNSHE_API_TOKEN: ${{ secrets.DNSHE_API_TOKEN }}
        run: python scripts/renew_domains.py
```

### Bash: Quick Record Updat