Skip to main content
Pirehub WHOIS accepts a domain, subdomain, or URL and returns normalized public registry data. Provider-specific payloads and personal WHOIS contact fields are removed from the response.

What you can retrieve

Registry data is best-effort. Optional values may be null or absent when the registry does not provide them.

Accepted input

The API normalizes the hostname before performing the lookup: The original normalized hostname remains available as query_domain, while domain contains the registrable root domain.

Authentication

POST /api/v1/domain/whois accepts a Pirehub API key with the domain:whois scope for server-to-server integrations. Send the key in x-pirehub-api-key or as a bearer token. See Authentication for OAuth support and credential handling.

Lookup request

Lookup response

An unregistered domain is not an API error. A completed lookup returns HTTP 200 with success: true and data.registered: false.

Cache and fresh lookups

Normal requests may use cached registry data for faster, more reliable responses. Inspect data.meta to understand the result:
  • cached: true means the response was served from cache.
  • stale: true means cached data was returned because a fresh provider lookup failed.
Set forceRefresh: true only when you need to attempt a new upstream lookup. If the provider is unavailable and cached data exists, the API may still return the cached result with stale: true.

Limits and failures

Administrator-issued API keys use the per-minute and monthly request limits configured for that key. Inspect X-ApiKey-RateLimit-* and X-ApiKey-Monthly-* response headers. First-party browser requests without an API key use the public per-IP limit and return X-RateLimit-* headers. Invalid input returns VALIDATION_ERROR. Provider failures may return 502, 503, or 504; honor Retry-After when present and retry with bounded backoff.

Next steps

WHOIS endpoint

Review the complete request and response schema.

Authentication

Learn about scopes and credential handling.

Errors and retries

Handle failures safely and predictably.

Subscription-backed API keys

Paid self-service keys use shared owner credits and the plan’s per-second and concurrent-job limits. Successful results, including cache hits, consume the configured action cost; errors release the reservation. Video jobs settle at completion. Inspect X-ApiKey-Credit-* and X-ApiKey-RateLimit-*. An optional Idempotency-Key prevents repeated synchronous execution/debits; repeated operations return 409 rather than replaying a response. Job starts use requestId instead. See API plans and idempotency for costs, billing periods, headers, error codes and retry rules.