### Examples of Command Help

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Demonstrates how to get help for individual commands like iris_investigate, domain_search, and nod.

```bash
domaintools iris_investigate --help
```

```bash
domaintools domain_search --help
```

```bash
domaintools nod --help
```

--------------------------------

### Bash/CLI Example

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/00-START-HERE.txt

Shows how to interact with the DomainTools API using the command-line interface (CLI). This example assumes the CLI tool is installed and configured.

```bash
# CLI example
domaintools dnsdb get-record example.com a
```

--------------------------------

### Basic CLI Usage Examples

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Provides examples for using the DomainTools CLI for common tasks such as domain profiling, complex searches, and accessing real-time feeds. Includes how to pass authentication credentials and get help.

```bash
# Domain profile
domaintools domain_profile example.com -u $USER -k $KEY

# Complex search
domaintools iris_investigate --ip 1.1.1.1 --risk-score 70 -u $USER -k $KEY

# Real-time feed
domaintools nod --session-id feed-1 --after -300 -u $USER -k $KEY

# Get help
domaintools iris_investigate --help
```

--------------------------------

### Python Synchronous Example

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/00-START-HERE.txt

Demonstrates a typical synchronous API call in Python. Ensure the necessary libraries are installed and authentication is configured.

```python
from domaintools import Dnsdb

dnsdb = Dnsdb()

# Synchronous example
response = dnsdb.get_record("example.com", "a")
print(response)
```

--------------------------------

### Configuration Options

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Comprehensive guide to API constructor options (21 parameters), authentication modes (header vs query, signed vs unsigned), network configuration (HTTPS, SSL, proxies, custom URLs), rate limiting strategies, and RTTF-specific options. Includes complete configuration examples.

```APIDOC
## Configuration Options

### Description
This section provides an exhaustive overview of the configuration options available when initializing the DomainTools API client. It covers all 21 constructor parameters, details different authentication methods (header vs. query, signed vs. unsigned requests), and explains network settings such as HTTPS, SSL verification, proxy usage, and custom endpoint URLs. Strategies for handling rate limiting and specific options for Real-Time Threat Feeds (RTTF) are also included, with complete configuration examples provided.

### Reference File
[`configuration.md`](configuration.md)
```

--------------------------------

### CLI Quick Start

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/00-START-HERE.txt

Basic command-line interface usage for fetching a domain profile.

```bash
$ domaintools domain_profile example.com -u username -k key
```

--------------------------------

### Basic Python API Usage Examples

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Demonstrates initializing the API client and performing common operations like domain lookups, filtered searches, and asynchronous iteration. Includes examples for domain profiles, Iris Investigate, Iris Enrich, and real-time feeds.

```python
from domaintools import API

# Initialize
api = API(username='your_username', key='your_api_key')

# Simple domain lookup
profile = api.domain_profile('example.com')
print(profile['registrar'])

# Search with filters
results = api.iris_investigate(ip='199.30.228.112', risk_score_threshold=70)
print(f"Found {results['results_count']} domains")

# Async iteration
async for domain in api.iris_enrich('google.com'):
    print(domain['domain'])

# Real-time feed
for record in api.nod(sessionID='session-1', after=-300).response():
    print(f"New domain: {record['domain']}")
```

--------------------------------

### Install Project Dependencies (Core)

Source: https://github.com/domaintools/python_api/blob/main/README.md

Install only the core project dependencies without test extras.

```bash
pip install -e .
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/domaintools/python_api/blob/main/README.md

Activate the created virtual environment to start using its isolated Python installation and packages.

```bash
source venv/bin/activate
```

--------------------------------

### Python Quick Start

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/00-START-HERE.txt

Basic Python usage for initializing the API client and fetching a domain profile.

```python
from domaintools import API
api = API('username', 'key')
profile = api.domain_profile('example.com')
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/domaintools/python_api/blob/main/README.md

Install the project's Python dependencies, including optional test extras, using pip.

```bash
pip install -e ".[test]"
```

--------------------------------

### Integration Pattern Example

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/00-START-HERE.txt

Illustrates a basic integration pattern, showing how to use the API within a larger application context. This example focuses on fetching and processing data.

```python
from domaintools import Dnsdb

def analyze_domain(domain):
    dnsdb = Dnsdb()
    try:
        a_records = dnsdb.get_record(domain, "a")
        # Process a_records for analysis
        print(f"Found {len(a_records.get('records', []))} A records for {domain}")
    except Exception as e:
        print(f"Could not analyze {domain}: {e}")

analyze_domain("example.com")
```

--------------------------------

### Install DomainTools Python API

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/00-START-HERE.txt

Install the DomainTools Python API using pip.

```bash
$ pip install domaintools_api
```

--------------------------------

### Get Domain Profile

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/index.md

Retrieve a quick profile for a given domain. This example shows how to initialize the API client and fetch basic domain information.

```python
from domaintools import API

api = API(username, key)

# Quick profile
profile = api.domain_profile('example.com')
print(profile['registrar'])
```

--------------------------------

### Index and Navigation

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

The main index and navigation guide for the documentation set. Includes a quick reference for common tasks, module organization, configuration quick start, rate limiting overview, endpoint summary, and Python version/dependency information.

```APIDOC
## Index and Navigation

### Description
This is the primary entry point for the DomainTools Python API documentation, serving as a complete index and navigation guide. It offers a quick reference for frequently performed tasks, explains the overall module organization, and provides a streamlined configuration quick start. An overview of rate limiting, a summary of available endpoints, and essential information regarding Python version compatibility and dependencies are also included.

### Reference File
[`index.md`](index.md)
```

--------------------------------

### IrisQL Query Example

Source: https://github.com/domaintools/python_api/blob/main/README.md

Construct and execute an IrisQL query to search for domains with specific criteria.

```python
query = """# IrisQL-1.0
DOMAIN CONTAINS "phishing"
AND
RISK_SCORE GREATER_THAN 85
"""

results = api.iris_investigate(irisql=query)
print(results["results_count"])
for domain in results:
    print(domain["domain"])
```

--------------------------------

### Async Programming

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Explains how to use async/await patterns with the DomainTools Python API, including examples for real-time feeds.

```APIDOC
## Async Programming

### Description
This section focuses on utilizing asynchronous programming patterns with the DomainTools Python API, including examples for handling real-time data feeds and session management.

### Async/Await Patterns
- Guidance on implementing asynchronous operations.
- Examples demonstrating the use of `async` and `await` keywords.

### Real-Time Feeds
- Specific patterns for interacting with real-time threat feeds asynchronously.
- Session management techniques for continuous data streams.
```

--------------------------------

### Get API Endpoint Help

Source: https://github.com/domaintools/python_api/blob/main/README.md

Use the built-in help function to get an overview of all available API endpoints.

```python
help(api)
```

--------------------------------

### Await Results Object

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/results-and-filters.md

Demonstrates how to await a Results object to get the data, and access specific fields.

```python
# Await result
result = api.domain_profile('example.com')
data = await result
print(data['registrar'])
```

--------------------------------

### Get account information with user and key

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Retrieve account usage and limits by providing your username and API key. This command returns product list with rate limits.

```bash
domaintools account_information -u $USER -k $KEY
```

--------------------------------

### Run Unit Tests with Tox

Source: https://github.com/domaintools/python_api/blob/main/README.md

Execute unit tests using the tox testing tool. Ensure tox is installed and configured.

```bash
tox -e
```

--------------------------------

### Get Domain Profile Asynchronously

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/index.md

Demonstrates how to fetch a domain profile using asynchronous programming. Requires the asyncio library.

```python
import asyncio
async def get_profile():
    result = api.domain_profile('example.com')
    await result
    return result

asyncio.run(get_profile())
```

--------------------------------

### Get Domains Using Nameserver

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Finds domains that are using a specified nameserver. Supports limiting the number of results.

```bash
domaintools reverse_name_server DOMAIN_OR_NS [OPTIONS]
```

```bash
domaintools reverse_name_server ns1.example.com
```

--------------------------------

### Python Asynchronous Example

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/00-START-HERE.txt

Illustrates how to perform asynchronous API calls using Python's async/await syntax. This is useful for handling multiple requests concurrently without blocking.

```python
import asyncio
from domaintools import Dnsdb

async def main():
    dnsdb = Dnsdb()
    # Asynchronous example
    response = await dnsdb.get_record_async("example.com", "a")
    print(response)

asyncio.run(main())
```

--------------------------------

### Get Account Information

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/api-client.md

Retrieve account usage statistics and product information. The results include a list of products with their respective limits.

```python
account = api.account_information()
for product in account:
    print(product['id'], product['per_minute_limit'])
```

--------------------------------

### Domain Profile Output in JSON

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Example of the JSON output format for a domain profile lookup. Shows basic registrar and creation date information.

```bash
$ domaintools domain_profile example.com -f json -u user -k key

{
  "response": {
    "registrar": {
      "name": "GoDaddy",
      "url": "godaddy.com"
    },
    "create_date": "1995-08-15",
    ...
  },
  "status": "success"
}
```

--------------------------------

### List Type: List of Strings

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/types-and-enums.md

Example of using a list of strings for parameters like domain names in an API call.

```python
domains: list[str]
api.iris_investigate(domains=['google.com', 'amazon.com'])
```

--------------------------------

### Error Output Example

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Illustrates the typical error message format when a request to the DomainTools CLI fails, including status code and message.

```bash
$ domaintools domain_profile invalid!@# -u user -k key

Error: Bad Request (400)
Message: We could not understand your request
```

--------------------------------

### Grouped Iteration Example

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/results-and-filters.md

Shows how to iterate over a Results object that contains grouped iteration across multiple result lists.

```python
history = api.hosting_history('example.com')
for entry in history:  # Iterates across all grouped lists
    print(entry)
```

--------------------------------

### Handle API Exceptions

Source: https://github.com/domaintools/python_api/blob/main/README.md

Example of an API call that results in a BadRequestException, demonstrating how exceptions are raised for unsuccessful API calls.

```python
api.domain_profile('notvalid').data()


---------------------------------------------------------------------------
BadRequestException                       Traceback (most recent call last)
<ipython-input-3-f9e22e2cf09d> in <module>()
----> 1 api.domain_profile('google').data()

/home/tcrosley/projects/external/python_api/venv/lib/python3.5/site-packages/domaintools-0.0.1-py3.5.egg/domaintools/base_results.py in data(self)
     25                 self.api._request_session = Session()
     26             results = self.api._request_session.get(self.url, params=self.kwargs)
---> 27             self.status = results.status_code
     28             if self.kwargs.get('format', 'json') == 'json':
     29                 self._data = results.json()

/home/tcrosley/projects/external/python_api/venv/lib/python3.5/site-packages/domaintools-0.0.1-py3.5.egg/domaintools/base_results.py in status(self, code)
     44
     45         elif code == 400:
---> 46             raise BadRequestException()
     47         elif code == 403:
     48             raise NotAuthorizedException()

BadRequestException:

```

--------------------------------

### CLI Reference

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/MANIFEST.txt

Complete reference for the Command Line Interface (CLI), including all commands, global options, output specifications, and usage examples.

```APIDOC
## CLI Reference

This document provides a comprehensive reference for the DomainTools Command Line Interface (CLI). It details all available commands, their options, and how to use the CLI for various tasks.

### CLI Features:
- **Command Coverage**: Reference for 40+ CLI commands across different functionalities (domain, WHOIS, IP, monitor, Iris, feeds, account).
- **Global Options**: Documentation on global settings, including credential handling.
- **Output Specifications**: Details on supported output formats.
- **Usage Examples**: Real-world examples demonstrating practical CLI usage.
- **Integration Patterns**: Guidance on integrating the CLI with scripting, piping, and cron jobs.
```

--------------------------------

### CLI Output Formats: JSON, HTML, XML

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Examples of using the '-f' option to specify output formats for CLI commands, including redirecting HTML output to a file.

```bash
domaintools domain_search google -f json
```

```bash
domaintools domain_search google -f html > results.html
```

```bash
domaintools domain_search google -f xml
```

--------------------------------

### Standard Filter Mode: Active Domains with Recent Updates

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/iris-investigate-irisql.md

Example filtering for active domains that have had recent data updates.

```python
# Active domains with recent updates
results = api.iris_investigate(
    active=True,
    data_updated_after='2024-01-01'
)
```

--------------------------------

### API Client Reference

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/MANIFEST.txt

The `api-client.md` file contains the complete reference for the main API class, including all 40+ endpoint methods, constructor parameters, return value specifications, and usage examples.

```APIDOC
## API Client Reference

This section details the primary `API` class for interacting with the DomainTools API. It includes documentation for over 40 distinct endpoint methods, a constructor with 21 configurable parameters, and specifications for return values and usage examples.

### Key Features:
- **Endpoint Methods**: Comprehensive documentation for all available API operations.
- **Constructor**: Detailed reference for the `API` class constructor, outlining 21 parameters for initialization and configuration.
- **Return Values**: Clear specifications for the data returned by each method.
- **Usage Examples**: Practical examples demonstrating how to use each method effectively.
- **Asynchronous Patterns**: Guidance on utilizing asynchronous programming patterns with the API client.
```

--------------------------------

### Error Handling Pattern Example

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/00-START-HERE.txt

Demonstrates a common pattern for handling exceptions when interacting with the API. This includes catching specific DomainTools exceptions.

```python
from domaintools import Dnsdb, DomainToolsException

dnsdb = Dnsdb()

try:
    response = dnsdb.get_record("nonexistent.com", "a")
except DomainToolsException as e:
    print(f"An API error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
```

--------------------------------

### API Client and Endpoint Methods

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Documentation for the main API class, including its constructor, configuration options, all endpoint methods with their signatures, parameters, return types, and usage examples. Also covers asynchronous support.

```APIDOC
## API Client and Endpoint Methods

### Description
This section details the primary `API` class within the `domaintools_api` package. It covers how to instantiate the client, configure its various options, and outlines all available endpoint methods. Each method's signature, expected parameters, and return types are provided, along with practical usage examples. Asynchronous programming patterns are also addressed.

### Reference File
[`api-client.md`](api-client.md)
```

--------------------------------

### Result Attributes: Pagination with Position Cursor

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/iris-investigate-irisql.md

Example showing how to use the 'position' cursor from the results to fetch the next page of data.

```python
# Pagination
if results['position']:
    next_page = api.iris_investigate(
        ip='1.1.1.1',
        position=results['position']
    )
```

--------------------------------

### CLI Help

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/00-START-HERE.txt

Display help information for the DomainTools CLI.

```bash
$ domaintools --help
```

--------------------------------

### Initialize API with Credentials

Source: https://github.com/domaintools/python_api/blob/main/README.md

Create an instance of the DomainTools API by passing your username and key.

```python
from domaintools import API


api = API(USER_NAME, KEY)
```

--------------------------------

### IrisQL Search by Registrar and Expiration Date

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/iris-investigate-irisql.md

Filter domains based on their registrar and expiration date. This example searches for domains registered with 'GoDaddy' or 'Namecheap' that expire before a specified date.

```python
query = """# IrisQL-1.0
REGISTRAR IN ("GoDaddy", "Namecheap")
AND
EXPIRATION_DATE before "2025-12-31"
"""
results = api.iris_investigate(irisql=query)
```

--------------------------------

### Get Specific Endpoint Help

Source: https://github.com/domaintools/python_api/blob/main/README.md

Get more information about a specific API endpoint, such as iris_investigate.

```python
help(api.iris_investigate)
```

--------------------------------

### Get Value with Default from Results

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/results-and-filters.md

Illustrates using the .get() method to safely retrieve a value from a Results object, providing a default if the key is not found.

```python
# Get with default
registrar = result.get('registrar', 'Unknown')
```

--------------------------------

### Command-Line Help

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/index.md

Access help information for any `domaintools` CLI command to understand available options and usage.

```bash
# Get help
domaintools iris_investigate --help
```

--------------------------------

### IrisQL with Post-Processing Filters

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/iris-investigate-irisql.md

Shows how to combine IrisQL queries with built-in post-request filtering parameters. This example filters by risk score, expiration date, update date, and includes/excludes domains based on missing fields.

```python
results = api.iris_investigate(
    ip='199.30.228.112',
    risk_score_threshold=70,
    younger_than_date='2025-12-31',
    older_than_date='2020-01-01',
    updated_after='2024-01-01',
    include_domains_with_missing_field='ip',
    exclude_domains_with_missing_field='ssl'
)

# results['results'] contains filtered domains
# results['results_count'] reflects post-filter count
for domain in results:
    print(domain['domain'])
```

--------------------------------

### RTTF JSONL Record Example

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/types-and-enums.md

An example of the structure for a Risk-Taker-to-Follower (RTTF) JSONL record, often used for observed domain data.

```json
{
    "domain": str,
    "observed_date": str,             # ISO 8601
    "tld": str,
    "ip": str,
    "name_servers": [str],
    "mx_exists": bool,
    "registrar": str,
    "risk_score": int,
    "risk_level": str
}
```

--------------------------------

### Global Help for DomainTools CLI

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Use this command to list all available commands in the DomainTools CLI. This provides an overview of the tool's capabilities.

```bash
domaintools --help
```

--------------------------------

### CLI Credential Handling: Username and API Key

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

How to provide DomainTools API username and key directly on the command line for authentication.

```bash
domaintools domain_profile example.com -u myuser -k mykey
```

--------------------------------

### CLI - Domain Profile

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Command-line interface command to get a domain profile.

```APIDOC
## CLI - Domain Profile

### Description
Command-line tool to retrieve domain profile information.

### Usage
`domaintools domain_profile <domain> -u <username> -k <key>`

### Parameters
- **domain** (string) - Required - The domain name to look up.
- **-u, --username** (string) - Required - Your DomainTools API username.
- **-k, --key** (string) - Required - Your DomainTools API key.
```

--------------------------------

### Get Response Content Only

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/results-and-filters.md

Extracts only the core response object, excluding envelope data.

```python
data = api.domain_profile('example.com').response()
# Returns just the response object without wrapper
```

--------------------------------

### Initialize DomainTools API Client

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/api-client.md

Instantiate the API client with your username and key. Optional parameters can configure SSL, rate limiting, proxies, and authentication.

```python
from domaintools import API

api = API(username, key, **options)
```

--------------------------------

### Constructor Parameters

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Details 21 documented parameters for the constructor, covering authentication, network settings, rate limiting, and application metadata.

```APIDOC
## Constructor Parameters

### Description
Documentation for 21 constructor parameters, including authentication methods, network configurations, rate limiting options, and application metadata.

### Parameters
- Authentication (username, key, signing modes, header vs query)
- Network (HTTPS, SSL verification, proxies, custom URLs)
- Rate limiting (automatic, manual, feeds-specific)
- Application metadata (app name, version)
- Default parameters
```

--------------------------------

### Python API - Domain Profile Lookup

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Demonstrates how to initialize the API client and perform a simple domain profile lookup.

```APIDOC
## Domain Profile Lookup

### Description
Retrieves the profile information for a given domain.

### Method
`api.domain_profile(domain)`

### Parameters
- **domain** (string) - Required - The domain name to look up.

### Request Example
```python
from domaintools import API
api = API(username='your_username', key='your_api_key')
profile = api.domain_profile('example.com')
```

### Response
Returns a dictionary containing domain profile data. The example shows accessing the 'registrar' field.

### Response Example
```python
print(profile['registrar'])
```
```

--------------------------------

### Get Complete Response Data

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/results-and-filters.md

Retrieves the full API response, including metadata and status.

```python
complete = api.domain_profile('example.com').data()
# Returns: {"response": {...}, "status": "success", ...}
```

--------------------------------

### Get Response Status Code

Source: https://github.com/domaintools/python_api/blob/main/README.md

Shows how to access the HTTP status code of a successful API response.

```python
api.domain_profile('google.com').status == 200
```

--------------------------------

### Standard API Configuration

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/index.md

Initialize the API client with default settings for username, API key, HTTPS, SSL verification, and automatic rate limiting.

```python
api = API(
    username='your_username',
    key='your_api_key',
    https=True,
    verify_ssl=True,
    rate_limit=True
)
```

--------------------------------

### Get Domains on Same IP

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Finds other domains that are hosted on the same IP address. Supports limiting the number of results.

```bash
domaintools reverse_ip DOMAIN [OPTIONS]
```

```bash
domaintools reverse_ip example.com --limit 50
```

--------------------------------

### Basic Production Configuration

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/configuration.md

Configure the API client for a standard production environment. Ensure SSL verification and enable automatic rate limiting.

```python
api = API(
    username="my_username",
    key="my_api_key",
    https=True,           # Mandatory
    verify_ssl=True,      # Verify CA
    rate_limit=True,      # Auto rate limit
    app_name="my_tool",
    app_version="1.0.0"
)
```

--------------------------------

### Asynchronous Support

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/api-client.md

Demonstrates how to use the API methods asynchronously with async/await, context managers, and for loops.

```APIDOC
## Asynchronous Support

All API methods return `Results` objects that support async/await:

```python
# Async context manager
async with api.iris_enrich('example.com') as result:
    print(result['results_count'])

# Async for loop
async for domain in api.iris_enrich('example.com'):
    print(domain['domain'])

# Mixed sync/async (optimal if async called first)
result = api.domain_profile('google.com')
title = await result['website_data']['title']
```
```

--------------------------------

### Get Parsed WHOIS Data

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Retrieves structured, parsed WHOIS data for a domain. Can output in JSON format.

```bash
domaintools parsed_whois DOMAIN
```

```bash
domaintools parsed_whois example.com -f json
```

--------------------------------

### Get Raw WHOIS Record

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Fetches the raw WHOIS record for a given domain name or IP address.

```bash
domaintools whois DOMAIN_OR_IP
```

```bash
domaintools whois example.com
```

```bash
domaintools whois 1.1.1.1
```

--------------------------------

### Get Domain Profile

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Retrieves a complete profile for a specified domain. Use with your API user and key for authentication.

```bash
domaintools domain_profile DOMAIN [OPTIONS]
```

```bash
domaintools domain_profile google.com -u $USER -k $KEY
```

```bash
domaintools domain_profile example.com -f json
```

--------------------------------

### Pagination: Position-based (Recommended)

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/iris-investigate-irisql.md

Demonstrates the recommended position-based pagination method using the 'position' cursor for fetching subsequent pages.

```python
# First page
results = api.iris_investigate(ip='1.1.1.1', page_size=50)
print(results['position'])

# Next page using cursor
next_results = api.iris_investigate(
    ip='1.1.1.1',
    page_size=50,
    position=results['position']
)
```

--------------------------------

### Basic Authentication

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/configuration.md

Initialize the API client with your username and API key for authentication.

```python
api = API('your_username', 'your_api_key')
```

```python
api = API('username', 'your_api_key_here')
```

--------------------------------

### Make an Iris Enrich API Call

Source: https://github.com/domaintools/python_api/blob/main/README.md

Example of making an API call to the iris_enrich endpoint with a domain name.

```python
api.iris_enrich('domaintools.com')
```

--------------------------------

### API Constructor

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/api-client.md

Initializes the DomainTools API client. You need to provide your username and API key. Various optional parameters can be set to customize the client's behavior, such as SSL verification, rate limiting, proxy settings, and authentication methods.

```APIDOC
## API Constructor

### Description
Initializes the DomainTools API client. You need to provide your username and API key. Various optional parameters can be set to customize the client's behavior, such as SSL verification, rate limiting, proxy settings, and authentication methods.

### Method Signature
```python
def __init__(
    self,
    username: str,
    key: str,
    https: bool = True,
    verify_ssl: Union[bool, str] = True,
    rate_limit: bool = True,
    proxy_url: str = None,
    always_sign_api_key: bool = None,
    header_authentication: bool = None,
    key_sign_hash: str = "sha256",
    app_name: str = "python_wrapper",
    app_version: str = version,
    api_url: str = None,
    api_port: int = None,
    **default_parameters
) -> API
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| username | str | yes | — | DomainTools API username |
| key | str | yes | — | DomainTools API key |
| https | bool | no | True | Use HTTPS for API requests. HTTP is no longer supported and must remain True |
| verify_ssl | bool, str | no | True | SSL verification. Pass False to disable or a string path to a custom CA bundle |
| rate_limit | bool | no | True | Automatically apply rate limiting based on account limits |
| proxy_url | str | no | None | Proxy URL in format "host:port" (e.g., "127.0.0.1:8888") |
| always_sign_api_key | bool | no | None | Sign API key in request signature for all endpoints |
| header_authentication | bool | no | None | Use header-based authentication (X-Api-Key) instead of query parameter |
| key_sign_hash | str | no | "sha256" | Hash algorithm for signing: "sha1" or "sha256" |
| app_name | str | no | "python_wrapper" | Application identifier sent to API |
| app_version | str | no | current version | Application version sent to API |
| api_url | str | no | https://api.domaintools.com | Base API URL override |
| api_port | int | no | None | Port override for custom API deployments |
| **default_parameters | dict | no | {} | Default query parameters to include in all requests |

### Request Example
```python
api = API(username="your_username", key="your_api_key")
```

### Response
#### Success Response (200)
Returns an initialized `API` object.

#### Response Example
```python
# No direct response example for constructor, returns API object
```
```

--------------------------------

### List Type: List of TLDs

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/types-and-enums.md

Example of providing a list of strings representing Top-Level Domains (TLDs) for filtering.

```python
tlds: list[str]
api.iris_detect_new_domains(tlds=['com', 'net', 'org'])
```

--------------------------------

### List Type: List of Callables (Filters)

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/types-and-enums.md

Example of using a list of callable objects (filters) to refine results.

```python
filters: list[Callable]
DTResultFilter(result_set).by([filter1, filter2, filter3])
```

--------------------------------

### Get HTML Response Format

Source: https://github.com/domaintools/python_api/blob/main/README.md

Retrieve the HTML version of the response for a domain search by calling .html(). This works with non-AsyncResults.

```python
html = str(api.domain_search('google').html())
```

--------------------------------

### DomainTools CLI IrisQL with Pagination

Source: https://github.com/domaintools/python_api/blob/main/README.md

Run an IrisQL query using the CLI, specifying pagination parameters and credentials.

```bash
domaintools iris_investigate --irisql $'# IrisQL-1.0\nDOMAIN CONTAINS "phishing"' --page-size 50 --sort-by risk_score -u $TEST_USER -k $TEST_KEY
```

--------------------------------

### Get XML Response Format

Source: https://github.com/domaintools/python_api/blob/main/README.md

Retrieve the XML version of the response for a domain search by calling .xml(). This works with non-AsyncResults.

```python
xml = str(api.domain_search('google').xml())
```

--------------------------------

### Load Credentials from Environment Variables

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/configuration.md

Shows how to load API credentials (username and key) from environment variables for secure credential management. This is a recommended pattern for credential handling.

```python
import os
from domaintools import API

# Load from environment
username = os.environ.get('DOMAINTOOLS_USERNAME')
key = os.environ.get('DOMAINTOOLS_KEY')

# Create API instance
api = API(username, key)
```

--------------------------------

### Get JSON Response Format

Source: https://github.com/domaintools/python_api/blob/main/README.md

Retrieve the JSON version of the response for a domain search by calling .json(). This works with non-AsyncResults.

```python
json = str(api.domain_search('google').json())
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/index.md

Use the DomainTools CLI to perform an Iris Investigate query for a given IP address, providing username and key as arguments.

```bash
domaintools iris_investigate --ip 199.30.228.112 -u $USER -k $KEY
```

--------------------------------

### Get Domains Hosted on IP

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Retrieves domains that are hosted by a specific IP address. Supports limiting the number of results.

```bash
domaintools host_domains IP [OPTIONS]
```

```bash
domaintools host_domains 1.1.1.1
```

--------------------------------

### Get Parsed RDAP Registration Data

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Fetches parsed registration data using the RDAP protocol for a given domain.

```bash
domaintools parsed_domain_rdap DOMAIN
```

--------------------------------

### Basic Async/Await for API Results

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/feeds-and-async.md

Demonstrates how to await API results directly for single requests. Ensure the API object is initialized before awaiting.

```python
import asyncio

async def get_profile():
    api = API(username, key)
    
    # Await the result
    result = api.domain_profile('example.com')
    await result
    
    # Access data after await
    print(result['registrar'])

asyncio.run(get_profile())
```

--------------------------------

### Get WHOIS Change History

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Retrieves the historical changes for a WHOIS record. Supports various modes, sorting, and pagination.

```bash
domaintools whois_history DOMAIN [OPTIONS]
```

--------------------------------

### Get Domain Change History

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Retrieves the history of changes for a domain. Supports filtering which fields to include or exclude, and pagination.

```bash
domaintools domain_history DOMAIN [OPTIONS]
```

```bash
domaintools domain_history example.com --include-fields ip,registrar
```

```bash
domaintools domain_history google.com --page-size 50
```

--------------------------------

### Command-Specific Help for DomainTools CLI

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Obtain detailed help for a specific command by appending the --help flag. This is useful for understanding command parameters and options.

```bash
domaintools COMMAND --help
```

--------------------------------

### Setting Up a Cron Job for Continuous Monitoring

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

This cron job entry configures continuous monitoring using the DomainTools 'nod' command, logging output to a specified file. It runs every hour.

```bash
# Continuous monitoring
0 * * * * domaintools nod --session-id monitor-$(date +%s) --after -3600 -u $USER -k $KEY >> /var/log/nod-feed.log
```

--------------------------------

### Get Response as HTML String

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/results-and-filters.md

Converts the API response to an HTML formatted string. This method is available for non-asynchronous results only.

```python
html_str = api.domain_search('google').html()
```

--------------------------------

### CLI Support

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Details 40+ CLI commands, including help, endpoint invocation, output formatting, and credential handling.

```APIDOC
## CLI Support

### Description
Documentation for over 40 command-line interface commands, covering help, API endpoint execution, output format options, and credential management.

### Commands
- Help and navigation
- All API endpoints
- Output format options
- Credential handling
- Integration patterns (piping, scripting)
```

--------------------------------

### Get Response as XML String

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/results-and-filters.md

Converts the API response to an XML formatted string. This method is available for non-asynchronous results only.

```python
xml_str = api.domain_search('google').xml()
```

--------------------------------

### Get Response as JSON String

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/results-and-filters.md

Converts the API response to a JSON formatted string. This method is available for non-asynchronous results only.

```python
json_str = api.domain_search('google').json()
```

--------------------------------

### Create Virtual Environment

Source: https://github.com/domaintools/python_api/blob/main/README.md

Create a new virtual environment for your Python project to manage dependencies.

```bash
python3 -m venv venv
```

--------------------------------

### On-Premises API Configuration

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/index.md

Set up the API client for an on-premises deployment, specifying the custom API URL, port, and SSL certificate path.

```python
api = API(
    username='internal_user',
    key='internal_key',
    api_url='https://api.internal.company.com',
    api_port=8443,
    verify_ssl='/path/to/ca.crt'
)
```

--------------------------------

### Standard Filter Mode: Single Domain Search

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/iris-investigate-irisql.md

Example of filtering Iris Investigate results for a single specified domain.

```python
# Single domain filter
results = api.iris_investigate(domains='example.com')
```

--------------------------------

### DomainTools CLI Entry Point

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

The basic structure for invoking DomainTools CLI commands, including global options for username, API key, and output format.

```bash
domaintools [COMMAND] [OPTIONS] [-u USERNAME] [-k API_KEY] [-f FORMAT]
```

--------------------------------

### Configure API Credentials in ~/.dtapi

Source: https://github.com/domaintools/python_api/blob/main/README.md

Store API user and key in the ~/.dtapi file for automatic credential loading by the CLI.

```bash
API_USER
API_KEY
```

--------------------------------

### Get Iris Detect Monitors

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/api-client.md

Retrieves a list of monitors from the Iris Detect service. Useful for iterating through monitors and accessing their terms.

```python
monitors = api.iris_detect_monitors(offset=0, limit=10)
for monitor in monitors:
    print(monitor['term'])
```

--------------------------------

### Configuration Options

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/MANIFEST.txt

Details on configuring the API client, including authentication methods, network settings, rate limiting, and RTTF-specific options.

```APIDOC
## Configuration Options

This section provides a comprehensive guide to configuring the DomainTools API client. It covers various aspects essential for establishing and managing connections, including authentication, network settings, and performance tuning.

### Key Configuration Areas:
- **API Constructor Options**: Reference for the 21 parameters available in the API constructor for detailed setup.
- **Authentication Modes**: Documentation on supported authentication methods, including header, query, and signing.
- **Network Configuration**: Settings for SSL verification, proxy usage, and custom API endpoint URLs.
- **Rate Limiting**: Strategies for managing API request rates to avoid exceeding limits.
- **RTTF-specific Options**: Configuration parameters tailored for Real-Time Threat Feed services.
- **Complete Examples**: Illustrative examples showcasing various configuration scenarios.
```

--------------------------------

### Retrieve Response Information from API Call

Source: https://github.com/domaintools/python_api/blob/main/README.md

Get just the actionable response information from a DomainTools API call using the .response() method.

```python
api.iris_enrich('domaintools.com').response() == { ... }
```

--------------------------------

### On-Premises Deployment Configuration

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/configuration.md

Configure the API client for an on-premises deployment. Specify the internal API URL, port, and the path to the internal CA certificate for SSL verification. Enable header authentication if required.

```python
# Internal API endpoint
api = API(
    username="internal_user",
    key="internal_key",
    api_url="https://api.internal.company.com",
    api_port=8443,
    verify_ssl="/path/to/internal-ca.crt",
    header_authentication=True
)
```

--------------------------------

### Retrieve Full Data from API Call

Source: https://github.com/domaintools/python_api/blob/main/README.md

Get the entire structure returned from a DomainTools API call using the .data() method.

```python
api.iris_enrich('domaintools.com').data() == {'response': { ... }}
```

--------------------------------

### Basic Python API Usage

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/index.md

Initialize the DomainTools API client with your username and key, then perform an Iris Investigate query for a given IP address.

```python
from domaintools import API

api = API(username, key)
results = api.iris_investigate(ip='199.30.228.112')
```

--------------------------------

### Domain Filtering Examples

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/feeds-and-async.md

Filter feed results by domain name using exact matches, prefix patterns, or suffix patterns.

```python
# Exact domain match
results = api.nod(domain="example.com")

# Prefix match
results = api.nod(domain="*phishing*")

# Suffix match
results = api.nod(domain="example*")

# Only prefix
results = api.nod(domain="test*")

# Only suffix
results = api.nod(domain="*.malware")
```

--------------------------------

### Async Support

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/README.md

Covers 8+ async patterns, including await results, async iteration, context managers, and parallel requests.

```APIDOC
## Async Support

### Description
Documentation for 8+ asynchronous patterns supported by the API, including await results, async iteration, context managers, and parallel request handling.

### Patterns Covered
- Await results
- Async iteration
- Async context managers
- Mixed sync/async
- Parallel requests with gather
- Async generators
- Exception handling
- Performance characteristics
```

--------------------------------

### Get Parsed WHOIS Data

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/api-client.md

Retrieve and flatten parsed WHOIS data for a given domain. This is useful for obtaining normalized domain information.

```python
parsed = api.parsed_whois('example.com')
flat = parsed.flattened()  # Get flattened representation
```

--------------------------------

### Get Domain Reputation Score

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/api-client.md

Retrieves the risk reputation score for a given domain. The score can be cast to float or int for direct use.

```python
rep = api.reputation('example.com')
score = float(rep)  # Cast to float
risk_level = int(rep)  # Cast to int
```

--------------------------------

### CLI Credential Handling: Credential File

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Using a credential file (~/.dtapi) for authentication, where the username is on the first line and the API key on the second.

```bash
domaintools domain_profile example.com
```

--------------------------------

### Domain Search Output in HTML

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/cli-reference.md

Example of the HTML output format for a domain search. This format is typically used for web-based display of results.

```bash
$ domaintools domain_search google -f html -u user -k key

<html>
  <head><title>Search Results</title></head>
  <body>
    ...formatted HTML results...
  </body>
</html>
```

--------------------------------

### Access API Instance Attributes

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/configuration.md

Demonstrates the attributes available on an API instance after it has been created. These attributes provide details about the API connection and configuration.

```python
api = API(username, key)

# Accessible attributes
print(api.username)           # Your username
print(api.key)                # Your API key
print(api.https)              # True (always)
print(api.verify_ssl)         # ssl.SSLContext or bool
print(api.rate_limit)         # bool
print(api.proxy_url)          # str or None
print(api.limits)             # dict of rate limits per product
print(api.limits_set)         # bool
print(api.specs)              # dict of OpenAPI specs (Iris endpoints)
print(api.default_parameters) # dict
print(api._rest_api_url)      # Base URL
```

--------------------------------

### List Type: List of Risk Score Ranges

Source: https://github.com/domaintools/python_api/blob/main/_autodocs/types-and-enums.md

Example of specifying a list of strings, where each string represents a risk score range for filtering.

```python
risk_score_ranges: list[str]
api.iris_detect_new_domains(risk_score_ranges=['0-0', '1-39', '40-69'])
```