OAuth 2.0
Pirehub uses Clerk as its OAuth 2.0 authorization server and supports Authorization Code with PKCE. Start discovery from either metadata document:https://clerk.ntanduy.com. Send the resulting access token in the standard header:
https://www.ntanduy.com/.well-known/oauth-protected-resource/mcp.
For MCP connection settings, Claude/ChatGPT/Codex setup, tool-to-scope mappings and download/crawl workflows, see
Connect an AI agent with MCP. Send the credential in the MCP request
headers; the server forwards it to the scoped API and retains the same ownership
and quota checks. Video continuation tools use the issued job/media capability instead; they never forward the API key to the download gateway.
API keys
Use an issued Pirehub API key with the scope required by the endpoint. The recommended method is thex-pirehub-api-key header:
WHOIS requires
domain:whois, DNS requires domain:dns, IP information requires
ip:lookup, video extraction requires video:extract, and server-to-server Bank
QR generation requires bank-qr:generate. Reading the supported bank directory
requires bank-qr:banks. Website capture requires screenshot:capture and
social oEmbed resolution requires oembed:read. Web search, page extraction,
URL discovery and crawling require web:search, web:scrape, web:map and
web:crawl respectively. A valid
OAuth token or API key without the endpoint’s required scope returns HTTP 403.Self-service API plans
Sign in and open Developer API keys to purchase a paid API plan and manage your own keys. There is no free public API-key plan. The dashboard shows the current price, billing interval, included capabilities, credit allowance, active-key limit, request rate and concurrency limits before purchase. Each purchase starts a new billing period and replaces the previous plan; unused credits do not carry over. Automatic renewal is off until you explicitly enable it in Manage API plan and approve the agreement with Stripe or PayPal. The first recurring charge is due at the end of the paid period. Each verified renewal payment grants a new credit allowance for the next billing period. One-time purchases use the payment methods available for your billing currency, including NOWPayments when supported; crypto payments do not enable automatic renewal. Self-service keys share one owner subscription credit pool. Creating or rotating another key never multiplies the allowance. Your key’s scopes and the purchased plan’s capabilities must both permit the operation. Administrator privileges do not waive the paid entitlement. Cancellation preserves access until the displayed period end; expired subscriptions leave keys in place for later reactivation. Only the creation/rotation response reveals the secret. Copy it immediately; it cannot be retrieved later. Self-service rotation revokes the old key immediately. Existing administrator-issued keys retain their configured request quota, expiry, scopes and rotation contract. Contact support for changes to an issued key.Credits and execution
View your plan, usage allowance and current operation costs in Developer API keys.X-ApiKey-Credit-Cost reports the cost applied to a request. Capture options such as
full-page mode, includePostVariants=true, pixelRatio=3, or delay=5000 can select
a different operation cost; extended capture takes precedence over full-page.
Credits are reserved before execution and consumed on a successful response
(including a cache hit). Authentication, scope, entitlement, validation, rate limit,
and execution failures do not consume credits. Video jobs keep a reservation
until completion and settle before publishing a successful result. Pending
reservations reduce available credits; abandoned reservations expire. Video HTTP
202 is admission, not a completed charge. Web crawl submission is billed on
successful admission, including HTTP 202, and later failure/cancellation does not
automatically refund it. Each successful crawl read or cancellation is a separate
operation. See
Web data for its request deduplication and polling contract.
Idempotency
For self-service keys, send an optionalIdempotency-Key header containing 1–80
ASCII letters, digits, _ or -. A repeated key is scoped to the owner and bound
to the method, route, query and JSON payload. Reuse returns HTTP 409 without another
execution or debit; responses are not replayed. Use a new value for genuinely new
work, including retrying a failed operation. Keep request fields and ordering
unchanged when checking the same operation. Without the header, synchronous
requests are separate billable operations. Video job starts instead use the
existing per-key requestId; changing the header cannot charge that job again.
Do not retry an operation under a new identifier merely because its response was lost.
If admission returns USAGE_CONCURRENCY_EXCEEDED, execution has not started and
no new credit reservation is retained. Wait for capacity, then retry with the same
identifier and unchanged request. Once execution starts, the reuse rules above apply.
Paid-key headers and failures
Self-service limits use a one-second sliding window, per key and shared owner.X-ApiKey-RateLimit-Window: 1 distinguishes this from administrator keys’ minute
window. X-ApiKey-Credit-Limit reports the purchased period allowance and
X-ApiKey-Credit-Reset its actual end as Unix seconds. Credits do not reset on
calendar-month boundaries or after a fixed 30 days. Self-service keys do not
return per-key X-ApiKey-Monthly-* quota headers.
First-party browser verification
Verification for Pirehub’s website tools is managed automatically by the website. It is not an API authentication method for external integrations. Use OAuth or a scoped API key when calling the documented endpoints from your application.Keep keys secure
- Store keys in a secret manager or environment variable.
- Never include a key in a query string, client-side bundle, source control, or log.
- Use a separate key for each integration so it can be revoked independently.
- Rotate a key immediately if it may have been exposed.
Authentication failures
Administrator-issued key rate limits and monthly request quotas are specific to each key; inspect
X-ApiKey-* headers. First-party browser requests return X-RateLimit-* headers.
For administrator-issued key requests, RATE_LIMITED uses data.reason: "per_minute", while
MONTHLY_QUOTA_EXCEEDED uses data.reason: "monthly_quota". Both include the
applicable limit, remaining, resetAt, retryAfter, and requestId. Browser
or upstream throttling may omit the API-key-specific fields. Honor Retry-After
when present, and see Errors and retries for exact response
examples and recovery guidance.
Request timing
API-key responses may include optional diagnostics inServer-Timing (durations
in milliseconds): api_key_parse_ms, api_key_lookup_ms, api_key_verify_ms,
scope_ms, runtime_snapshot_ms, quota_ms,
credit_reserve_ms, provider_ms, credit_finalize_ms, api_key_pre_provider_ms
and total_ms. Stages that do not apply are omitted, for example paid billing
stages on an administrator-issued key. api_key_cache describes the lookup path.
For paid keys, api_key_lookup_ms includes the fresh credential, owner, subscription,
entitlement and capability read. runtime_snapshot_ms covers request parsing and
validation of that snapshot. api_key_pre_provider_ms includes the admission stages,
so do not sum every field.
provider_ms covers endpoint work after admission, including validation and
result-cache access. It is not an isolated upstream network measurement.
total_ms measures server time before sending the response; client network time
and background activity logging are excluded. These diagnostics do not change
billing, quotas or the response body and are not a latency guarantee.