DETEQTIVE DNS - End User Documentation

DETEQTIVE DNS - Global Uncached Lookup Log Your passive DNS flight recorder

Welcome to the DETEQTIVE DNS API documentation.

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"

Documentation Structure

This documentation is organized into four types to help you find what you need:

Tutorial - Learning-oriented

Start here if you’re new to the DETEQTIVE DNS API

• Getting started with your first query
• Understanding passive DNS concepts
• Step-by-step examples
• Building your first integration

How-To Guides - Problem-oriented

Practical guides for specific tasks

• Searching for domains and subdomains
• Finding DNS records by IP address
• Filtering results by time ranges
• Working with CIDR blocks
• Handling large result sets
• Generating API clients

Reference - Information-oriented

Complete technical reference

• Full endpoint documentation
• All query parameters
• Response format specification
• Error messages and codes
• DNS record types
• Search type reference

Explanation - Understanding-oriented

Concepts and design decisions

• What is Passive DNS?
• How the API works
• Search strategies explained
• Response streaming
• Error handling philosophy
• Security and privacy

Quick Start

Your First Query

Search for all A records for google.com:

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

Response (NDJSON format):

{"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}
{"eof":true,"count":1,"elapsed":0.102,"error":null}

New to the API? Start with the Tutorial

Common Use Cases

API Endpoints Overview

Forward Search (RRSet)

Search DNS records by domain name:

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

Search Types:

• em - Exact Match (google.com)
• rm - Right Match (*.google.com)
• lm - Left Match (google.*)
• fm - Fuzzy Match (similar domains)
• wm - Word Match (contains token)

Reverse Search (RData)

Search DNS records by IP, CIDR, or hostname:

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

Supported Values:

• IPv4: 1.2.3.4
• IPv6: 2001:db8::1
• IPv4 CIDR: 192.0.2.0%2F24
• IPv6 CIDR: 2001:db8::%2F32
• Hostname: ns1.example.com

Tools & Resources

OpenAPI Specification

The API provides an OpenAPI 3.0.3 specification that you can use to generate client libraries, import into API tools, and more.

Download the spec:

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

Generate a Python client:

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

Generate a Go client:

npx @openapitools/openapi-generator-cli generate \
  -i deteqtive-openapi.yaml \
  -g go \
  -o ./deteqtive-go-client \
  --package-name deteqtive

See How-To: Generate API Clients for complete examples.

Response Format

All API responses use NDJSON (Newline-Delimited JSON):

• Each line is a valid JSON object
• Records are streamed as available
• Last line contains status information
• Important: If the eof status line is missing, the response was truncated
• Note: Results are not sorted - the same query may return records in different order on subsequent requests

Example response:

{"rrname":"example.com","rrtype":"A","rdata":"93.184.216.34","first_seen":"2023-01-01T00:00:00Z","last_seen":"2023-12-31T23:59:59Z","sightings":500}
{"rrname":"example.com","rrtype":"A","rdata":"93.184.216.35","first_seen":"2023-06-01T00:00:00Z","last_seen":"2023-12-31T23:59:59Z","sightings":200}
{"eof":true,"count":2,"elapsed":0.102,"error":null}

Learn more: Explanation: NDJSON Streaming

Error Handling

The API uses normalized, user-friendly error messages that protect backend implementation details:

{"eof":false,"count":0,"elapsed":0.002,"error":"query timeout - please refine your search or try again later"}
{"eof":false,"count":0,"elapsed":0.002,"error":"a temporary error occurred - please try again later"}
{"eof":false,"count":0,"elapsed":0.002,"error":"the request could not be completed - please check your search parameters"}

All errors return:

• eof: false - Query did not complete successfully
• count: N - Number of records returned before error
• elapsed: N - Time elapsed before error, in seconds
• error: "message" - User-friendly error description

Learn more: Reference: Error Messages

Query Timeouts

• Default timeout: 120 seconds
• Default time window: Last 14 days (records with last_seen in past 2 weeks)
• Behavior: Queries exceeding timeout return an error
• Error message: "query timeout - please refine your search or try again later"
• Recommendation: Use more specific filters (limit, time ranges, record types)
• Note: To query all historical data, explicitly set last_seen_after=0

Getting Help

Quick Answers

Q: How do I encode CIDR notation in URLs? A: Replace / with %2F: 192.0.2.0/24 -> 192.0.2.0%2F24

Q: How do I include bailiwick information? A: Add ?withbailiwick query parameter (no value needed)

Q: What’s the maximum number of results? A: 50,000 records per request (default: 1,000)

Q: What are the supported DNS record types? A: A, AAAA, CNAME, MX, NS, TXT, SOA, PTR, SRV, and more. See Reference: DNS Record Types

Q: Why do results come back in different order each time? A: Results are not sorted for performance. Sort client-side if needed: | jq -s 'sort_by(.rdata)'

More Help

• See Tutorial for guided learning
• See Reference for complete technical details
• See Explanation for concepts and design

Ready to start? Begin with the Tutorial