API Documentation
Programmatic access to WHOIS/RDAP domain intelligence data.
Authentication
All API requests require an API key. Generate one from My Settings.
Pass your key via the X-API-Key header (recommended) or the api_key query parameter:
Header Authentication
curl -H "X-API-Key: whois_your_api_key_here" \ https://whois.cx/api/v1/whois/google.com
Query Parameter
curl "https://whois.cx/api/v1/whois/google.com?api_key=whois_your_api_key_here"
Security: Always use the header method when possible. Never expose your API key in client-side code or URLs that may be logged.
Endpoints
Base URL: https://whois.cx/api/v1
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/whois/{domain} |
WHOIS/RDAP lookup for a domain |
| GET | /v1/account |
Your API key info and usage stats |
WHOIS Lookup
GET
/v1/whois/{domain}
Look up WHOIS/RDAP registration data for a domain name.
Parameters
| Parameter | Type | Location | Description |
|---|---|---|---|
domain |
string | path | Required. Domain name (e.g., google.com, example.co.uk) |
Response
200 OK
{
"domain": "google.com",
"registrar": "MarkMonitor Inc.",
"registrar_iana_id": "292",
"registrar_abuse_email": "[email protected]",
"creation_date": "1997-09-15T04:00:00Z",
"updated_date": "2019-09-09T15:39:04Z",
"expiry_date": "2028-09-14T04:00:00Z",
"nameservers": [
"ns1.google.com",
"ns2.google.com",
"ns3.google.com",
"ns4.google.com"
],
"status": [
"client delete prohibited",
"client transfer prohibited",
"client update prohibited",
"server delete prohibited",
"server transfer prohibited",
"server update prohibited"
],
"dnssec": "unsigned",
"_meta": {
"protocol": "rdap",
"duration_ms": 245
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
domain | string | Queried domain name |
registrar | string | Domain registrar name |
registrar_iana_id | string | Registrar's IANA accreditation ID |
registrar_abuse_email | string | Registrar abuse contact email |
creation_date | string | Domain registration date (ISO 8601) |
updated_date | string | Last modification date (ISO 8601) |
expiry_date | string | Domain expiration date (ISO 8601) |
nameservers | array | List of DNS nameservers |
status | array | Domain status codes (EPP format) |
dnssec | string | DNSSEC status |
registrant_name | string | Registrant name/organization (if available) |
registrant_country | string | Registrant country (if available) |
available | boolean | Whether the domain appears unregistered |
_meta.protocol | string | Protocol used: rdap, whois, or hybrid |
_meta.duration_ms | integer | Server-side lookup duration in ms |
Note: Fields with no data are omitted from the response. Only non-null, non-empty values are returned.
Account Info
GET
/v1/account
Retrieve information about your API key, including usage stats and current rate limit status.
Response
200 OK
{
"key_name": "My App",
"key_prefix": "whois_a1b2c3",
"total_requests": 1542,
"rate_limits": {
"1m": 10,
"1h": 200,
"1d": 2000
},
"rate_usage": {
"1m": {"limit": 10, "used": 3, "remaining": 7, "reset": 1709740800},
"1h": {"limit": 200, "used": 45, "remaining": 155, "reset": 1709740800},
"1d": {"limit": 2000, "used": 312, "remaining": 1688, "reset": 1709769600}
},
"created_at": "2025-01-15 10:30:00"
}
Rate Limits
API requests are rate-limited across three time windows:
| Window | Default Limit | Description |
|---|---|---|
| Per Minute | 10 | Short-burst protection |
| Per Hour | 200 | Medium-term limit |
| Per Day | 2,000 | Daily quota |
Rate limit info is included in response headers:
Response Headers
X-RateLimit-Limit: 10 X-RateLimit-Remaining: 7 X-RateLimit-Reset: 1709740800
When a rate limit is exceeded, you'll receive a 429 Too Many Requests response:
429 Too Many Requests
{"error": "Rate limit exceeded. Try again in 45s"}
Error Codes
| Status | Meaning | Description |
|---|---|---|
200 | OK | Successful lookup |
400 | Bad Request | Invalid domain format |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | API key revoked or API disabled |
404 | Not Found | Domain not found / unsupported TLD |
429 | Too Many Requests | Rate limit exceeded |
500 | Server Error | Internal lookup failure |
All error responses follow this format:
Error Response
{"error": "Description of what went wrong"}
Code Examples
cURL
# Lookup a domain curl -H "X-API-Key: whois_your_key" \ https://whois.cx/api/v1/whois/google.com # Check account status curl -H "X-API-Key: whois_your_key" \ https://whois.cx/api/v1/account