API Documentation

Base URL

https://tools.bd/api/v1

Authentication

No authentication required. All endpoints are publicly accessible.

Rate Limiting

Limit	20 requests per minute per IP address
Window	60 seconds (sliding window)
Concurrent Scans	Maximum 5 simultaneous scans
Rate Limit Response	429 Too Many Requests

Endpoints

Health Check

Check if the API is running.

Response

{
  "status": "ok",
  "time": "2026-08-09T21:00:00Z"
}

Full Domain Scan

Perform a comprehensive DNS and WHOIS analysis for a domain. Returns all sections in a single JSON response.

Parameters

domain	Required. Domain name to scan (e.g., google.com)
?private=1	Optional. Prevents the scan from being stored in the database

Response

{
  "domain": "example.com",
  "scan_id": "example.com-1234567890",
  "started_at": "2026-08-09T21:00:00Z",
  "completed_at": "2026-08-09T21:00:02Z",
  "rdap": { ... },
  "dns_records": [ ... ],
  "parent_ns": [ ... ],
  "auth_ns": [ ... ],
  "soa": { ... },
  "mx": [ ... ],
  "www": [ ... ],
  "dnssec": { ... },
  "spf": { ... },
  "dmarc": { ... },
  "caa": [ ... ],
  "propagation": [ ... ],
  "health": {
    "score": 76,
    "grade": "C",
    "passes": 34,
    "warnings": 6,
    "failures": 0,
    "infos": 6,
    "total": 46
  }
}

Sections Included

• rdap — Domain registration data (registrar, dates, status)
• dns_records — All DNS records (A, AAAA, NS, MX, SOA, TXT, CAA, DS, DNSKEY, SRV)
• parent_ns — Parent nameserver delegation info
• auth_ns — Authoritative nameserver tests (reachability, auth flag, recursion)
• soa — SOA record analysis
• mx — Mail server analysis
• www — WWW/CNAME analysis
• dnssec — DNSSEC chain validation
• spf — SPF record analysis
• dmarc — DMARC policy analysis
• caa — CAA records
• propagation — DNS propagation across 10 resolvers
• health — Overall health score and grade

Stream Scan (SSE)

Same as full scan but returns results as Server-Sent Events (SSE) for real-time updates.

Parameters

domain	Required. Domain name to scan
?private=1	Optional. Prevents storage

SSE Events

event: start
data: {"domain":"example.com","scan_id":"..."}

event: section:rdap
data: { ... RDAP data ... }

event: section:dns_records
data: [ ... DNS records ... ]

event: section:parent_ns
data: [ ... nameserver data ... }

event: section:auth_ns
data: [ ... auth NS tests ... ]

event: section:soa
data: { ... SOA data ... }

event: section:mx
data: [ ... MX data ... ]

event: section:www
data: [ ... WWW data ... ]

event: section:dnssec
data: { ... DNSSEC data ... }

event: section:security
data: {"spf":{...},"dmarc":{...},"caa":[...]}

event: section:propagation
data: [ ... propagation data ... ]

event: complete:all
data: { ... health score ... }

event: done
data: {"domain":"example.com"}

RDAP/WHOIS Only

Fast RDAP/WHOIS lookup only. Returns registration data without DNS analysis.

Parameters

domain

Required. Domain name to lookup

Response

{
  "domain": "example.com",
  "registry": "Verisign",
  "registrar": "Example Registrar Inc.",
  "created_date": "1995-08-14T04:00:00Z",
  "updated_date": "2023-08-14T04:00:00Z",
  "expires_date": "2028-08-13T04:00:00Z",
  "status": ["client delete prohibited", "client transfer prohibited"],
  "nameservers": ["ns1.example.com", "ns2.example.com"],
  "dnssec": "unsigned",
  "available": false,
  "privacy_guard": false
}

DNS Records Only

Returns DNS records without full analysis.

Recent Scans

Returns the last 50 public scans. Cached for 30 seconds.

Response

{
  "scans": [
    {
      "domain": "google.com",
      "scan_id": "google.com-1234567890",
      "updated_at": "2026-08-09T21:00:00Z",
      "health": {"score": 70, "grade": "C", ...}
    },
    ...
  ]
}

Generate Share Link

Generates (or returns existing) share token for a domain. The domain must have been scanned first.

Parameters

domain

Required. Domain name to generate share link for

Response

{
  "share_token": "abc123def456...",
  "share_url": "https://tools.bd/share/abc123def456..."
}

Get Shared Scan

Retrieves a scan by its share token. Returns full scan result.

Parameters

token

Required. Share token (32 character hex string)

Response

Same as full scan response. Returns 404 if token not found or expired.

Sitemap Domains

Returns all public domains for sitemap generation.

Response

{
  "domains": ["google.com", "github.com", "cloudflare.com", ...]
}

Error Responses

All errors follow this format:

{
  "error": true,
  "message": "Description of the error"
}

HTTP Status Codes

200	Success
400	Bad request (invalid domain, missing parameters)
404	Not found (invalid share token)
429	Rate limit exceeded (20 requests/minute)
500	Internal server error

Response Headers

X-Cache	HIT if response served from cache
Content-Type	application/json for all endpoints
Cache-Control	no-store for scan results (always fresh)

Caching

• Scan results — Cached in Redis for 2 minutes. Subsequent requests for the same domain return cached results.
• Recent scans — Cached for 30 seconds.
• Shared scans — Cached for 1 hour.
• Sitemap domains — Cached for 30 seconds.

Usage Examples

cURL

# Full scan
curl https://tools.bd/api/v1/scan/google.com

# RDAP only
curl https://tools.bd/api/v1/domain/google.com

# Stream scan (SSE)
curl -N https://tools.bd/api/v1/scan/google.com/stream

# Recent scans
curl https://tools.bd/api/v1/recent

# Generate share link
curl -X POST https://tools.bd/api/v1/share/google.com

# Private scan (not stored)
curl "https://tools.bd/api/v1/scan/google.com?private=1"

JavaScript (fetch)

// Full scan
const response = await fetch('https://tools.bd/api/v1/scan/google.com');
const data = await response.json();
console.log(data.health.grade); // "C"

// Stream scan (SSE)
const eventSource = new EventSource('https://tools.bd/api/v1/scan/google.com/stream');
eventSource.addEventListener('section:rdap', (e) => {
  const rdap = JSON.parse(e.data);
  console.log('RDAP:', rdap);
});
eventSource.addEventListener('complete:all', (e) => {
  const health = JSON.parse(e.data);
  console.log('Grade:', health.grade);
  eventSource.close();
});

Python

import requests

# Full scan
response = requests.get('https://tools.bd/api/v1/scan/google.com')
data = response.json()
print(f"Grade: {data['health']['grade']}")

# Stream scan
import sseclient
response = requests.get('https://tools.bd/api/v1/scan/google.com/stream', stream=True)
client = sseclient.SSEClient(response)
for event in client.events():
    print(f"{event.event}: {event.data[:50]}...")

Data Retention

• Public scans are stored for 30 days
• Private scans (?private=1) are not stored
• Share tokens are valid for 30 days
• Expired data is automatically cleaned up

Contact

For API questions or issues:

• info@tools.bd
• hello@mehedims.com