Skip to main content

​
Base URL and versioning

The API version is part of the URL. A future incompatible version will use a new version segment so your existing integration does not change unexpectedly. JSON endpoints accept and return JSON. Send Content-Type: application/json for requests with a body. Binary endpoints document their response media type explicitly; for example, video preview returns image bytes.

​
Success envelope

Successful JSON endpoints return a consistent top-level envelope:
Endpoint-specific fields are nested in data. For WHOIS responses, data.meta reports cache state. Video extraction responses expose only normalized metadata, internal preview URLs, and opaque download tokens. Binary responses such as video preview do not use this JSON envelope.

​
Error envelope

Use the machine-readable error.code for program logic and the safe error.message for display. data.requestId is an opaque correlation ID for support and log lookup; do not branch on it. See Errors and retries for the complete handling guide.

​
Endpoint security

Security requirements differ by endpoint:
  • WHOIS, DNS, IP information, video extraction, screenshot capture, social oEmbed, and Bank QR endpoints accept OAuth 2.0 access tokens or scoped Pirehub API keys for agent and server use.
  • Bank QR generation requires bank-qr:generate; reading the bank directory requires bank-qr:banks.
  • Website verification is handled automatically by Pirehub’s tools. External integrations authenticate with OAuth or an API key.
See Authentication before integrating an endpoint.

​
Domain-not-found behavior

A valid lookup for an unregistered domain is not an API error. It returns HTTP 200, success: true, and data.registered: false.

​
Privacy and provider isolation

WHOIS output is normalized and sanitized. Raw provider messages, email addresses, registrant names, and upstream WHOIS server details are not returned. DNS output contains normalized resolver results rather than raw provider responses. IP information is allowlisted to the documented location, network, and timezone fields. Video extraction does not expose provider identifiers, upstream media URLs, provider headers, or raw responses. Bank QR images are rendered locally; only the independent bank-directory refresh contacts its upstream metadata service, and submitted transfer details are not included in that request.

​
Rate-limit headers

Use response headers as the authoritative source. API-key endpoints return X-ApiKey-* headers, while browser-facing public endpoints return X-RateLimit-* headers. An HTTP 429 can represent either a short per-minute limit (RATE_LIMITED) or an exhausted monthly API-key quota (MONTHLY_QUOTA_EXCEEDED). Do not branch on the HTTP status alone. See Errors and retries for all documented 429 response shapes, including browser and upstream throttling.