🔗 API Reference

Access TLD RDAP/WHOIS data programmatically through our RESTful API endpoints.

📍 Endpoints

GET /status

Get current TLD checking status and progress information.

Example Response:

{
  "web_server": "running",
  "tld_checker_initialized": true,
  "tld_check_status": "completed",
  "results_available": 1440,
  "last_update": "2025-08-16 05:15:23",
  "progress": {
    "status": "completed",
    "current_step": "TLD check completed successfully",
    "total_tlds": 1440,
    "processed_tlds": 1440,
    "last_update": 1723800923.45
  }
}

GET /api/results

Get complete TLD check results with RDAP and WHOIS information.

Example Response:

{
  "results": [
    {
      "tld": "com",
      "rdap_supported": true,
      "rdap_urls": ["https://rdap.verisign.com/com/v1/"],
      "rdap_working": true,
      "working_url": "https://rdap.verisign.com/com/v1/",
      "whois_available": true,
      "whois_server": "whois.verisign-grs.com",
      "stealth_rdap": false,
      "stealth_urls": []
    },
    {
      "tld": "ch",
      "rdap_supported": true,
      "rdap_urls": ["https://rdap.nic.ch/"],
      "rdap_working": true,
      "working_url": "https://rdap.nic.ch/",
      "whois_available": true,
      "whois_server": "whois.nic.ch",
      "stealth_rdap": true,
      "stealth_urls": ["https://rdap.nic.ch/"]
    }
  ],
  "last_update": 1723800923.45,
  "total_tlds": 1440,
  "stealth_metadata": {
    "total_tlds_probed": 246,
    "stealth_tlds_found": 24,
    "discovery_timestamp": 1755505064.1557574,
    "max_tlds_configured": null
  }
}

GET /download/json

Download complete results as JSON file.

GET /download/csv

Download complete results as CSV file. Includes stealth RDAP data in stealth_rdap and stealth_urls columns.

GET /download/summary

Download summary statistics as JSON file. Includes stealth RDAP discovery metrics.

GET /health

Simple health check endpoint.

Example Response:

{
  "status": "healthy",
  "timestamp": 1723800923.45,
  "stealth_count": 24
}

📊 Data Structure

TLD Result Object

Field	Type	Description
`tld`	string	Top-level domain name (without dot)
`rdap_supported`	boolean	Whether RDAP is supported for this TLD
`rdap_urls`	array	List of RDAP server URLs
`rdap_working`	boolean\|null	Whether RDAP endpoint is functional (null if not tested)
`working_url`	string\|null	Functional RDAP URL (if working)
`whois_available`	boolean\|null	Whether WHOIS server is available (null if not tested)
`whois_server`	string\|null	WHOIS server hostname
`stealth_rdap`	boolean	Whether stealth RDAP servers were discovered for this TLD
`stealth_urls`	array	List of discovered stealth RDAP server URLs

Response Metadata

Field	Type	Description
`results`	array	Array of TLD result objects
`last_update`	number	Unix timestamp of last data update
`total_tlds`	number	Total number of TLDs in results
`stealth_metadata`	object	Metadata about stealth RDAP discovery process

Stealth Metadata Object

Field	Type	Description
`total_tlds_probed`	number	Total number of TLDs probed during stealth discovery
`stealth_tlds_found`	number	Number of TLDs with stealth RDAP servers discovered
`discovery_timestamp`	number	Unix timestamp of stealth discovery run
`max_tlds_configured`	number\|null	Maximum TLDs configured for discovery (null if unlimited)

⚡ Rate Limits

• No authentication required for read-only endpoints

• Rate limit: 100 requests per minute per IP

• Large downloads may take several seconds

• Data is updated every 48 hours

💡 Usage Examples

JavaScript/Node.js

// Fetch current status
const response = await fetch('/status');
const status = await response.json();
console.log(`Checked ${status.results_available} TLDs`);

// Get all results
const resultsResponse = await fetch('/api/results');
const data = await resultsResponse.json();
const comData = data.results.find(r => r.tld === 'com');

// Find TLDs with stealth RDAP servers
const stealthTlds = data.results.filter(r => r.stealth_rdap);
console.log(`Found ${stealthTlds.length} stealth RDAP TLDs`);
console.log(`Stealth discovery: ${data.stealth_metadata.stealth_tlds_found}/${data.stealth_metadata.total_tlds_probed}`);

Python

import requests

# Get status
response = requests.get('/status')
status = response.json()
print(f"Status: {status['tld_check_status']}")

# Get results with stealth data
results_response = requests.get('/api/results')
data = results_response.json()

# Analyze stealth RDAP data
stealth_tlds = [r for r in data['results'] if r['stealth_rdap']]
print(f"Stealth TLDs found: {len(stealth_tlds)}")
print(f"Discovery rate: {data['stealth_metadata']['stealth_tlds_found']}/{data['stealth_metadata']['total_tlds_probed']}")

# Download CSV data (includes stealth columns)
csv_response = requests.get('/download/csv')
with open('tld_data.csv', 'wb') as f:
    f.write(csv_response.content)

cURL

# Check status
curl -X GET "/status"

# Download JSON data
curl -X GET "/download/json" -o tld_data.json

# Get results with pretty formatting
curl -X GET "/api/results" | jq .