Overview

DomainIQ is a domain-intelligence API. It checks domains for Ahrefs Domain Rating (DR) and DNS availability (free / registered / live), stores full history, and serves the results for filtering and export. All endpoints accept and return JSON.

Base URL: http://localhost:3000 (replace with your deployment host). The public submit endpoint /api/check is guarded by an optionalx-api-key header (set INGEST_API_KEY to require it).

Submit domains for checking

Queues domains into both lanes (Ahrefs DR + DNS availability). Normalizes and deduplicates automatically; IDN domains are converted to punycode.

curl -X POST http://localhost:3000/api/check \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["example.com", "цик.bg", "https://www.github.com/x"],
    "name": "My batch",      // optional label
    "tag": "research-2026"   // optional filter tag
  }'

# → { "success": true, "batchJobId": "...", "stats": { "validCount": 3, ... },
#     "poll": "/api/batch/<id>" }

Retrieve results

Paginated, sortable, filterable list of domains with their latest DR and availability.

GET /api/domains?page=1&limit=50&sortBy=latestDR&sortOrder=desc
    &tld=bg                 # filter by TLD
    &registration=free      # free | registered | unknown
    &resolves=true          # has a live A record
    &source=api_submit      # how it entered
    &tag=research-2026      # batch tag
    &search=shop            # substring
    &status=checked         # checked | unchecked

# → { "domains": [ { "domain", "tld", "latestDR", "registrationStatus",
#       "resolves", "totalChecks", "lastCheckedAt" } ], "pagination": {...} }

Bulk lookup

Look up many domains at once (max 1000). Accepts raw or IDN names; normalization matches the stored form.

curl -X POST http://localhost:3000/api/domains/bulk \
  -H "Content-Type: application/json" \
  -d '{"domains": ["google.com", "bnt.bg"]}'

# → { "results": [ { "domain", "found", "latestDR", "lastCheckedAt",
#       "totalChecks" } ], "stats": { "requested", "found", "notFound" } }

Domain history

Full time-series of DR values for a domain. Each row spans checkedAt → lastConfirmedAt (change-detection: a new row only when DR changes).

GET /api/domains/google.com/history?limit=100

Export

Download the catalog as CSV or JSON, with the same filters as the list endpoint.

GET /api/export?format=csv&tld=bg&minDR=20
# columns: domain, tld, latest_dr, total_checks, first_seen, last_checked

TLD facets

Counts and average DR grouped by TLD — useful for building filters.

GET /api/domains/tlds?limit=50
# → { "tlds": [ { "tld": "bg", "count": 471535, "avgDR": 12.4 } ] }

Data model

Domain — the deduplicated entity: domain, tld,latestDR, registrationStatus (free/registered/unknown),resolves, lastCheckedAt, availabilityCheckedAt.

DomainCheck — DR history (change-detection). AvailabilityCheck — DNS history. BatchJob — a submission with optional name/tag.

Registration is conservative: a domain is only free when two independent DNS resolvers agree it does not exist. Anything ambiguous is unknown — never a false positive.