Domain Intelligence API
POST a JSON object containing your API key and a domain or subdomain. Use a domain name without a URL path. A leading www. is removed before the lookup: www.example.com checks example.com. Other subdomains are checked individually by default. The subject and domain fields contain the normalized requested name, even when a parent assessment is returned.
3 credits per successful check, including Unknown results. API errors do not consume credits.
curl -X POST 'https://inspector.gridinsoft.com/api/v1/domain/check' \
-H 'Content-Type: application/json' \
-d '{"apikey":"YOUR_PRIVATE_APIKEY","domain":"example.com"}'
Optional parent-domain fallback
Set parent_fallback to the JSON boolean true to use an existing parent assessment when the requested domain has none. The default is false; strings, numbers and null are not accepted for this parameter. The closest parent with an assessment wins, whether that assessment is Safe or a threat classification. For example, a.b.example.co.jp is checked first, then b.example.co.jp, then example.co.jp. The search stops at the registrable domain and never inherits from a public suffix such as com or co.jp. Unknown suffixes are checked exactly, without parent fallback.
This opt-in also permits a hosting provider's assessment: customer.cloudfront.net may return an assessment of cloudfront.net. That is context about the provider, not a direct assessment or guarantee about the customer's content. The source is always identified in assessment_domain.
curl -X POST 'https://inspector.gridinsoft.com/api/v1/domain/check' \
-H 'Content-Type: application/json' \
-d '{"apikey":"YOUR_PRIVATE_APIKEY","domain":"a.b.example.com","parent_fallback":true}'
The entire successful request still costs 3 credits, including all parent checks and Unknown results. No fresh analysis is guaranteed. Parent lookup has a shared 10-second analysis-service budget in addition to the original lookup; incomplete lookups return an error without a charge. An inherited assessment describes the parent, not a direct analysis of the requested subdomain. Use assessment_domain and assessment_match to retain that distinction in your reports.
Response fields
| Field | Meaning |
|---|
| subject, domain | The normalized domain that was checked. |
| assessment_domain | The domain whose assessment supplied the result, or null for Unknown. A parent result keeps the requested subject and domain unchanged. |
| assessment_match | exact for an assessment of the normalized requested name, parent for an inherited assessment, or none when no assessment was found. With parent, all assessment fields (including date, score, whitelist status and report) refer to assessment_domain. |
| platform | Local service-directory context for the normalized requested domain, independent of its assessment. Contains matched, types, matched_suffix, provider and registry_version. Always present; unmatched domains have false, an empty types array, and null suffix/provider. |
| verdict | A category such as Safe, Phishing, Adware Distributor or Unknown. Safe means an available assessment found no classified threat; it is not a guarantee of safety. Do not assume there are only three possible verdict strings. |
| data_available | Boolean. False means there is no usable assessment; it does not mean safe. |
| score, reputation | Aliases for the available reputation score (0–100, higher is better), or null. This is not a probability or confidence percentage. |
| category | Available category identifier, or null. Zero is a valid category (Adult Content), not a missing value. |
| tags | Available category or behavior tags, or null. |
| date | Date of the available assessment, when known; otherwise null. A null date does not invalidate an available verdict or category. Use data_available to distinguish an assessment from no data. The date is not the time of this request. |
| fingerprint | Available fingerprint value, or null. |
| whitelisted | Whether the available assessment marks the domain as whitelisted. |
| report | Available report reference, or null. |
Example: a classified domain
Illustrative response using a reserved example domain. This is a format example, not a finding about a real website.
{
"subject": "download.example",
"domain": "download.example",
"assessment_domain": "download.example",
"assessment_match": "exact",
"verdict": "Unwanted Application Distributor",
"data_available": true,
"score": 15,
"reputation": 15,
"category": 8,
"tags": null,
"date": "2026-09-27 12:00:00",
"fingerprint": null,
"whitelisted": false,
"report": null,
"platform": {
"matched": false,
"types": [],
"matched_suffix": null,
"provider": null,
"registry_version": "2026-10-26.5"
}
}
Example: no analysis record
{
"subject": "unknown.example",
"domain": "unknown.example",
"assessment_domain": null,
"assessment_match": "none",
"verdict": "Unknown",
"data_available": false,
"score": null,
"reputation": null,
"category": null,
"tags": null,
"date": null,
"fingerprint": null,
"whitelisted": false,
"report": null,
"platform": {
"matched": false,
"types": [],
"matched_suffix": null,
"provider": null,
"registry_version": "2026-10-26.5"
}
}
Handle Unknown separately from Safe. Optional context may be null even when a verdict is available. A missing verdict does not guarantee that a new analysis will be completed during the lookup.
Example: inherited assessment
{
"subject": "a.b.example.com",
"domain": "a.b.example.com",
"assessment_domain": "example.com",
"assessment_match": "parent",
"verdict": "Safe",
"data_available": true,
"score": 95,
"reputation": 95,
"category": -1,
"tags": null,
"date": "2026-10-25 12:00:00",
"fingerprint": null,
"whitelisted": false,
"report": null,
"platform": {
"matched": false,
"types": [],
"matched_suffix": null,
"provider": null,
"registry_version": "2026-10-26.5"
}
}
Platform and service context
The platform object is included automatically, including for Unknown results and with parent fallback disabled. Matching uses complete DNS labels and the closest matching suffix. Provider may be null when only an infrastructure category is known. Registry entries describe a service association; they do not prove a hostname is active, its precise purpose, or that it is safe. They never change verdict, score, whitelist status, assessment availability or the 3-credit request cost. With parent fallback, platform still describes the requested hostname, not assessment_domain.
Inspector shows platform and service labels separately from the assessment. New history records save the platform snapshot and registry version at check time. Older records show Context not recorded; they are never silently reclassified as historical facts. History distinguishes a saved no-match result from missing context. Expand a history row to inspect the saved matched zone and registry version.
The directory covers provider domain families, including CDN, cloud hosting, SaaS, authentication and dynamic DNS platforms. New subdomains at any depth under a listed zone are recognized without adding individual hostnames. Curated provider records retain official source references and review dates. Matching is local and does not resolve CNAMEs; a customer-owned custom domain needs its own assessment or registry entry.
Types currently include hosted_tenant, hosting_provider, shared_infrastructure, customer_support, authentication, analytics, site_search, advertising, web_fonts, marketing_automation, error_monitoring, video_hosting and content_delivery. Multiple types can apply. Consumers should accept future types and registry versions.
Example of the platform field for a hostname under ada.support (service context only):
{
"platform": {
"matched": true,
"types": ["customer_support"],
"matched_suffix": "ada.support",
"provider": "Ada",
"registry_version": "2026-10-26.5"
}
}
Errors and timing
Handle HTTP 400 (invalid input), 401 (authentication), 405 (method), 429 (insufficient credits), and 5xx errors. Response times vary; use timeouts and bounded retries for transient errors. Check your credit balance before retrying a 429 response.
Service coverage includes site search (Algolia, Coveo, Searchspring, Swiftype, Typesense, Doofinder), web fonts, video delivery and browser error monitoring. Specific service hostnames are used where a provider also operates unrelated services. Labels describe service context, not proof of activity or request contents.
