Reference: DETEQTIVE DNS API

Information-oriented: Complete technical reference for the DETEQTIVE DNS API.

Authentication

All API requests require a Bearer token. Set it once in your shell and all examples will work:

export DETEQTIVE_TOKEN="your-api-token-here"

API Version

Current Version: v3 Base Path: /api/v3 Specification: OpenAPI 3.0.3

Base URLs

Endpoints

Forward Search (RRSet) - Search by Domain

Search for DNS records by domain name using various matching strategies.

GET /rrset/{type}/{value}

Search with all record types.

Path Parameters:

• type (string, required) - Search type: em, rm, lm, fm, wm
• value (string, required) - Domain name to search

Query Parameters:

• limit (integer, optional) - Max results (1-50000, default: 1000)
• first_seen_before (integer, optional) - Unix timestamp (default: none)
• first_seen_after (integer, optional) - Unix timestamp (default: none)
• last_seen_before (integer, optional) - Unix timestamp (default: now)
• last_seen_after (integer, optional) - Unix timestamp (default: 14 days ago)
• withbailiwick (boolean flag, optional) - Include bailiwick field
• idn (boolean flag, optional) - Enable IDN search
• fuzziness (integer, optional) - Edit distance (1-3, default: 2, only for fm)

Example:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rrset/em/google.com

GET /rrset/{type}/{value}/{rrtype}

Search filtered by specific DNS record type.

Path Parameters:

• type (string, required) - Search type
• value (string, required) - Domain name
• rrtype (string, required) - DNS record type (A, AAAA, CNAME, MX, etc.)

Query Parameters: Same as above

Example:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rrset/em/google.com/A

GET /rrset/{type}/{value}/{rrtype}/{bailiwick}

Search filtered by record type and bailiwick (authoritative zone).

Path Parameters:

• type (string, required) - Search type
• value (string, required) - Domain name
• rrtype (string, required) - DNS record type
• bailiwick (string, required) - DNS zone where record was observed

Query Parameters: Same as above (except withbailiwick is implicit)

Example:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rrset/em/www.google.com/A/google.com

Reverse Search (RData) - Search by IP/CIDR/Hostname

Search for DNS records by value in the RDATA field (IP addresses, hostnames, etc.).

GET /rdata/{value}

Search with all record types.

Path Parameters:

• value (string, required) - IP, CIDR, or hostname to search

Query Parameters:

• limit (integer, optional) - Max results (1-50000, default: 1000)
• first_seen_before (integer, optional) - Unix timestamp (default: none)
• first_seen_after (integer, optional) - Unix timestamp (default: none)
• last_seen_before (integer, optional) - Unix timestamp (default: now)
• last_seen_after (integer, optional) - Unix timestamp (default: 14 days ago)

Value Format:

• IPv4: 1.2.3.4
• IPv6: 2001:db8::1
• IPv4 CIDR: 192.0.2.0%2F24 (URL-encoded)
• IPv6 CIDR: 2001:db8::%2F32 (URL-encoded)
• Hostname: ns1.example.com

Example:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rdata/142.250.185.46

GET /rdata/{value}/{rrtype}

Search filtered by specific DNS record type.

Path Parameters:

• value (string, required) - IP, CIDR, or hostname
• rrtype (string, required) - DNS record type

Query Parameters: Same as above

Example:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rdata/142.250.185.46/A

GET /rdata/{value}/{rrtype}/{bailiwick}

Search filtered by record type and bailiwick.

Path Parameters:

• value (string, required) - IP, CIDR, or hostname
• rrtype (string, required) - DNS record type
• bailiwick (string, required) - DNS zone

Query Parameters: Same as above

Example:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rdata/142.250.185.46/A/google.com

Metadata Endpoints

GET /status

Returns your account status, the request limits that apply to you, your current request rate, and your daily/monthly usage counters.

Authentication: Required (Bearer JWT).

Note: Checking /status does not count toward your usage.

Response fields:

Authenticated example:

curl -H "Authorization: Bearer $TOKEN" https://api.deteqtive.com/api/v3/status

{
  "authenticated": true,
  "user": "alice@example.com",
  "account": "acc-0042",
  "limits": { "qps": 5.0, "qpm": 100.0, "qph": 2000.0 },
  "rate":   { "qps": 0.12, "qpm": 3.40, "qph": 45.0 },
  "counters": { "daily": 312, "monthly": 8741 }
}

GET /openapi.yaml

Returns the API catalog — an index of the available APIs, each linking to its own OpenAPI specification. Fetch a specific API’s spec from its spec link (see below).

GET /openapi/{name}.yaml

Returns a single API’s OpenAPI 3.0.3 specification in YAML format — for example /openapi/pdns.yaml for the Passive DNS API. This is the document you download for generating client libraries, importing into tools, or documentation purposes.

Example:

# Download the Passive DNS spec
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/openapi/pdns.yaml > deteqtive-api-spec.yaml

# Verify it's valid YAML
head -10 deteqtive-api-spec.yaml

Response: YAML file containing the complete API specification

Use this to:

• Generate client libraries in 40+ languages
• Import into Postman, Insomnia, or other API tools
• Generate documentation
• Validate API requests before implementation

Search Types

Search Type Examples

Exact Match (em):

• Search: google.com
• Matches: google.com only

Right Match (rm):

• Search: google.com
• Matches: google.com, www.google.com, mail.google.com, api.google.com

Left Match (lm):

• Search: www.google.com
• Matches: www.google.com, google.com, com

Fuzzy Match (fm):

• Search: google.com with fuzziness=1
• Matches: google.com, googlee.com, gogle.com (1 char difference)

Word Match (wm):

• Search: google
• Matches: google.com, google-analytics.com, mygoogle.com, googleusercontent.com

Query Parameters

limit

Type: Integer Range: 1 - 50000 Default: 1000 Description: Maximum number of DNS records to return

Example:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/google.com?limit=100"

Time Filtering Parameters

first_seen_before

Type: Integer (Unix timestamp) Default: None (no limit) Description: Return only records first observed before this timestamp

Example:

# Records first seen before Jan 1, 2024
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/google.com?first_seen_before=1704067200"

first_seen_after

Type: Integer (Unix timestamp) Default: None (no limit) Description: Return only records first observed after this timestamp

Example:

# Records first seen after Jan 1, 2024
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/google.com?first_seen_after=1704067200"

last_seen_before

Type: Integer (Unix timestamp) Default: Current time (now) Description: Return only records last observed before this timestamp

Example:

# Records last seen before Jan 1, 2024 (possibly expired)
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/google.com?last_seen_before=1704067200"

last_seen_after

Type: Integer (Unix timestamp) Default: 14 days ago (2 weeks before current time) Description: Return only records last observed after this timestamp

Example:

# Records last seen after Jan 1, 2024 (likely still active)
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/google.com?last_seen_after=1704067200"

Important: By default, queries return only records seen in the last 14 days (unless you override last_seen_after). To query all historical data, explicitly set last_seen_after=0.

Time Range Example:

# Records first seen in January 2024
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/google.com?first_seen_after=1704067200&first_seen_before=1706745599"

withbailiwick

Type: Boolean flag Default: false Description: Include the bailiwick field in DNS record responses

Usage:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/google.com?withbailiwick"

Note: Don’t assign a value, just include the parameter name.

Effect:

• Without flag: {"rrname":"google.com","rrtype":"A","rdata":"1.2.3.4",...}
• With flag: {"bailiwick":"google.com","rrname":"google.com","rrtype":"A","rdata":"1.2.3.4",...}

idn

Type: Boolean flag Default: false Description: Enable Internationalized Domain Name (IDN) search Applies to: RRSet endpoints only

Usage:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/münchen.de?idn"

fuzziness

Type: Integer Range: 1 - 3 Default: 2 Description: Edit distance threshold for fuzzy matching Applies to: Only when using search type fm

Usage:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/fm/google.com?fuzziness=2"

Interpretation:

• fuzziness=1 - 1 character can differ
• fuzziness=2 - 2 characters can differ (default)
• fuzziness=3 - 3 characters can differ (maximum, very broad)

DNS Record Types

Usage:

# Specific type
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rrset/em/google.com/MX

# All types
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rrset/em/google.com

Response Format

Content-Type

Format: NDJSON (Newline-Delimited JSON) MIME Type: application/x-ndjson

Each line is a separate, valid JSON object. This allows for streaming responses and processing records as they arrive.

Important: Results are not sorted. The same query executed multiple times may return records in different order. If you need consistent ordering, sort results client-side.

DNS Record Object

Structure:

{
  "bailiwick": "google.com",
  "rrname": "google.com",
  "rrtype": "A",
  "rdata": "142.250.185.46",
  "first_seen": "2023-01-01T12:00:00Z",
  "last_seen": "2023-12-31T23:59:59Z",
  "sightings": 1542
}

Fields:

Notes:

• first_seen and last_seen are ISO 8601 format: 2023-12-31T23:59:59Z
• Nullable fields may be null if data is not available
• bailiwick is only present when requested via parameter or path

Status Message Object

The final line of every response is a status message.

Success Example:

{
  "eof": true,
  "count": 42,
  "elapsed": 0.187,
  "error": null
}

Error Example:

{
  "eof": false,
  "count": 0,
  "elapsed": 0.002,
  "error": "query timeout - please refine your search or try again later"
}

Fields:

Important: If the status line with eof is not present in the output, the response was truncated (e.g., connection lost, timeout, client disconnected). Always check for the presence of the status line to ensure complete results.

Complete Response Example

{"rrname":"google.com","rrtype":"A","rdata":"142.250.185.46","first_seen":"2023-01-01T12:00:00Z","last_seen":"2023-12-31T23:59:59Z","sightings":1542}
{"rrname":"google.com","rrtype":"A","rdata":"142.250.185.78","first_seen":"2023-02-15T08:30:00Z","last_seen":"2023-12-30T18:45:00Z","sightings":987}
{"eof":true,"count":2,"elapsed":0.187,"error":null}

Parsing:

• Lines 1-2: DNS records
• Line 3: Status message
• Each line is independently parseable as JSON

Empty Results Example

When no records match:

{"eof":true,"count":0,"elapsed":0.021,"error":null}

HTTP Status Codes

Note: A successful HTTP 200 response does not guarantee data was found - check the count field in the status message.

Error Handling

Error Response Format

All errors return NDJSON format with status message:

{"eof":false,"count":0,"elapsed":0.002,"error":"error description"}

Error Messages

The API uses normalized, user-friendly error messages that don’t expose internal details.

Common Error Messages

Query Timeout:

{"eof":false,"count":0,"elapsed":0.002,"error":"query timeout - please refine your search or try again later"}

Causes:

• Query exceeded 120-second timeout
• Search too broad (e.g., wildcard on common term)
• No filters applied to large dataset

Solutions:

• Add limit parameter
• Add time filters (first_seen_after, etc.)
• Use more specific search type (em instead of rm)
• Filter by specific record type
• Use bailiwick filter

Temporary Error:

{"eof":false,"count":0,"elapsed":0.002,"error":"a temporary error occurred - please try again later"}

Causes:

• A temporary problem on our side
• Network interruption
• The service is briefly unavailable

Solutions:

• Retry request after a short delay
• Check system status
• Contact support if persistent

Invalid Request Error:

{"eof":false,"count":0,"elapsed":0.002,"error":"the request could not be completed - please check your search parameters"}

Causes:

• Invalid parameter combination
• Malformed query
• Unsupported operation

Solutions:

• Verify parameter syntax
• Check URL encoding (especially for CIDR)
• Review API documentation
• Simplify query

Generic Error:

{"eof":false,"count":0,"elapsed":0.002,"error":"an error occurred while processing your request"}

Causes:

• Unexpected server error
• Internal processing failure

Solutions:

• Retry request
• Contact support with request details

Error Handling in Code

Python Example:

import requests
import json

response = requests.get('https://api.deteqtive.com/api/v3/rrset/em/example.com', verify=False)

lines = response.text.strip().split('\n')
status = json.loads(lines[-1])

if not status['eof']:
    print(f"Error: {status['error']}")
    print(f"Partial results: {status['count']} records")
else:
    print(f"Success: {status['count']} records")

Bash Example:

RESULT=$(curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" -s "https://api.deteqtive.com/api/v3/rrset/em/example.com")
STATUS=$(echo "$RESULT" | tail -1)

if echo "$STATUS" | jq -e '.eof == false' > /dev/null; then
  echo "Error: $(echo $STATUS | jq -r '.error')"
  exit 1
fi

Query Timeouts

Default Timeout: 120 seconds Behavior: Queries exceeding timeout return error response Error Message: "query timeout - please refine your search or try again later"

Avoiding Timeouts

1. Use specific search types: em is faster than rm, wm, or fm
2. Add time filters: Limit the time range with first_seen_after/before
3. Set result limit: Use limit parameter to cap results
4. Filter by record type: Request only needed types (e.g., /A)
5. Use bailiwick filter: Add bailiwick path parameter for narrower search

Example of optimized query:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/example.com/A?limit=1000&first_seen_after=1704067200"

URL Encoding

CIDR Notation

CIDR blocks must have / URL-encoded as %2F:

Example:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rdata/192.0.2.0%2F24

Special Characters in Domains

If domain names contain special characters, URL-encode them:

• Space: %20
• #: %23
• %: %25
• &: %26
• +: %2B

Response Headers

Typical Response Headers:

HTTP/1.1 200 OK
Content-Type: application/x-ndjson
Cache-Control: no-cache, no-store, must-revalidate
Transfer-Encoding: chunked

Cache-Control

Responses include Cache-Control: no-cache to ensure fresh data.

Transfer-Encoding

Responses use chunked encoding to enable streaming.

Rate Limiting

Note: Rate limiting policies are server-specific. Check with your administrator.

Authentication

Note: Authentication requirements are deployment-specific. The OpenAPI spec includes optional API key authentication via Authorization header.

If authentication is required:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" \
  https://api.deteqtive.com/api/v3/rrset/em/google.com/A

Best Practices

1. Be Specific

Good:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/em/example.com/A?limit=100"

Bad:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/wm/example?limit=50000"

2. Use Time Filters

Good:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/rm/example.com?first_seen_after=1704067200"

Bad:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" "https://api.deteqtive.com/api/v3/rrset/rm/example.com?limit=50000"

3. Filter by Record Type

Good:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rrset/em/example.com/A

Bad:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/rrset/em/example.com

4. Process Streaming Responses

Don’t load entire response into memory:

Python:

for line in response.iter_lines():
    if line:
        process(json.loads(line))

Bash:

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" ... | while read -r line; do
  echo "$line" | jq ...
done

5. Handle Errors Gracefully

Always check the eof field:

status = json.loads(lines[-1])
if not status['eof']:
    handle_error(status['error'])

6. Use Appropriate Limits

• Default (1000) for exploratory queries
• Low (10-100) for testing
• High (10000-50000) only when necessary

7. URL Encode CIDR

Always encode / as %2F in CIDR notation.

8. Sort Results When Needed

Results are not sorted by default. If you need consistent ordering (e.g., for comparison or display):

# Sort by IP address
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" ... | jq -s 'map(select(.rrname)) | sort_by(.rdata)'

# Sort by first_seen
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" ... | jq -s 'map(select(.rrname)) | sort_by(.first_seen)'

OpenAPI Specification

Format: YAML Version: OpenAPI 3.0.3

Download the Specification

Via API (recommended):

curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/openapi/pdns.yaml > deteqtive-api-spec.yaml

The API serves the OpenAPI specification dynamically, ensuring you always get the correct version for your deployment.

Use Cases

1. Generate Client Libraries - Create SDKs in 40+ languages
2. Import into API Tools - Use with Postman, Insomnia, Bruno
3. Validate Requests - Test API calls before implementation
4. Generate Documentation - Create custom docs or API portals
5. API Gateway Configuration - Configure Kong, Apigee, etc.

Tools and Utilities

Interactive API Documentation (Swagger UI)

You can explore and test the API using Swagger UI.

Option 1: Using Docker

# Download the spec
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/openapi/pdns.yaml > deteqtive-api-spec.yaml

# Run Swagger UI
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/spec/deteqtive-api-spec.yaml \
  -v $(pwd):/spec \
  swaggerapi/swagger-ui

# Open in browser: http://localhost:8080

Option 2: Using npx

# Download the spec
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/openapi/pdns.yaml > deteqtive-api-spec.yaml

# Serve with Swagger UI
npx swagger-ui-dist-cli --file deteqtive-api-spec.yaml --port 8080

# Open in browser: http://localhost:8080

Validate the Specification

Ensure the OpenAPI spec is valid:

Using Swagger CLI:

# Install validator
npm install -g @apidevtools/swagger-cli

# Download spec
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/openapi/pdns.yaml > deteqtive-api-spec.yaml

# Validate
swagger-cli validate deteqtive-api-spec.yaml

Using Docker:

docker run --rm -v "${PWD}:/spec" \
  openapitools/openapi-generator-cli validate \
  -i /spec/deteqtive-api-spec.yaml

Generate Client Libraries

Generate API clients in 40+ programming languages. See the How-To: Generating API Clients section for complete examples.

Quick example - Python:

# Download spec
curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/openapi/pdns.yaml > deteqtive-api-spec.yaml

# Generate Python client
npx @openapitools/openapi-generator-cli generate \
  -i deteqtive-api-spec.yaml \
  -g python \
  -o ./deteqtive-python-client \
  --package-name deteqtive_client

# Install and use
cd deteqtive-python-client
pip install -e .

Supported languages include: Python, Go, TypeScript, JavaScript, Java, C#, Rust, PHP, Ruby, Kotlin, Swift, and many more.

Import into API Testing Tools

Postman:

1. Download the spec: curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/openapi/pdns.yaml > deteqtive-api-spec.yaml
2. Open Postman -> Import -> Upload deteqtive-api-spec.yaml
3. Collections and environments will be created automatically

Insomnia:

1. Download the spec: curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/openapi/pdns.yaml > deteqtive-api-spec.yaml
2. Open Insomnia -> Import/Export -> Import Data -> From File
3. Select deteqtive-api-spec.yaml

Bruno:

1. Download the spec: curl -H "Authorization: Bearer $DETEQTIVE_TOKEN" https://api.deteqtive.com/api/v3/openapi/pdns.yaml > deteqtive-api-spec.yaml
2. Open Bruno -> Import -> OpenAPI
3. Select deteqtive-api-spec.yaml

Example Scripts

Run all API examples:

./docs/API_EXAMPLES.sh

Set custom endpoint:

export API_BASE=https://your-server/api/v3
./docs/API_EXAMPLES.sh

Limits and Constraints

Glossary

Looking for practical examples? See How-To Guides Want to understand concepts? See Explanation