Registry / auth-security / domaintools-api

domaintools-api

JSON →
library2.7.4pypypiunverified

The DomainTools Python API Wrapper provides a unified interface to interact with DomainTools' cybersecurity and threat intelligence products, including Iris Investigate, Iris Enrich, Iris Detect, Lookups, Monitors, and Threat Feeds. It is actively maintained, currently at version 2.7.3, with frequent minor releases addressing bugs and ensuring API parity.

pip install domaintools-api --upgrade
INSTALL
IMPORT
SIG · DOMAINTOOLS-API
D
domaintools-api
auth-securitypythonv2.7.4
Install
3.6s avg
Import
590ms
Disk
38MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v2.7.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.607s · 38.5MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.573s · 40MB
38MB installed
● package 38MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

API
✓ from domaintools import API
✗ import domaintools
The primary API client is exposed as `API` from the `domaintools` package. A separate, older `domaintools` package exists on PyPI (last updated 2018) for domain parsing, which can cause import conflicts if installed incorrectly or simultaneously.

Initialize the API client with your DomainTools username and API key. The library supports various DomainTools API endpoints, including Domain Profile lookups, Iris Enrich, and Real-Time Threat Feeds. Credentials should ideally be stored as environment variables (DOMAINTOOLS_USERNAME, DOMAINTOOLS_API_KEY) for security.

import os from domaintools import API # Best practice: Store credentials securely in environment variables username = os.environ.get('DOMAINTOOLS_USERNAME', 'your_username') api_key = os.environ.get('DOMAINTOOLS_API_KEY', 'your_api_key') # Initialize the API client try: api = API(username, api_key) # Example 1: Domain Profile lookup profile_result = api.domain_profile('example.com') print(f"Domain Profile for example.com: {profile_result.response()['domain']}") # Example 2: Iris Enrich enrich_result = api.iris_enrich('domaintools.com') for domain_data in enrich_result.response().get('results', {}): print(f"Enriched domain: {domain_data['domain']}, Risk Score: {domain_data['domain_risk']['risk_score']}") break # Just print one for brevity # Example 3: Real-Time Threat Feed (New Observed Domains - NOD) # Threat Feeds automatically use header authentication, handled by SDK # Use sessionID for pagination or 'after' parameter for time range nod_feed = api.nod(after=-3600) # Last hour for record_json in nod_feed.response(): # Records are JSON strings, need to parse them import json record = json.loads(record_json) print(f"New observed domain from feed: {record['domain']}") break # Just print one for brevity except Exception as e: print(f"An error occurred: {e}") if username == 'your_username' or api_key == 'your_api_key': print("Please set DOMAINTOOLS_USERNAME and DOMAINTOOLS_API_KEY environment variables or replace placeholders.")
Debug
Known issues
gotchaThe SDK primarily uses HMAC-signed authentication by default, which is the most secure method. However, Threat Feeds (e.g., NOD, NAD) automatically switch to header-based authentication. The SDK handles this transparently, but it's important context for custom authentication logic or troubleshooting.
fix
Ensure you are initializing the API client with your `username` and `api_key`. The SDK manages the correct authentication method internally for different endpoints. If manually configuring, consult documentation for specific endpoint requirements.
affects: All versions
gotchaAPI calls return a response object. To access the raw data returned by DomainTools, use `.data()`. To get the actionable response content (typically a dictionary or list), use `.response()`. Direct attribute access (e.g., `profile['field']`) is also possible for specific results.
fix
For most use cases, append `.response()` to your API call to get the core data. Example: `results = api.iris_enrich('domaintools.com').response()`.
affects: All versions
gotchaThe library handles API rate limiting automatically. However, if a `503 Service Unavailable` error is received, it typically indicates a temporary service unavailability or a hard rate limit hit.
fix
Implement exponential backoff and retry logic when receiving `503 Service Unavailable` errors. Review your DomainTools subscription limits if this occurs frequently.
affects: All versions
breakingVersions prior to 2.6.1 had an issue where `Accept-Encoding` was not set to 'identity', causing decompression issues with `iter_lines` for streaming RTTF endpoints. This could lead to malformed or incomplete streaming data.
fix
Upgrade to `domaintools-api` version 2.6.1 or newer: `pip install domaintools-api --upgrade`.
affects: < 2.6.1
breakingIn versions prior to 2.7.3, the `iris_investigate` function would occasionally return missing `risk_score` values even when expected.
fix
Upgrade to `domaintools-api` version 2.7.3 or newer to ensure correct `risk_score` retrieval: `pip install domaintools-api --upgrade`.
affects: < 2.7.3
Upgrade
Version history
2.7.4latest on PyPI · released May 15, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
Agent activity
21 hits · last 30 days
node
20
OpenAI (training)
1
Resources
domaintools-api — pip install domaintools-api · libregistry