Making requests: API v4

The Website Categorization API v4 classifies a domain into the IAB Content Taxonomy v3.1. This page covers the base URL, authentication, the request body, and the optional inputs that change what comes back.

Base URL

https://website-categorization.whoisxmlapi.com/api/v4

All examples on this page are relative to that base.

Authentication

Pass your API key as the apiKey query parameter. It is not a header and not a bearer token:

POST /api/v4/categorize?apiKey=YOUR_API_KEY

You authenticate with your existing WhoisXML API key: Website Categorization has no separate subscription or dashboard. Every request is validated against your WhoisXML account for an active subscription and an available credit balance before it is processed. An invalid key, an expired subscription, or a zero balance all return 403 — see Error codes.

Your first request

POST only. A GET to /api/v4/categorize returns 405 Method Not Allowed. The domain goes in the JSON body; apiKey stays a query parameter.

curl -X POST "https://website-categorization.whoisxmlapi.com/api/v4/categorize?apiKey=YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domain": "stackoverflow.com"}'

The response shape is covered in full on Output format.

Request body

Only domain is required.

Field Type Required Description
domain string Yes The domain to categorize, for example example.com. Max 253 chars.
url string No Full URL, if you have one. Max 2,048 chars.
title string No Page title. Max 2,048 chars.
description string No Meta description. Max 4,096 chars.
body_text string No Page body text. Max 20,000 chars; truncated for classification.
skip_cache boolean No Defaults to false. Set true to force a fresh classification.

Supplying your own content. If you already hold the page — title, description and body_text — pass it. The service uses what you send instead of fetching the site, which removes the crawl from the critical path and is markedly faster. domain on its own is enough; everything else is optional.

Query parameters

Parameter Type Default Description
apiKey string — Required. Your API key.
output_mode string top1 top1 or set. set appends a calibrated prediction_set.
coverage string (numeric) 0.60 Coverage target for output_mode=set, between 0.01 and 0.99. Ignored for top1.
output_format string — openrtb appends an AdCOM-shaped openrtb object. Omit for the default response.
include string — Comma-separated opt-in blocks: policy, safety, content_purpose.
pack string policy_v1 policy_v1, policy_v2 or policy_v3. Ignored when include omits policy.
include_status boolean false true appends the domain-status block.

output_mode, coverage and output_format apply to POST /api/v4/categorize only. The bulk endpoint accepts apiKey, include, pack and include_status; other parameters are ignored rather than rejected. The async batch endpoint accepts apiKey only and ignores any other query parameter.

Each opt-in block is documented on its own page or section: Policy pack, Content purpose and Safety (sections of Output format), Domain-status fields, OpenRTB output.

The opt-ins are independent — you can combine them on one request.

Retrying with an Idempotency-Key

Send an Idempotency-Key request header if your client may retry on timeout. A repeated request carrying the same key within a 24-hour window is processed again (usually from the cache) but normally charges credits_charged: 0 if an earlier request with that key was already billed. A retry after a 429 or 503 bills normally. On async batch submission, a repeat with the same key returns the original job.

curl -X POST "https://website-categorization.whoisxmlapi.com/api/v4/categorize?apiKey=YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 7c1f9a10-3d2b-4e6a-9f11-0b8c2d5e4a37" \
     -d '{"domain": "stackoverflow.com"}'

Use a stable key per logical request, not a fresh one per attempt.

Caching and freshness

Successful classifications are cached for up to 30 days. The window is shorter for categories whose label depends on what was on the page that day: 7 days for entertainment, pop culture and sports, and 3 days for event-driven categories (crime, disasters, events, politics, war and conflicts). A repeat request inside the window returns the cached result, which is considerably faster than a fresh classification because it does not re-run the crawl and model pipeline. A cached call still returns a result and is billed the same as a fresh one.

To force a fresh classification, set "skip_cache": true in the request body.

Reference data — the taxonomy tree

curl "https://website-categorization.whoisxmlapi.com/api/v4/taxonomy?apiKey=YOUR_API_KEY"

Returns the full IAB Content Taxonomy v3.1 tree — 704 categories across four tiers. This call validates your key but charges no credits. The default tree changes only on a major taxonomy version bump, so cache it client-side. See Categories.

Request identifiers

Every response, successful or not, carries an X-Request-ID header. Include it when you contact support about a specific call — it locates the request in our logs without you sharing your API key.

Larger volumes

For up to 100 domains in one synchronous call, and for background jobs of up to 10,000 domains, see Bulk and async jobs.

Need help?

Email support@whoisxmlapi.com. Include your account email, the request URL or curl command, the response body with your API key redacted, and the X-Request-ID header from the failed response.