vectordns-server/docs/api-reference.md

API Reference

Complete reference for the VectorDNS Go server REST API.

Base URL & Authentication

Base URL: https://<your-vps-host>/api/v1

All requests (except /health) require an API key header:

X-API-Key: <your-shared-secret>

Set API_KEY in your server environment to enable authentication. If left empty, auth is disabled (not recommended for production).

---

Endpoints

POST /dns/lookup

Resolve DNS records for a domain. Query one or more record types in a single request.

Request:

{
  "domain": "example.com",
  "types": ["A", "AAAA", "MX", "TXT", "NS", "CNAME", "SOA", "CAA", "SRV"],
  "nameserver": "8.8.8.8"
}

Field	Required	Description
domain	Yes	The domain to query.
types	No	Record types to query. Defaults to all 9 supported types if omitted.
nameserver	No	Specific nameserver to query. Defaults to system resolver.

Response (200):

{
  "domain": "example.com",
  "nameserver": "8.8.8.8",
  "records": {
    "A": [{ "value": "93.184.216.34", "ttl": 300 }],
    "MX": [{ "value": "mail.example.com", "priority": 10, "ttl": 3600 }]
  },
  "query_time_ms": 12
}

---

POST /dns/propagation

Check DNS propagation across multiple public resolvers. Queries resolvers in parallel and compares results.

Request:

{
  "domain": "example.com",
  "type": "A",
  "resolvers": ["8.8.8.8", "1.1.1.1", "9.9.9.9"]
}

Field	Required	Description
domain	Yes	The domain to check.
type	Yes	The record type to check (e.g. A, MX).
resolvers	No	List of resolver IPs. Defaults to a built-in list of public resolvers.

Response (200):

{
  "domain": "example.com",
  "type": "A",
  "results": [
    { "resolver": "8.8.8.8", "values": ["93.184.216.34"], "ttl": 300 },
    { "resolver": "1.1.1.1", "values": ["93.184.216.34"], "ttl": 280 },
    { "resolver": "9.9.9.9", "values": ["93.184.216.34"], "ttl": 295 }
  ],
  "consistent": true
}

---

POST /dns/validate

DNSSEC validation for a domain. Checks the AD flag and verifies the signature chain.

Request:

{
  "domain": "example.com"
}

Field	Required	Description
domain	Yes	The domain to validate.

Response (200):

{
  "domain": "example.com",
  "dnssec": true,
  "chain_valid": true,
  "details": "RRSIG verified for A record"
}

---

GET /health

Health check. No authentication required. Use this for uptime monitoring.

Response (200):

{
  "status": "ok",
  "version": "0.1.0"
}

---

Error Responses

All errors return a consistent JSON body:

{
  "error": "invalid domain",
  "code": "INVALID_DOMAIN"
}

HTTP Status	Code	Description
400	INVALID_DOMAIN	Malformed or missing domain
400	INVALID_TYPE	Unsupported record type
401	UNAUTHORIZED	Missing or invalid API key
500	DNS_ERROR	Upstream DNS query failed
500	INTERNAL	Unexpected server error