Free Domain Name Service API User Manual

Welcome to the Free Domain API Service.

This API is designed to provide developers with an efficient and convenient domain management solution. It supports subdomain registration, DNS record configuration, API key management, quota queries, and other core features—all without requiring in-depth knowledge of underlying DNS technologies.

The documentation outlines the API request specifications, endpoint details, request/response examples, and multi-language SDK implementations. It is suitable for a wide range of application scenarios that require domain service integration, such as developer tools, SaaS platforms, and personal projects.

Before using the API, please ensure you have obtained a valid API Key and API Secret, and follow all authentication and rate-limit requirements. It is recommended to use HTTP Headers to transmit authentication information and apply best practices for key security and access control.

If you encounter issues during integration, refer to the FAQ section in the documentation or contact customer support for technical assistance. We will continue improving both the API and the documentation to provide you with a more stable and efficient development experience.

1. Basic Information

API Endpoint:
https://api005.dnshe.com/index.php?m=domain_hub

Authentication Method:
API Key + API Secret

Supported Format:
JSON

Default Rate Limit:
60 requests per minute

2. Authentication Mechanism

1. Obtain API Keys

• Log in to the DNSHE Client Area
• Navigate to the Free Domain page
• Find the API Management section at the bottom
• Click Create API Key

Method 1: HTTP Header (Recommended)

bash
 
 
 
 
 
curl -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy"
 

Method 2: URL Parameters

bash
 
 
 
 
 
curl -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list&api_key=cfsd_xxxxxxxxxx&api_secret=yyyyyyyyyyyy"
 

3. Core API Endpoints & Examples

1. Subdomain Management

Action Method Description
list GET List all subdomains
register POST Register a new subdomain
get GET Get subdomain details
delete POST/DELETE Delete a subdomain
renew POST/PUT Renew a subdomain

1.1 List Subdomains

  • Request Example:
 
bash
 
 
 
 
 
curl -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy"
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "count": 2,
  "subdomains": [
    {
      "id": 1,
      "subdomain": "test",
      "rootdomain": "example.com",
      "full_domain": "test.example.com",
      "status": "active",
      "created_at": "2025-10-19 10:00:00",
      "updated_at": "2025-10-19 10:00:00"
    },
    {
      "id": 2,
      "subdomain": "api",
      "rootdomain": "example.com",
      "full_domain": "api.example.com",
      "status": "active",
      "created_at": "2025-10-19 11:00:00",
      "updated_at": "2025-10-19 11:00:00"
    }
  ]
}
 

1.2 Register Subdomain

  • Request Parameters:
    • subdomain: Subdomain prefix (string, required)
    • rootdomain: Root domain (string, required)
  • Request Example:
 
bash
 
 
 
 
 
curl -X POST "https://your-domain.com/index.php?m=domain_hub&endpoint=subdomains&action=register" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "myapp",
    "rootdomain": "example.com"
  }'
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "message": "Subdomain registered successfully",
  "subdomain_id": 3,
  "full_domain": "myapp.example.com"
}
 

1.3 Get Subdomain Details

  • Request Parameter: subdomain_id (integer, required)
  • Request Example:
 
bash
 
 
 
 
 
curl -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=get&subdomain_id=1" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy"
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "subdomain": {
    "id": 1,
    "subdomain": "test",
    "rootdomain": "example.com",
    "full_domain": "test.example.com",
    "status": "active",
    "created_at": "2025-10-19 10:00:00",
    "updated_at": "2025-10-19 10:00:00"
  },
  "dns_records": [
    {
      "id": 1,
      "name": "test.example.com",
      "type": "A",
      "content": "192.168.1.1",
      "ttl": 120,
      "priority": null,
      "status": "active",
      "created_at": "2025-10-19 10:05:00"
    }
  ],
  "dns_count": 1
}
 

1.4 Delete Subdomain

  • Request Parameter: subdomain_id (integer, required)
  • Request Example:
 
bash
 
 
 
 
 
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=delete" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain_id": 1
  }'
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "message": "Subdomain deleted successfully"
}
 

1.5 Renew Subdomain

  • Request Parameter: subdomain_id (integer, required)
  • Request Example:
 
bash
 
 
 
 
 
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=renew" \
-H "X-API-Key: cfsd_xxxxxxxxxx" \
-H "X-API-Secret: yyyyyyyyyyyy" \
-H "Content-Type: application/json" \
-d '{
  "subdomain_id": 3
}'
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "message": "Subdomain renewed successfully",
  "subdomain_id": 3,
  "subdomain": "myapp",
  "previous_expires_at": "2025-05-01 00:00:00",
  "new_expires_at": "2026-05-01 00:00:00",
  "renewed_at": "2025-04-10 12:34:56",
  "never_expires": 0,
  "status": "active",
  "remaining_days": 366
}
 

2. DNS Record Management

Action Method Description
list GET List DNS records for a subdomain
create POST Create a DNS record
update POST/PUT Update a DNS record
delete POST/DELETE Delete a DNS record

2.1 List DNS Records

  • Request Parameter: subdomain_id (integer, required)
  • Request Example:
 
bash
 
 
 
 
 
curl -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=list&subdomain_id=1" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy"
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "count": 2,
  "records": [
    {
      "id": 1,
      "name": "test.example.com",
      "type": "A",
      "content": "192.168.1.1",
      "ttl": 120,
      "priority": null,
      "proxied": false,
      "status": "active",
      "created_at": "2025-10-19 10:05:00"
    },
    {
      "id": 2,
      "name": "www.test.example.com",
      "type": "CNAME",
      "content": "test.example.com",
      "ttl": 120,
      "priority": null,
      "proxied": false,
      "status": "active",
      "created_at": "2025-10-19 10:10:00"
    }
  ]
}
 

2.2 Create DNS Record

  • Request Parameters:
    • subdomain_id: Associated subdomain ID (integer, required)
    • type: Record type (A/AAAA/CNAME/MX/TXT, required)
    • content: Record value (string, required)
    • name: Record name (string, optional)
    • ttl: TTL value (integer, optional, default 120)
    • priority: Priority (integer, optional, required for MX records)
  • Request Example:
 
bash
 
 
 
 
 
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=create" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain_id": 1,
    "type": "A",
    "content": "192.168.1.100",
    "ttl": 600
  }'
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "message": "DNS record created successfully",
  "record_id": 3
}
 

2.3 Update DNS Record

  • Request Parameters:
    • record_id: DNS record ID (integer, required)
    • content: New record value (string, optional)
    • ttl: New TTL value (integer, optional)
    • priority: New priority (integer, optional)
  • Request Example:
 
bash
 
 
 
 
 
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=update" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": 1,
    "content": "192.168.1.200",
    "ttl": 600
  }'
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "message": "DNS record updated successfully"
}
 

2.4 Delete DNS Record

  • Request Parameter: record_id (integer, required)
  • Request Example:
 
bash
 
 
 
 
 
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=delete" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": 1
  }'
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "message": "DNS record deleted successfully"
}
 

3. API Key Management

Action Method Description
list GET List all API keys
create POST Create a new API key
delete POST/DELETE Delete an API key
regenerate POST Regenerate an API key

3.1 List API Keys

  • Request Example:
 
bash
 
 
 
 
 
curl -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=keys&action=list" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy"
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "count": 2,
  "keys": [
    {
      "id": 1,
      "key_name": "Production Key",
      "api_key": "cfsd_xxxxxxxxxx",
      "status": "active",
      "request_count": 1523,
      "last_used_at": "2025-10-19 15:30:00",
      "created_at": "2025-10-19 10:00:00"
    },
    {
      "id": 2,
      "key_name": "Testing Key",
      "api_key": "cfsd_yyyyyyyyyy",
      "status": "active",
      "request_count": 45,
      "last_used_at": "2025-10-19 14:00:00",
      "created_at": "2025-10-19 11:00:00"
    }
  ]
}
 

3.2 Create API Key

  • Request Parameters:
    • key_name: Key name (string, required)
    • ip_whitelist: IP whitelist (string, optional, comma-separated)
  • Request Example:
 
bash
 
 
 
 
 
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=keys&action=create" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "New API Key",
    "ip_whitelist": "192.168.1.1,192.168.1.2"
  }'
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "message": "API key created successfully",
  "api_key": "cfsd_zzzzzzzzzz",
  "api_secret": "aaaaaaaaaaaaaaaa",
  "warning": "Please save the api_secret, it will not be shown again"
}
 

3.3 Delete API Key

  • Request Parameter: key_id (integer, required)
  • Request Example:
 
bash
 
 
 
 
 
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=keys&action=delete" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": 2
  }'
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "message": "API key deleted successfully"
}
 

3.4 Regenerate API Key

  • Request Parameter: key_id (integer, required)
  • Request Example:
 
bash
 
 
 
 
 
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=keys&action=regenerate" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": 1
  }'
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "message": "API secret regenerated successfully",
  "api_key": "cfsd_xxxxxxxxxx",
  "api_secret": "new_secret_here",
  "warning": "Please save the new api_secret, it will not be shown again"
}
 

4. Quota Inquiry

  • Endpoint: quota
  • Method: GET
  • Request Example:
 
bash
 
 
 
 
 
curl -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=quota" \
  -H "X-API-Key: cfsd_xxxxxxxxxx" \
  -H "X-API-Secret: yyyyyyyyyyyy"
 
 
  • Response Example:
 
json
 
 
 
 
 
{
  "success": true,
  "quota": {
    "used": 3,
    "base": 5,
    "invite_bonus": 2,
    "total": 7,
    "available": 4
  }
}
 

4. Error Handling

Common HTTP Status Codes

Status Code Description
200 Request successful
400 Invalid request parameters
401 Authentication failed
403 Insufficient permissions or function disabled
404 Resource not found
429 Rate limit exceeded
500 Server internal error

Error Response Example

json
 
 
 
 
 
{
  "error": "Invalid API key"
}
 

5. Rate Limiting

  • Default limit: 60 requests/minute
  • Rate limit exceeded response example:
 
json
 
 
 
 
 
{
  "error": "Rate limit exceeded",
  "limit": 60,
  "remaining": 0,
  "reset_at": "2025-10-19 15:31:00"
}
 

6. SDK Examples

PHP Example

php
 
 
 
 
 
<?php
class CloudflareSubdomainAPI {
    private $baseUrl;
    private $apiKey;
    private $apiSecret;
    
    public function __construct($baseUrl, $apiKey, $apiSecret) {
        $this->baseUrl = rtrim($baseUrl, '/');
        $this->apiKey = $apiKey;
        $this->apiSecret = $apiSecret;
    }
    
    private function request($endpoint, $action, $method = 'GET', $data = []) {
        $url = $this->baseUrl . '?m=domain_hub&endpoint=' . $endpoint . '&action=' . $action;
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'X-API-Key: ' . $this->apiKey,
            'X-API-Secret: ' . $this->apiSecret,
            'Content-Type: application/json'
        ]);
        
        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    // List subdomains
    public function listSubdomains() {
        return $this->request('subdomains', 'list', 'GET');
    }
    
    // Register subdomain
    public function registerSubdomain($subdomain, $rootdomain) {
        return $this->request('subdomains', 'register', 'POST', [
            'subdomain' => $subdomain,
            'rootdomain' => $rootdomain
        ]);
    }
    
    // Create DNS record
    public function createDnsRecord($subdomainId, $type, $content, $ttl = 120) {
        return $this->request('dns_records', 'create', 'POST', [
            'subdomain_id' => $subdomainId,
            'type' => $type,
            'content' => $content,
            'ttl' => $ttl
        ]);
    }
}

// Usage example
$api = new CloudflareSubdomainAPI(
    'https://api005.dnshe.com/index.php',
    'cfsd_xxxxxxxxxx',
    'yyyyyyyyyyyy'
);

// List subdomains
$result = $api->listSubdomains();
print_r($result);

// Register new subdomain
$result = $api->registerSubdomain('myapp', 'example.com');
print_r($result);
 

Python Example

<div class="code-block-element

  • 免费域名, api, freedomain, 免费域名api
  • 11 Users Found This Useful
Was this answer helpful?

Related Articles

DNSHE Free Domain Renewal and API Command Renewal Methods

This manual is intended to guide users on how to manually or automatically renew free domains...

DNSHE Free Domain API User Guide (V2.0)

DNSHE Free Domain API User Guide (V2.0) Basic Information API Endpoint:...