DNS API

Use DNS endpoints for diagnostic and propagation checks across public resolvers.

DNS Capabilities

GET

/2026-02-01/dns/capabilities.json

Required permissiondns:read

Path, query, and header parameters

No path, query, or additional header parameters.

Responses

Supported record types, default record types, and resolver catalog.

{
  "recordTypes": [
    "A",
    "AAAA",
    "CNAME",
    "TXT",
    "MX",
    "NS",
    "SOA",
    "CAA",
    "SRV"
  ],
  "defaultRecordTypes": [
    "A",
    "AAAA",
    "CNAME",
    "TXT"
  ],
  "resolvers": [
    {
      "id": "cloudflare_primary",
      "label": "Cloudflare (1.1.1.1)",
      "server": "1.1.1.1"
    },
    {
      "id": "google_primary",
      "label": "Google (8.8.8.8)",
      "server": "8.8.8.8"
    }
  ]
}

Request examples

curl --request GET 'https://api.hub.donutwork.com/2026-02-01/dns/capabilities.json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

const response = await fetch('https://api.hub.donutwork.com/2026-02-01/dns/capabilities.json', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer ' + process.env.DONUTWORK_API_KEY,
  },
});
const requestId = response.headers.get('x-request-id');
if (!response.ok) {
  const error = await response.text();
  throw new Error(`${response.status} ${error} [${requestId}]`);
}
const contentType = response.headers.get('content-type') ?? '';
const data = response.status === 204 ? null
  : contentType.includes('application/json') ? await response.json()
  : await response.text();

$request = curl_init('https://api.hub.donutwork.com/2026-02-01/dns/capabilities.json');
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DONUTWORK_API_KEY'),
    ],
]);
$response = curl_exec($request);
if ($response === false) {
    $error = curl_error($request);
    curl_close($request);
    throw new RuntimeException($error);
}
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$contentType = (string) curl_getinfo($request, CURLINFO_CONTENT_TYPE);
curl_close($request);
if ($status >= 400) { throw new RuntimeException($response); }
$data = $status === 204 ? null
    : (str_contains($contentType, 'application/json')
        ? json_decode($response, true, flags: JSON_THROW_ON_ERROR) : $response);

Replace uppercase placeholders and sample values with your own data and company resource IDs. Keep the API key on a trusted server. Reuse an idempotency key only for the same logical request and payload.

DNS Lookup (GET)

GET

/2026-02-01/dns/lookup.json

Required permissiondns:read

Path, query, and header parameters

targetstring· queryRequired

Hostname or IP to resolve.

recordTypesarray|string· query

Record types list (for example A, MX, TXT).

resolverPresetarray|string· query

Resolver preset filter.

customResolversstring· query

Space/comma separated custom resolvers.

Responses

DNS lookup completed.

{
  "target": "example.com",
  "generated_at": "2026-04-15T10:00:00+00:00",
  "recordTypes": [
    "A",
    "AAAA"
  ],
  "resolver_count": 2,
  "resolvers": [
    {
      "id": "cloudflare_primary",
      "label": "Cloudflare (1.1.1.1)",
      "server": "1.1.1.1"
    },
    {
      "id": "google_primary",
      "label": "Google (8.8.8.8)",
      "server": "8.8.8.8"
    }
  ],
  "propagation": {
    "A": {
      "is_consistent": true,
      "distinct_statuses": 1,
      "distinct_answers": 1
    }
  },
  "queries": {
    "A": [
      {
        "resolver_label": "Cloudflare (1.1.1.1)",
        "resolver": "1.1.1.1",
        "record_type": "A",
        "status": "NOERROR",
        "server": "1.1.1.1#53",
        "query_time_ms": 12,
        "answers": [
          {
            "name": "example.com.",
            "ttl": 300,
            "class": "IN",
            "type": "A",
            "value": "93.184.216.34"
          }
        ],
        "answer_signature": "A|93.184.216.34",
        "error": null
      }
    ]
  }
}

Invalid or missing target.

{
  "error": "target is required"
}

Request examples

curl --request GET 'https://api.hub.donutwork.com/2026-02-01/dns/lookup.json?target=example.com' \
  --header 'Authorization: Bearer YOUR_API_KEY'

const response = await fetch('https://api.hub.donutwork.com/2026-02-01/dns/lookup.json?target=example.com', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer ' + process.env.DONUTWORK_API_KEY,
  },
});
const requestId = response.headers.get('x-request-id');
if (!response.ok) {
  const error = await response.text();
  throw new Error(`${response.status} ${error} [${requestId}]`);
}
const contentType = response.headers.get('content-type') ?? '';
const data = response.status === 204 ? null
  : contentType.includes('application/json') ? await response.json()
  : await response.text();

$request = curl_init('https://api.hub.donutwork.com/2026-02-01/dns/lookup.json?target=example.com');
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DONUTWORK_API_KEY'),
    ],
]);
$response = curl_exec($request);
if ($response === false) {
    $error = curl_error($request);
    curl_close($request);
    throw new RuntimeException($error);
}
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$contentType = (string) curl_getinfo($request, CURLINFO_CONTENT_TYPE);
curl_close($request);
if ($status >= 400) { throw new RuntimeException($response); }
$data = $status === 204 ? null
    : (str_contains($contentType, 'application/json')
        ? json_decode($response, true, flags: JSON_THROW_ON_ERROR) : $response);

DNS Lookup (POST)

POST

/2026-02-01/dns/lookup.json

Required permissiondns:write

Path, query, and header parameters

No path, query, or additional header parameters.

Request Body

JSON

{
  "target": "example.com",
  "recordTypes": [
    "A",
    "AAAA"
  ],
  "resolverPreset": [
    "public"
  ],
  "customResolvers": "1.1.1.1 8.8.8.8",
  "resolvers": [
    "9.9.9.9"
  ]
}

targetstringRequired

Hostname or IP to resolve.

recordTypesarray|string

Record types list (for example A, MX, TXT).

resolverPresetarray|string

Resolver preset filter.

customResolversstring

Space/comma separated custom resolvers.

resolversarray

Additional custom resolver list.

Responses

DNS lookup completed.

{
  "target": "example.com",
  "generated_at": "2026-04-15T10:00:00+00:00",
  "recordTypes": [
    "A",
    "AAAA"
  ],
  "resolver_count": 2,
  "resolvers": [
    {
      "id": "cloudflare_primary",
      "label": "Cloudflare (1.1.1.1)",
      "server": "1.1.1.1"
    },
    {
      "id": "google_primary",
      "label": "Google (8.8.8.8)",
      "server": "8.8.8.8"
    }
  ],
  "propagation": {
    "A": {
      "is_consistent": true,
      "distinct_statuses": 1,
      "distinct_answers": 1
    }
  },
  "queries": {
    "A": [
      {
        "resolver_label": "Cloudflare (1.1.1.1)",
        "resolver": "1.1.1.1",
        "record_type": "A",
        "status": "NOERROR",
        "server": "1.1.1.1#53",
        "query_time_ms": 12,
        "answers": [
          {
            "name": "example.com.",
            "ttl": 300,
            "class": "IN",
            "type": "A",
            "value": "93.184.216.34"
          }
        ],
        "answer_signature": "A|93.184.216.34",
        "error": null
      }
    ]
  }
}

Request examples

curl --request POST 'https://api.hub.donutwork.com/2026-02-01/dns/lookup.json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "target": "example.com",
  "recordTypes": [
    "A",
    "AAAA"
  ],
  "resolverPreset": [
    "public"
  ],
  "customResolvers": "1.1.1.1 8.8.8.8",
  "resolvers": [
    "9.9.9.9"
  ]
}'

const response = await fetch('https://api.hub.donutwork.com/2026-02-01/dns/lookup.json', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.DONUTWORK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "target": "example.com",
    "recordTypes": [
      "A",
      "AAAA"
    ],
    "resolverPreset": [
      "public"
    ],
    "customResolvers": "1.1.1.1 8.8.8.8",
    "resolvers": [
      "9.9.9.9"
    ]
  }),
});
const requestId = response.headers.get('x-request-id');
if (!response.ok) {
  const error = await response.text();
  throw new Error(`${response.status} ${error} [${requestId}]`);
}
const contentType = response.headers.get('content-type') ?? '';
const data = response.status === 204 ? null
  : contentType.includes('application/json') ? await response.json()
  : await response.text();

$request = curl_init('https://api.hub.donutwork.com/2026-02-01/dns/lookup.json');
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DONUTWORK_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "target": "example.com",
  "recordTypes": [
    "A",
    "AAAA"
  ],
  "resolverPreset": [
    "public"
  ],
  "customResolvers": "1.1.1.1 8.8.8.8",
  "resolvers": [
    "9.9.9.9"
  ]
}',
]);
$response = curl_exec($request);
if ($response === false) {
    $error = curl_error($request);
    curl_close($request);
    throw new RuntimeException($error);
}
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$contentType = (string) curl_getinfo($request, CURLINFO_CONTENT_TYPE);
curl_close($request);
if ($status >= 400) { throw new RuntimeException($response); }
$data = $status === 204 ? null
    : (str_contains($contentType, 'application/json')
        ? json_decode($response, true, flags: JSON_THROW_ON_ERROR) : $response);

DNS API

DNS Capabilities

Path, query, and header parameters

Responses

Request examples

DNS Lookup (GET)

Path, query, and header parameters

Responses

Request examples

DNS Lookup (POST)

Path, query, and header parameters

Request Body

Responses

Request examples

On this page