Inspector API documentation

Domain Intelligence API

POST a JSON object containing your API key and a domain or subdomain. Use a domain name without a URL path.

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"}'

Response fields

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",
  "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
}

Example: no analysis record

{
  "subject": "unknown.example",
  "domain": "unknown.example",
  "verdict": "Unknown",
  "data_available": false,
  "score": null,
  "reputation": null,
  "category": null,
  "tags": null,
  "date": null,
  "fingerprint": null,
  "whitelisted": false,
  "report": null
}

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.

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.

How to use?

You need to use the HTTP POST method, sending your data in the form of a JSON object within the body of the request.

Each successful scan costs 10 credits. API errors do not consume credits.

Request:

Field	Type	Description
apikey	String	Your unique API key that authenticates requests to our services.
url	String	A full HTTP or HTTPS URL, including its path when relevant

Example:

You can use various tools or libraries to make this POST request. Here’s how you might typically do it using curl, a command-line tool:

curl -X POST 'https://inspector.gridinsoft.com/api/v1/url/scan' \
    -H 'Content-Type: application/json' \
    -d '{
    "apikey": "YOUR_PRIVATE_APIKEY",
    "url": "https://example.com/path"
    }'

Response:

The JSON response has metadata, security and analysis blocks. Individual fields can be null or empty when information could not be obtained; a missing finding is not a guarantee of safety.

Field	Type	Description
url	String	The input URL that was analyzed.
metadata	Object	Basic information about the page, including title, description, language, and categories.
security	Object	Critical security indicators: verdict: Available assessment object from Gridinsoft, or null. effective_url: Final destination after all redirects. redirect_chain: Available redirect information. antiviruses_detection: Aggregated detection stats from multiple engines. dns_records: Available DNS records; not a complete DNS history. certificate: Detailed SSL/TLS info (SANs, validity, issuer). jarm & reputation: Advanced technical fingerprints and scores.
analysis	Object	Additional captured analysis. Available for paid users only; this block is null on the free plan. Individual artifacts may be absent. screenshots: Visual captures (PC & Mobile). network_requests: Captured network request data, when available. cookies & console_logs: Browser environment details. urls_in_html: Available links extracted from the page source.

Response example

Illustrative excerpt using example.com; fields not shown are omitted for readability.

{
  "url": "https://example.com/path",
  "metadata": {"title": "Example page", "description": "", "categories": [], "language": "en"},
  "security": {"effective_url": "https://example.com/path", "redirect_chain": null, "verdict": null},
  "analysis": null
}

A null verdict is unavailable evidence, not a clean verdict. The analysis block is null on a free plan. On paid plans, inspect each artifact for availability before using it.

Allow for variable response times. A full scan can take several seconds or longer; handle HTTP errors and timeouts in your client.

How to use?

You need to use the POST request with the file data and your API key. The request should be formatted as 'multipart/form-data'.

Each successful check costs 5 credits. API errors do not consume credits.

Request:

Field	Type	Description
apikey	String	Your unique API key that authenticates requests to our services.
file	File	The file to be checked, uploaded as multipart/form-data.

Example:

curl -X POST https://inspector.gridinsoft.com/api/v1/file/check \
     -H 'Content-Type: multipart/form-data' \
     -F 'apikey=YOUR_PRIVATE_APIKEY' \
     -F 'file=@/path/to/your/file'

Response:

Field	Type	Description
sha256	String	SHA-256 hash of the file.
md5	String	MD5 hash of the file.
filename	String	Name of the file.
size	Integer	Size of the file in bytes.
detection	String	Detection label, or Clean when no detection was returned. Clean is not a guarantee that a file is safe.
type	String	Available PE identification signatures, or null.
heuristic	Object	Contains malicious and harmless flags for this result. Available detailed criteria appear in heuristic.analysis on Premium; otherwise that field is null.
PE	Object	PE data in an executable (EXE) file refers to the Portable Executable format, which is a file format for executables, object code, DLLs, FON Font files, and others used in 32-bit and 64-bit versions of Windows operating systems. Available PE data is included on paid plans; it may be null when not applicable or unavailable.

How to use?

You need to use the HTTP POST method, sending your data in the form of a JSON object within the body of the request.

Each successful check costs 2 credits, including inconclusive results. API errors do not consume credits.

Request:

Field	Type	Description
apikey	String	Your unique API key that authenticates requests to our services.
email	String	The email address you want to validate.

Example:

You can use various tools or libraries to make this POST request. Here's how you might typically do it using curl, a command-line tool:

curl -X POST 'https://inspector.gridinsoft.com/api/v1/email/check' \
    -H 'Content-Type: application/json' \
    -d '{
    "apikey": "YOUR_PRIVATE_APIKEY",
    "email": "[email protected]"
    }'

Response:

Field	Type	Description
verdict	String	Validation result: "VALID", "INVALID", "NON_EXISTENT", "RISKY", or "UNKNOWN".
message	String	Human-readable description of the validation result.
checks	Object	Detailed checks; account can be null when the SMTP result is inconclusive.
checks.format	Boolean	Whether the email has a valid format.
checks.service	Boolean	Whether the domain exists and has MX records.
checks.account	Boolean or null	SMTP recipient result: true for accepted, false for rejected, null for inconclusive. Acceptance does not prove the mailbox exists or that delivery will succeed.
checks.disposable	Boolean	Whether the email domain is a known disposable/temporary email provider.
checks.spam	Boolean	Whether the domain is listed in spam blacklists (DNSBL).
mx_records	Array	List of MX servers found for the email domain.
account_status	String	accepted, rejected or unknown when an SMTP check is performed. Can be absent for early validation failures.
details	Array	SMTP conversation details for debugging purposes.

Example: inconclusive mailbox check

Illustrative response excerpt. A server timeout or policy restriction must not be interpreted as a nonexistent mailbox.

{
  "verdict": "UNKNOWN",
  "account_status": "unknown",
  "checks": {
    "format": true,
    "service": true,
    "account": null,
    "disposable": false,
    "spam": false
  }
}

Catch-all servers may accept recipients that do not have individual mailboxes. Use address confirmation when proof of ownership or deliverability is required.

How to Use?

Request:

Use the following parameters to customize your search:

Field	Type	Required	Description
apikey	String	Yes	Your unique API key that authenticates requests to our services.
q	String	Yes* (for simple search)	The search query (part or whole domain name, IP address, tags, etc.).
domain	String	No* (for advanced search)	Search by domain name. Supports partial matching.
detect	String	No* (for advanced search)	Search by detection category (e.g., "Scam Website", "Phishing").
tags	String	No* (for advanced search)	Search by tags (e.g., "Cryptocurrency", "Shopping").
fingerprint	String	No* (for advanced search)	Search by fingerprint hash or pattern.
hosts	String	No* (for advanced search)	Search by IP address.
p	Integer	No	The page number of the results (used for pagination).
limit	Integer	No	The number of results to return per page (defaults to 10).

* Either 'q' for simple search OR at least one advanced search parameter (domain, detect, category, tags, fingerprint, hosts) must be provided.

Examples:

Simple Search:

curl -X GET "https://inspector.gridinsoft.com/api/v1/domain/search?apikey=YOUR_PRIVATE_APIKEY&q=example&p=1&limit=10" \
     -H "Accept: application/json"

Advanced Search:

curl -X GET "https://inspector.gridinsoft.com/api/v1/domain/search?apikey=YOUR_PRIVATE_APIKEY&detect=Scam%20Website&domain=.xyz&p=1&limit=10" \
     -H "Accept: application/json"

Response:

The response includes pagination details and an array of enriched domain objects.

Response Structure:

Field	Type	Description
search_type	String	Type of search performed ("simple" or "advanced").
p	Integer	Current page number.
limit	Integer	Maximum results per page.
total	Integer	Total number of records matching the query.
results	Array	List of domain objects (see below).

Domain Object Fields:

Field	Type	Description
domain	String	The domain name.
date	String	Timestamp of the last database update.
verdict	String	Security status ("Safe", "Suspicious", "Malicious").
reputation	Integer	Security score (0-100). Higher is safer.
fingerprint	String	Behavioral fingerprint hash.
report	String	Link to the full interactive virus report.
hosting	Object	Server information (IP, Provider, Location).
whois	Object	Registration data (Registrar, Created/Expires dates).
site	Object	Website metadata and risk-based categorization tags.

Simple Search Response:

Simple search includes the q field containing your original query string.

{
    "search_type": "simple",
    "q": "gridinsoft.com",
    "results": [ ... ],
    "p": 1,
    "limit": 10,
    "total": 9
}

Advanced Search Response:

Advanced search replaces q with a params object containing all filters applied.

{
    "search_type": "advanced",
    "params": {
        "detect": "Malware",
        "domain": ".xyz"
    },
    "results": [ ... ],
    "p": 1,
    "limit": 10,
    "total": 25
}

Each result will provide detailed information about the domain, including hosting details, WHOIS data, and site metadata.