DomainTools Real-Time Feeds API Reference¶
Version 0.1.1
Real-Time Threat Intelligence Feeds provide data on the different stages of the domain lifecycle: from first-observed in the wild, to newly re-activated after a period of quiet. Access current feed data in real-time or retrieve historical feed data through separate APIs. Some feeds also offer data for DNS firewalls in Response Policy Zone (RPZ) format.
Servers¶
https://api.domaintools.com - DomainTools API endpoint
Authorization¶
API Key¶
Header-based authentication using your DomainTools API key.
For example: curl -H 'X-Api-Key: MY_API_KEY' 'https://api.domaintools.com/v1/feed/nod/?sessionID=mySIEM'
In: header
Name: X-API-Key
HMAC¶
HMAC SHA1-based authentication. Clients must send three query parameters on each request:
-
api_username(your HMAC API username) -
timestamp(current UTC time in ISO 8601 format) -
signature(HMAC SHA1 ofapi_username + timestamp + request_path, hex‐encoded)
In: query
Name: signature
HTTP Basic¶
HTTP Basic Authentication using your DomainTools API username as the username, and API key as the password.
Scheme: basic
Domain Discovery Feed¶
New domains as they are either discovered in domain registration information, observed by our global sensor network, or reported by trusted third parties.
/v1/feed/domaindiscovery/ (GET)¶
Returns data from the real-time Domain Discovery feed.
Each session requires a sessionID.
appParter, appName, appVersion are optional
Example query:
Operation ID: getDomainDiscovery
Parameters¶
domain (string)¶
In: query
Required: false
Description:
Filter for an exact domain or a domain substring by prefixing or suffixing your string with *.
Multiple parameters are supported: e.g., ?domain=*apple*&domain=*mic*.
The URL-encoded version of * (%2A) may be required in some clients.
See full documentation.
Validation Rules:
- Min Length:
1 - Max Length:
253 - Pattern:
^\*?[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\.?$|^[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\*\.?$
Schema Description:
A domain name or substring using the DNS character set (letters, digits, hyphens).
An asterisk (*) may be used as a wildcard prefix or suffix, but not in the middle. Omit the parameter entirely to fetch all domains.
A trailing dot is acceptable. International characters must be in punycode.
before (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the earliest available record up to the specified point in time (inclusive).
Use with after to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If after is omitted, before (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the end of the query window for filtering domains by when they were observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
after (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the specified point in time (inclusive) up to the latest available record.
Use with before to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If before is omitted, after (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the start of the query window for filtering domains by when they were first observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
Use in combination with seenBefore to define a bounded time range.
headers (integer)¶
In: query
Required: false
Description:
Adds a header row as the first line of the response when text/csv is requested.
Set headers=1 to enable. Only applies when requesting CSV format.
Validation Rules:
- Must be one of:
1
Schema Description:
Optional flag to include a header row as the first line of the response when the response format is text/csv.
Set to 1 to enable CSV headers. If omitted, no header row is included.
Only the value 1 is accepted; any other value is invalid.
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
fromBeginning (boolean)¶
In: query
Required: false
Description:
When starting a new session with sessionID, set fromBeginning=true to fetch data from the earliest available time (the first hour) rather than the most recent hour.
Returns an error if the given sessionID already exists.
Validation Rules:
- Must be one of:
True
Schema Description:
Optional flag to return data from the start of the available window (the first hour) when beginning a new session.
Only the value true is accepted; any other value (including false) will be ignored or treated as omitted.
top (integer)¶
In: query
Required: false
Description:
Limits the number of results in the response payload. Primarily for testing.
Validation Rules:
- Minimum:
1 - Maximum:
1000000000
Schema Description:
Maximum number of feed entries to return in the response payload.
Primarily intended for testing.
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: OK
Content-Type: application/x-ndjson
Schema Description: NDJSON stream, one JSON object per line, matching the FeedRecord schema.
Each object has keys:
- timestamp: ISO 8601 string
- domain: string
Example:
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.badactor.com"}
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.example.com"}
text/csv
Schema Description: CSV-formatted row representing a single feed record. Fields (comma-separated): 1. timestamp (ISO 8601 UTC) 2. domain (string)
Example:
206¶
Description: Partial content limited to 10M rows or 1 hour evaluation window
Content-Type: application/x-ndjson
Schema Description: NDJSON stream, one JSON object per line, matching the FeedRecord schema.
Each object has keys:
- timestamp: ISO 8601 string
- domain: string
Example:
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.badactor.com"}
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.example.com"}
text/csv
Schema Description: CSV-formatted row representing a single feed record. Fields (comma-separated): 1. timestamp (ISO 8601 UTC) 2. domain (string)
Example:
403¶
Description: 403 Forbidden — missing or invalid API credentials.
Content-Type: application/json
Required Fields: error, resources
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
406¶
Description: The requested media type is not supported. Only application/x-ndjson and text/csv are accepted. If you requested application/json, use one of the supported formats instead.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message indicating that the value in the Accept header is not supported.
422¶
Description: 422 Unprocessable Entity — The request is syntactically valid but violates semantic or domain-specific rules.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message explaining why the request could not be processed, despite being well-formed.
/v1/feed/domaindiscovery/ (DELETE)¶
End/cancel a feed session
Ends a previous session.
Requires a valid sessionID query parameter. If the session does not exist, a 404 response is returned.
Operation ID: deleteDomainDiscoverySession
Parameters¶
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: Session deleted successfully (empty response body).
Content-Type: application/json
Schema Description: Empty object returned when no content is required in the response body.
400¶
Description: Bad Request.
Content-Type: application/json
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
Domain Hotlist Feed¶
High-risk, apex-level domains that are observed by DomainTools' global sensor network to be active within 24 hours.
/v1/feed/domainhotlist/ (GET)¶
Returns data from the real-time Domain Hotlist feed.
High-risk, apex-level domains that are observed by DomainTools' global sensor network to be active within 24 hours.
Operation ID: getDomainHotlist
Parameters¶
overall_min (integer)¶
In: query
Required: false
Description:
Filter domains for overall domain risk scores greater than or equal to this value.
Validation Rules:
- Minimum:
1 - Maximum:
99
Schema Description:
Filter domains for risk scores greater than or equal to this value.
malware_min (integer)¶
In: query
Required: false
Description:
Filter domains for malware domain risk scores greater than or equal to this value.
Validation Rules:
- Minimum:
1 - Maximum:
99
Schema Description:
Filter domains for risk scores greater than or equal to this value.
phishing_min (integer)¶
In: query
Required: false
Description:
Filter domains for phishing domain risk scores greater than or equal to this value.
Validation Rules:
- Minimum:
1 - Maximum:
99
Schema Description:
Filter domains for risk scores greater than or equal to this value.
spam_min (integer)¶
In: query
Required: false
Description:
Filter domains for spam domain risk scores greater than or equal to this value.
Validation Rules:
- Minimum:
1 - Maximum:
99
Schema Description:
Filter domains for risk scores greater than or equal to this value.
domain (string)¶
In: query
Required: false
Description:
Filter for an exact domain or a domain substring by prefixing or suffixing your string with *.
Multiple parameters are supported: e.g., ?domain=*apple*&domain=*mic*.
The URL-encoded version of * (%2A) may be required in some clients.
See full documentation.
Validation Rules:
- Min Length:
1 - Max Length:
253 - Pattern:
^\*?[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\.?$|^[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\*\.?$
Schema Description:
A domain name or substring using the DNS character set (letters, digits, hyphens).
An asterisk (*) may be used as a wildcard prefix or suffix, but not in the middle. Omit the parameter entirely to fetch all domains.
A trailing dot is acceptable. International characters must be in punycode.
before (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the earliest available record up to the specified point in time (inclusive).
Use with after to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If after is omitted, before (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the end of the query window for filtering domains by when they were observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
after (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the specified point in time (inclusive) up to the latest available record.
Use with before to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If before is omitted, after (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the start of the query window for filtering domains by when they were first observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
Use in combination with seenBefore to define a bounded time range.
headers (integer)¶
In: query
Required: false
Description:
Adds a header row as the first line of the response when text/csv is requested.
Set headers=1 to enable. Only applies when requesting CSV format.
Validation Rules:
- Must be one of:
1
Schema Description:
Optional flag to include a header row as the first line of the response when the response format is text/csv.
Set to 1 to enable CSV headers. If omitted, no header row is included.
Only the value 1 is accepted; any other value is invalid.
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
fromBeginning (boolean)¶
In: query
Required: false
Description:
When starting a new session with sessionID, set fromBeginning=true to fetch data from the earliest available time (the first hour) rather than the most recent hour.
Returns an error if the given sessionID already exists.
Validation Rules:
- Must be one of:
True
Schema Description:
Optional flag to return data from the start of the available window (the first hour) when beginning a new session.
Only the value true is accepted; any other value (including false) will be ignored or treated as omitted.
top (integer)¶
In: query
Required: false
Description:
Limits the number of results in the response payload. Primarily for testing.
Validation Rules:
- Minimum:
1 - Maximum:
1000000000
Schema Description:
Maximum number of feed entries to return in the response payload.
Primarily intended for testing.
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
Accept (string)¶
In: header
Required: false
Description:
Specifies the desired response format.
- application/x-ndjson: JSON Lines (default)
- text/csv: Comma-separated values. Use headers=1 to include a header row.
Requests for application/json will result in a 406 Not Acceptable.
Validation Rules:
- Must be one of:
application/x-ndjson,text/csv
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: Stream of domain risk feed entries.
Content-Type: application/x-ndjson
Schema Description: NDJSON-formatted line containing a single domain risk record.
Each line is a standalone JSON object matching the structure of DomainRiskRecord.
Example:
{"domain": "badactor.com", "phishing_risk": 75, "malware_risk": 85, "spam_risk": 88, "proximity_risk": 99, "overall_risk": 99}
text/csv
Schema Description: CSV-formatted row representing a domain risk record.
Fields (comma-separated):
- timestamp (ISO 8601 UTC) - when the domain was observed
- domain (string) - apex domain name
- phishing_risk (0-100)
- malware_risk (0-100)
- spam_risk (0-100)
- proximity_risk (0-100)
- overall_risk (0-100)
- evaluated_at (ISO 8601 UTC) - when the risk was last evaluated
206¶
Description: Partial domain risk feed response (HTTP 206) — indicates that additional data is available.
Client should repeat the request with the same sessionID to retrieve the next segment.
Content-Type: application/x-ndjson
Schema Description: NDJSON-formatted line containing a single domain risk record.
Each line is a standalone JSON object matching the structure of DomainRiskRecord.
Example:
{"domain": "badactor.com", "phishing_risk": 75, "malware_risk": 85, "spam_risk": 88, "proximity_risk": 99, "overall_risk": 99}
text/csv
Schema Description: CSV-formatted row representing a domain risk record.
Fields (comma-separated):
- timestamp (ISO 8601 UTC) - when the domain was observed
- domain (string) - apex domain name
- phishing_risk (0-100)
- malware_risk (0-100)
- spam_risk (0-100)
- proximity_risk (0-100)
- overall_risk (0-100)
- evaluated_at (ISO 8601 UTC) - when the risk was last evaluated
403¶
Description: 403 Forbidden — missing or invalid API credentials.
Content-Type: application/json
Required Fields: error, resources
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
406¶
Description: The requested media type is not supported. Only application/x-ndjson and text/csv are accepted. If you requested application/json, use one of the supported formats instead.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message indicating that the value in the Accept header is not supported.
422¶
Description: 422 Unprocessable Entity — The request is syntactically valid but violates semantic or domain-specific rules.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message explaining why the request could not be processed, despite being well-formed.
/v1/feed/domainhotlist/ (DELETE)¶
End/cancel a feed session
Ends a previous session.
Requires a valid sessionID query parameter. If the session does not exist, a 404 response is returned.
Operation ID: deleteDomainHotlistSession
Parameters¶
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: Session deleted successfully (empty response body).
Content-Type: application/json
Schema Description: Empty object returned when no content is required in the response body.
400¶
Description: Bad Request.
Content-Type: application/json
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
Domain Risk Feed¶
Realtime domain risk information for apex-level domains, regardless of observed traffic.
/v1/feed/domainrisk/ (GET)¶
Returns data from the real-time Domain Risk feed.
Realtime domain risk information for apex-level domains, regardless of observed traffic.
Operation ID: getDomainRisk
Parameters¶
overall_min (integer)¶
In: query
Required: false
Description:
Filter domains for overall domain risk scores greater than or equal to this value.
Validation Rules:
- Minimum:
1 - Maximum:
99
Schema Description:
Filter domains for risk scores greater than or equal to this value.
malware_min (integer)¶
In: query
Required: false
Description:
Filter domains for malware domain risk scores greater than or equal to this value.
Validation Rules:
- Minimum:
1 - Maximum:
99
Schema Description:
Filter domains for risk scores greater than or equal to this value.
phishing_min (integer)¶
In: query
Required: false
Description:
Filter domains for phishing domain risk scores greater than or equal to this value.
Validation Rules:
- Minimum:
1 - Maximum:
99
Schema Description:
Filter domains for risk scores greater than or equal to this value.
spam_min (integer)¶
In: query
Required: false
Description:
Filter domains for spam domain risk scores greater than or equal to this value.
Validation Rules:
- Minimum:
1 - Maximum:
99
Schema Description:
Filter domains for risk scores greater than or equal to this value.
domain (string)¶
In: query
Required: false
Description:
Filter for an exact domain or a domain substring by prefixing or suffixing your string with *.
Multiple parameters are supported: e.g., ?domain=*apple*&domain=*mic*.
The URL-encoded version of * (%2A) may be required in some clients.
See full documentation.
Validation Rules:
- Min Length:
1 - Max Length:
253 - Pattern:
^\*?[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\.?$|^[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\*\.?$
Schema Description:
A domain name or substring using the DNS character set (letters, digits, hyphens).
An asterisk (*) may be used as a wildcard prefix or suffix, but not in the middle. Omit the parameter entirely to fetch all domains.
A trailing dot is acceptable. International characters must be in punycode.
before (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the earliest available record up to the specified point in time (inclusive).
Use with after to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If after is omitted, before (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the end of the query window for filtering domains by when they were observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
after (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the specified point in time (inclusive) up to the latest available record.
Use with before to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If before is omitted, after (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the start of the query window for filtering domains by when they were first observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
Use in combination with seenBefore to define a bounded time range.
headers (integer)¶
In: query
Required: false
Description:
Adds a header row as the first line of the response when text/csv is requested.
Set headers=1 to enable. Only applies when requesting CSV format.
Validation Rules:
- Must be one of:
1
Schema Description:
Optional flag to include a header row as the first line of the response when the response format is text/csv.
Set to 1 to enable CSV headers. If omitted, no header row is included.
Only the value 1 is accepted; any other value is invalid.
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
fromBeginning (boolean)¶
In: query
Required: false
Description:
When starting a new session with sessionID, set fromBeginning=true to fetch data from the earliest available time (the first hour) rather than the most recent hour.
Returns an error if the given sessionID already exists.
Validation Rules:
- Must be one of:
True
Schema Description:
Optional flag to return data from the start of the available window (the first hour) when beginning a new session.
Only the value true is accepted; any other value (including false) will be ignored or treated as omitted.
top (integer)¶
In: query
Required: false
Description:
Limits the number of results in the response payload. Primarily for testing.
Validation Rules:
- Minimum:
1 - Maximum:
1000000000
Schema Description:
Maximum number of feed entries to return in the response payload.
Primarily intended for testing.
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: Stream of domain risk feed entries.
Content-Type: application/x-ndjson
Schema Description: NDJSON-formatted line containing a single domain risk record.
Each line is a standalone JSON object matching the structure of DomainRiskRecord.
Example:
{"domain": "badactor.com", "phishing_risk": 75, "malware_risk": 85, "spam_risk": 88, "proximity_risk": 99, "overall_risk": 99}
text/csv
Schema Description: CSV-formatted row representing a domain risk record.
Fields (comma-separated):
- timestamp (ISO 8601 UTC) - when the domain was observed
- domain (string) - apex domain name
- phishing_risk (0-100)
- malware_risk (0-100)
- spam_risk (0-100)
- proximity_risk (0-100)
- overall_risk (0-100)
- evaluated_at (ISO 8601 UTC) - when the risk was last evaluated
206¶
Description: Partial domain risk feed response (HTTP 206) — indicates that additional data is available.
Client should repeat the request with the same sessionID to retrieve the next segment.
Content-Type: application/x-ndjson
Schema Description: NDJSON-formatted line containing a single domain risk record.
Each line is a standalone JSON object matching the structure of DomainRiskRecord.
Example:
{"domain": "badactor.com", "phishing_risk": 75, "malware_risk": 85, "spam_risk": 88, "proximity_risk": 99, "overall_risk": 99}
text/csv
Schema Description: CSV-formatted row representing a domain risk record.
Fields (comma-separated):
- timestamp (ISO 8601 UTC) - when the domain was observed
- domain (string) - apex domain name
- phishing_risk (0-100)
- malware_risk (0-100)
- spam_risk (0-100)
- proximity_risk (0-100)
- overall_risk (0-100)
- evaluated_at (ISO 8601 UTC) - when the risk was last evaluated
403¶
Description: 403 Forbidden — missing or invalid API credentials.
Content-Type: application/json
Required Fields: error, resources
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
406¶
Description: The requested media type is not supported. Only application/x-ndjson and text/csv are accepted. If you requested application/json, use one of the supported formats instead.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message indicating that the value in the Accept header is not supported.
422¶
Description: 422 Unprocessable Entity — The request is syntactically valid but violates semantic or domain-specific rules.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message explaining why the request could not be processed, despite being well-formed.
/v1/feed/domainrisk/ (DELETE)¶
End/cancel a feed session
Ends a previous session.
Requires a valid sessionID query parameter. If the session does not exist, a 404 response is returned.
Operation ID: deleteDomainRiskSession
Parameters¶
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: Session deleted successfully (empty response body).
Content-Type: application/json
Schema Description: Empty object returned when no content is required in the response body.
400¶
Description: Bad Request.
Content-Type: application/json
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
Download API¶
TODO Download up to 7 days of past files.
/v1/download/{feed}/ (GET)¶
Download feed archive from real-time or daily feeds.
Get signed URLs for one or more downloadable feed files.
Operation ID: getFeedDownload
Parameters¶
feed (string)¶
In: path
Required: true
Description:
Not specified. Validation Rules:
- Must be one of:
domaindiscovery,domainhotlist,domainrdap,domainrisk,nad,nod,noh,5_min_domain_whois,5_min_domain_whois_parsed,5_min_ip_whois,5_min_ip_whois_parsed,daily_domain_discovery,daily_domain_hotlist,daily_domain_risk,daily_ip_hotlist,daily_ip_risk
Schema Description:
Feed identifier for use in Download API path. Includes:
-
Real-time feeds
-
5-minute feeds
-
Daily feeds
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
limit (integer)¶
In: query
Required: false
Description:
Limits the number of files returned in the response, starting from the most recent.
Use to control payload size or test specific cases. Must be a positive integer.
Validation Rules:
- Minimum:
1
Schema Description:
Optional parameter to limit the number of downloadable files returned, starting from the most recent.
Must be a positive integer. Defaults to an implementation-defined maximum if omitted.
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
Responses¶
200¶
Description: 200 OK — List of signed URLs to download historical feed data and checksums.
Content-Type: application/json
Schema Description: A list of downloadable files for a specified DomainTools feed and timeframe.
Schema Properties:
- response (object):
400¶
Description: Bad Request.
Content-Type: application/json
Schema Properties:
- error (object):
- resources (object):
403¶
Description: 403 Forbidden — missing or invalid API credentials.
Content-Type: application/json
Required Fields: error, resources
Schema Properties:
- error (object):
- resources (object):
Newly Active Domains Feed¶
Apex-level domains (e.g. example.com but not www.example.com) that we observe based on the latest lifecycle of the domain. A domain may be seen either for the first time ever, or again after at least 10 days of inactivity (no observed resolutions in DNS). Populated with our global passive DNS (pDNS) sensor network.
/v1/feed/nad/ (GET)¶
Returns data from the Newly Active Domains (NAD) feed.
Apex-level domains (e.g. example.com but not www.example.com) that we observe based on the latest lifecycle of the domain. A domain may be seen either for the first time ever, or again after at least 10 days of inactivity. Populated with our global passive DNS (pDNS) sensor network.
Operation ID: getNAD
Parameters¶
domain (string)¶
In: query
Required: false
Description:
Filter for an exact domain or a domain substring by prefixing or suffixing your string with *.
Multiple parameters are supported: e.g., ?domain=*apple*&domain=*mic*.
The URL-encoded version of * (%2A) may be required in some clients.
See full documentation.
Validation Rules:
- Min Length:
1 - Max Length:
253 - Pattern:
^\*?[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\.?$|^[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\*\.?$
Schema Description:
A domain name or substring using the DNS character set (letters, digits, hyphens).
An asterisk (*) may be used as a wildcard prefix or suffix, but not in the middle. Omit the parameter entirely to fetch all domains.
A trailing dot is acceptable. International characters must be in punycode.
before (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the earliest available record up to the specified point in time (inclusive).
Use with after to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If after is omitted, before (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the end of the query window for filtering domains by when they were observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
after (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the specified point in time (inclusive) up to the latest available record.
Use with before to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If before is omitted, after (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the start of the query window for filtering domains by when they were first observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
Use in combination with seenBefore to define a bounded time range.
headers (integer)¶
In: query
Required: false
Description:
Adds a header row as the first line of the response when text/csv is requested.
Set headers=1 to enable. Only applies when requesting CSV format.
Validation Rules:
- Must be one of:
1
Schema Description:
Optional flag to include a header row as the first line of the response when the response format is text/csv.
Set to 1 to enable CSV headers. If omitted, no header row is included.
Only the value 1 is accepted; any other value is invalid.
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
fromBeginning (boolean)¶
In: query
Required: false
Description:
When starting a new session with sessionID, set fromBeginning=true to fetch data from the earliest available time (the first hour) rather than the most recent hour.
Returns an error if the given sessionID already exists.
Validation Rules:
- Must be one of:
True
Schema Description:
Optional flag to return data from the start of the available window (the first hour) when beginning a new session.
Only the value true is accepted; any other value (including false) will be ignored or treated as omitted.
top (integer)¶
In: query
Required: false
Description:
Limits the number of results in the response payload. Primarily for testing.
Validation Rules:
- Minimum:
1 - Maximum:
1000000000
Schema Description:
Maximum number of feed entries to return in the response payload.
Primarily intended for testing.
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: OK
Content-Type: application/x-ndjson
Schema Description: NDJSON stream, one JSON object per line, matching the FeedRecord schema.
Each object has keys:
- timestamp: ISO 8601 string
- domain: string
Example:
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.badactor.com"}
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.example.com"}
text/csv
Schema Description: CSV-formatted row representing a single feed record. Fields (comma-separated): 1. timestamp (ISO 8601 UTC) 2. domain (string)
Example:
206¶
Description: Partial content limited to 10M rows or 1 hour evaluation window
Content-Type: application/x-ndjson
Schema Description: NDJSON stream, one JSON object per line, matching the FeedRecord schema.
Each object has keys:
- timestamp: ISO 8601 string
- domain: string
Example:
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.badactor.com"}
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.example.com"}
text/csv
Schema Description: CSV-formatted row representing a single feed record. Fields (comma-separated): 1. timestamp (ISO 8601 UTC) 2. domain (string)
Example:
403¶
Description: 403 Forbidden — missing or invalid API credentials.
Content-Type: application/json
Required Fields: error, resources
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
406¶
Description: The requested media type is not supported. Only application/x-ndjson and text/csv are accepted. If you requested application/json, use one of the supported formats instead.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message indicating that the value in the Accept header is not supported.
422¶
Description: 422 Unprocessable Entity — The request is syntactically valid but violates semantic or domain-specific rules.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message explaining why the request could not be processed, despite being well-formed.
/v1/feed/nad/ (DELETE)¶
End/cancel a feed session
Ends a session previously started with the NAD feed.
Requires a valid sessionID query parameter. If the session does not exist, a 404 response is returned.
Operation ID: deleteNADSession
Parameters¶
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: Session deleted successfully (empty response body).
Content-Type: application/json
Schema Description: Empty object returned when no content is required in the response body.
400¶
Description: Bad Request.
Content-Type: application/json
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
Newly Observed Domains Feed¶
Apex-level domains (e.g. example.com but not www.example.com) that we observe for the first time, and have not observed previously with our global DNS sensor network.
/v1/feed/nod/ (GET)¶
Returns data from the Newly Observed Domains (NOD) feed.
Apex-level domains (e.g. example.com but not www.example.com) that we observe for the first time, and have not observed previously with our global passive DNS sensor network.
Operation ID: getNOD
Parameters¶
domain (string)¶
In: query
Required: false
Description:
Filter for an exact domain or a domain substring by prefixing or suffixing your string with *.
Multiple parameters are supported: e.g., ?domain=*apple*&domain=*mic*.
The URL-encoded version of * (%2A) may be required in some clients.
See full documentation.
Validation Rules:
- Min Length:
1 - Max Length:
253 - Pattern:
^\*?[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\.?$|^[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\*\.?$
Schema Description:
A domain name or substring using the DNS character set (letters, digits, hyphens).
An asterisk (*) may be used as a wildcard prefix or suffix, but not in the middle. Omit the parameter entirely to fetch all domains.
A trailing dot is acceptable. International characters must be in punycode.
before (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the earliest available record up to the specified point in time (inclusive).
Use with after to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If after is omitted, before (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the end of the query window for filtering domains by when they were observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
after (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the specified point in time (inclusive) up to the latest available record.
Use with before to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If before is omitted, after (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the start of the query window for filtering domains by when they were first observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
Use in combination with seenBefore to define a bounded time range.
headers (integer)¶
In: query
Required: false
Description:
Adds a header row as the first line of the response when text/csv is requested.
Set headers=1 to enable. Only applies when requesting CSV format.
Validation Rules:
- Must be one of:
1
Schema Description:
Optional flag to include a header row as the first line of the response when the response format is text/csv.
Set to 1 to enable CSV headers. If omitted, no header row is included.
Only the value 1 is accepted; any other value is invalid.
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
fromBeginning (boolean)¶
In: query
Required: false
Description:
When starting a new session with sessionID, set fromBeginning=true to fetch data from the earliest available time (the first hour) rather than the most recent hour.
Returns an error if the given sessionID already exists.
Validation Rules:
- Must be one of:
True
Schema Description:
Optional flag to return data from the start of the available window (the first hour) when beginning a new session.
Only the value true is accepted; any other value (including false) will be ignored or treated as omitted.
top (integer)¶
In: query
Required: false
Description:
Limits the number of results in the response payload. Primarily for testing.
Validation Rules:
- Minimum:
1 - Maximum:
1000000000
Schema Description:
Maximum number of feed entries to return in the response payload.
Primarily intended for testing.
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: OK
Content-Type: application/x-ndjson
Schema Description: NDJSON stream, one JSON object per line, matching the FeedRecord schema.
Each object has keys:
- timestamp: ISO 8601 string
- domain: string
Example:
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.badactor.com"}
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.example.com"}
text/csv
Schema Description: CSV-formatted row representing a single feed record. Fields (comma-separated): 1. timestamp (ISO 8601 UTC) 2. domain (string)
Example:
206¶
Description: Partial content limited to 10M rows or 1 hour evaluation window
Content-Type: application/x-ndjson
Schema Description: NDJSON stream, one JSON object per line, matching the FeedRecord schema.
Each object has keys:
- timestamp: ISO 8601 string
- domain: string
Example:
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.badactor.com"}
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.example.com"}
text/csv
Schema Description: CSV-formatted row representing a single feed record. Fields (comma-separated): 1. timestamp (ISO 8601 UTC) 2. domain (string)
Example:
403¶
Description: 403 Forbidden — missing or invalid API credentials.
Content-Type: application/json
Required Fields: error, resources
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
406¶
Description: The requested media type is not supported. Only application/x-ndjson and text/csv are accepted. If you requested application/json, use one of the supported formats instead.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message indicating that the value in the Accept header is not supported.
422¶
Description: 422 Unprocessable Entity — The request is syntactically valid but violates semantic or domain-specific rules.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message explaining why the request could not be processed, despite being well-formed.
/v1/feed/nod/ (DELETE)¶
End/cancel a feed session
Ends a session previously started with the NOD feed.
Requires a valid sessionID query parameter. If the session does not exist, a 404 response is returned.
Operation ID: deleteNODSession
Parameters¶
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: Session deleted successfully (empty response body).
Content-Type: application/json
Schema Description: Empty object returned when no content is required in the response body.
400¶
Description: Bad Request.
Content-Type: application/json
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
Newly Observed Hostnames Feed¶
Hostname resolutions that we observe for the first time with our global DNS sensor network.
/v1/feed/noh/ (GET)¶
Returns data from the Newly Observed Hostnames (NOH) feed.
Hostname resolutions that we observe for the first time with our global passive DNS sensor network.
Operation ID: getNOH
Parameters¶
domain (string)¶
In: query
Required: false
Description:
Filter for an exact domain or a domain substring by prefixing or suffixing your string with *.
Multiple parameters are supported: e.g., ?domain=*apple*&domain=*mic*.
The URL-encoded version of * (%2A) may be required in some clients.
See full documentation.
Validation Rules:
- Min Length:
1 - Max Length:
253 - Pattern:
^\*?[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\.?$|^[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\*\.?$
Schema Description:
A domain name or substring using the DNS character set (letters, digits, hyphens).
An asterisk (*) may be used as a wildcard prefix or suffix, but not in the middle. Omit the parameter entirely to fetch all domains.
A trailing dot is acceptable. International characters must be in punycode.
before (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the earliest available record up to the specified point in time (inclusive).
Use with after to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If after is omitted, before (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the end of the query window for filtering domains by when they were observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
after (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the specified point in time (inclusive) up to the latest available record.
Use with before to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If before is omitted, after (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the start of the query window for filtering domains by when they were first observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
Use in combination with seenBefore to define a bounded time range.
headers (integer)¶
In: query
Required: false
Description:
Adds a header row as the first line of the response when text/csv is requested.
Set headers=1 to enable. Only applies when requesting CSV format.
Validation Rules:
- Must be one of:
1
Schema Description:
Optional flag to include a header row as the first line of the response when the response format is text/csv.
Set to 1 to enable CSV headers. If omitted, no header row is included.
Only the value 1 is accepted; any other value is invalid.
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
fromBeginning (boolean)¶
In: query
Required: false
Description:
When starting a new session with sessionID, set fromBeginning=true to fetch data from the earliest available time (the first hour) rather than the most recent hour.
Returns an error if the given sessionID already exists.
Validation Rules:
- Must be one of:
True
Schema Description:
Optional flag to return data from the start of the available window (the first hour) when beginning a new session.
Only the value true is accepted; any other value (including false) will be ignored or treated as omitted.
top (integer)¶
In: query
Required: false
Description:
Limits the number of results in the response payload. Primarily for testing.
Validation Rules:
- Minimum:
1 - Maximum:
1000000000
Schema Description:
Maximum number of feed entries to return in the response payload.
Primarily intended for testing.
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: OK
Content-Type: application/x-ndjson
Schema Description: NDJSON stream, one JSON object per line, matching the FeedRecord schema.
Each object has keys:
- timestamp: ISO 8601 string
- domain: string
Example:
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.badactor.com"}
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.example.com"}
text/csv
Schema Description: CSV-formatted row representing a single feed record. Fields (comma-separated): 1. timestamp (ISO 8601 UTC) 2. domain (string)
Example:
206¶
Description: Partial content limited to 10M rows or 1 hour evaluation window
Content-Type: application/x-ndjson
Schema Description: NDJSON stream, one JSON object per line, matching the FeedRecord schema.
Each object has keys:
- timestamp: ISO 8601 string
- domain: string
Example:
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.badactor.com"}
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.example.com"}
text/csv
Schema Description: CSV-formatted row representing a single feed record. Fields (comma-separated): 1. timestamp (ISO 8601 UTC) 2. domain (string)
Example:
403¶
Description: 403 Forbidden — missing or invalid API credentials.
Content-Type: application/json
Required Fields: error, resources
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
406¶
Description: The requested media type is not supported. Only application/x-ndjson and text/csv are accepted. If you requested application/json, use one of the supported formats instead.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message indicating that the value in the Accept header is not supported.
422¶
Description: 422 Unprocessable Entity — The request is syntactically valid but violates semantic or domain-specific rules.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message explaining why the request could not be processed, despite being well-formed.
/v1/feed/noh/ (DELETE)¶
End/cancel a feed session
Ends a session previously started with the NOH feed.
Requires a valid sessionID query parameter. If the session does not exist, a 404 response is returned.
Operation ID: deleteNOHSession
Parameters¶
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: Session deleted successfully (empty response body).
Content-Type: application/json
Schema Description: Empty object returned when no content is required in the response body.
400¶
Description: Bad Request.
Content-Type: application/json
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
Parsed Domain RDAP Feed¶
Changes to global domain registration information, populated by the Registration Data Access Protocol (RDAP). Compliments the 5-Minute WHOIS Feed as registries and registrars switch from Whois to RDAP.
/v1/feed/domainrdap/ (GET)¶
Returns data from the real-time Parsed Domain RDAP Feed.
Changes to global domain registration information, populated by the Registration Data Access Protocol (RDAP). Compliments the 5-Minute WHOIS Feed as registries and registrars switch from Whois to RDAP.
Operation ID: getParsedDRDAP
Parameters¶
domain (string)¶
In: query
Required: false
Description:
Filter for an exact domain or a domain substring by prefixing or suffixing your string with *.
Multiple parameters are supported: e.g., ?domain=*apple*&domain=*mic*.
The URL-encoded version of * (%2A) may be required in some clients.
See full documentation.
Validation Rules:
- Min Length:
1 - Max Length:
253 - Pattern:
^\*?[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\.?$|^[A-Za-z0-9](?:[A-Za-z0-9\-\.]{0,251}[A-Za-z0-9])?\*\.?$
Schema Description:
A domain name or substring using the DNS character set (letters, digits, hyphens).
An asterisk (*) may be used as a wildcard prefix or suffix, but not in the middle. Omit the parameter entirely to fetch all domains.
A trailing dot is acceptable. International characters must be in punycode.
before (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the earliest available record up to the specified point in time (inclusive).
Use with after to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If after is omitted, before (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the end of the query window for filtering domains by when they were observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
after (integer or string)¶
In: query
Required: false
Description:
Returns results observed from the specified point in time (inclusive) up to the latest available record.
Use with before to return results from a specific window, starting from the after time (inclusive) and ending at the before time (inclusive).
At least one of after, before, or sessionID must be provided to establish a valid query window. If before is omitted, after (or sessionID) becomes required, and vice versa.
Schema Description:
Defines the start of the query window for filtering domains by when they were first observed.
Accepts one of:
-
relative time, in negative seconds
-
absolute time, in an ISO 8601 timestamp
Use in combination with seenBefore to define a bounded time range.
headers (integer)¶
In: query
Required: false
Description:
Adds a header row as the first line of the response when text/csv is requested.
Set headers=1 to enable. Only applies when requesting CSV format.
Validation Rules:
- Must be one of:
1
Schema Description:
Optional flag to include a header row as the first line of the response when the response format is text/csv.
Set to 1 to enable CSV headers. If omitted, no header row is included.
Only the value 1 is accepted; any other value is invalid.
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
fromBeginning (boolean)¶
In: query
Required: false
Description:
When starting a new session with sessionID, set fromBeginning=true to fetch data from the earliest available time (the first hour) rather than the most recent hour.
Returns an error if the given sessionID already exists.
Validation Rules:
- Must be one of:
True
Schema Description:
Optional flag to return data from the start of the available window (the first hour) when beginning a new session.
Only the value true is accepted; any other value (including false) will be ignored or treated as omitted.
top (integer)¶
In: query
Required: false
Description:
Limits the number of results in the response payload. Primarily for testing.
Validation Rules:
- Minimum:
1 - Maximum:
1000000000
Schema Description:
Maximum number of feed entries to return in the response payload.
Primarily intended for testing.
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: List of Parsed Domain RDAP feed records, including raw RDAP responses from both registry and registrar, as well as a parsed summary.
Content-Type: application/x-ndjson
Required Fields: timestamp, domain, raw_record, parsed_record
Schema Properties:
- timestamp (string (date-time)):
- domain (string):
- raw_record (object):
- parsed_record (object):
206¶
Description: Partial content limited to 10M rows or 1 hour evaluation window
Content-Type: application/x-ndjson
Schema Description: NDJSON stream, one JSON object per line, matching the FeedRecord schema.
Each object has keys:
- timestamp: ISO 8601 string
- domain: string
Example:
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.badactor.com"}
{"timestamp":"2012-10-03T16:03:12Z","domain":"www.example.com"}
text/csv
Schema Description: CSV-formatted row representing a single feed record. Fields (comma-separated): 1. timestamp (ISO 8601 UTC) 2. domain (string)
Example:
403¶
Description: 403 Forbidden — missing or invalid API credentials.
Content-Type: application/json
Required Fields: error, resources
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
406¶
Description: The requested media type is not supported. Only application/x-ndjson and text/csv are accepted. If you requested application/json, use one of the supported formats instead.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message indicating that the value in the Accept header is not supported.
422¶
Description: 422 Unprocessable Entity — The request is syntactically valid but violates semantic or domain-specific rules.
Content-Type: application/json
Required Fields: error
Schema Properties:
- error (string):
A human-readable message explaining why the request could not be processed, despite being well-formed.
/v1/feed/domainrdap/ (DELETE)¶
End/cancel a feed session
Ends a previous session.
Requires a valid sessionID query parameter. If the session does not exist, a 404 response is returned.
Operation ID: deleteDRDAPSession
Parameters¶
sessionID (string)¶
In: query
Required: false
Description:
A string that serves as a unique identifier for the session, used for resuming data retrieval from the last point.
Use a new sessionID to begin a new session, fetching the most recent hour by default. fromBeginning can change this behavior.
Reuse the same sessionID to return all feed data since your last request.
If an API call returns an HTTP 206 response, repeat the same request with the same sessionID to receive the next tranche of results, until an HTTP 200 response is returned, indicating all results have been delivered.
If omitted, time window parameters (such as after/before) are required.
Validation Rules:
- Min Length:
1 - Max Length:
64 - Pattern:
^[A-Za-z0-9\-]{1,64}$
Schema Description:
Unique, client-generated session identifier for incremental feed retrieval.
Requirements:
-
1 to 64 characters in length
-
Alphanumeric characters and hyphens only
-
Case-sensitive
Use a new value to start a new session; reuse the same value to resume a session and fetch additional results.
If omitted, time window parameters (such as after/before) are required.
Example:
api_username (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Your DomainTools API username.
signature (string)¶
In: query
Required: false
Description:
Hex-encoded HMAC signature computed over the string api_username + timestamp + request_path using the API key and a supported algorithm (MD5, SHA1, or SHA256) as the HMAC secret. For example, if using SHA256, compute:
hex(HMAC_SHA256(api_key, api_username + timestamp + "/v1/feed/nad/"))
and pass that as ?signature=….
timestamp (string)¶
In: query
Required: false
Description:
Only required for HMAC authentication.
Current UTC timestamp in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Used to prevent replay attacks; the server will reject timestamps outside an allowed window.
Validation Rules:
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
app_partner (string)¶
In: query
Required: false
Description:
Your product or integration name.
app_name (string)¶
In: query
Required: false
Description:
Appliance/module/playbook name
app_version (string)¶
In: query
Required: false
Description:
Your product or integration version.
Responses¶
200¶
Description: Session deleted successfully (empty response body).
Content-Type: application/json
Schema Description: Empty object returned when no content is required in the response body.
400¶
Description: Bad Request.
Content-Type: application/json
Schema Properties:
- error (object):
- resources (object):
404¶
Description: The requested resource could not be found.
Content-Type: application/json
Required Fields: status_code, reason_phrase
Schema Properties:
- status_code (integer):
- reason_phrase (string):
Last modified: July 01, 2025