Table of Contents

Interface IDnsApi

Namespace
Cloudflare.NET.Dns
Assembly
Cloudflare.NET.dll

Defines the contract for DNS record operations.

All DNS operations are zone-scoped and require a zone ID. This API provides complete CRUD operations for DNS records, including single-record operations, batch operations, and import/export functionality. 

public interface IDnsApi

Examples

// Create a DNS record
var record = await dns.CreateDnsRecordAsync(zoneId, new CreateDnsRecordRequest(
  DnsRecordType.A, "www.example.com", "192.0.2.1", Proxied: true
));

// List all records
await foreach (var r in dns.ListAllDnsRecordsAsync(zoneId))
{
  Console.WriteLine($"{r.Name} ({r.Type}): {r.Content}");
}

// Batch operations
var batch = new BatchDnsRecordsRequest(
  Posts: [new CreateDnsRecordRequest(DnsRecordType.A, "new.example.com", "192.0.2.2")]
);
await dns.BatchDnsRecordsAsync(zoneId, batch);

Methods

BatchDnsRecordsAsync(string, BatchDnsRecordsRequest, CancellationToken)

Performs batch DNS record operations in a single API call.

Execution Order: Deletes → Patches → Puts → Posts. This order allows you to delete a record and re-create it with the same name in one batch. 

Task<BatchDnsRecordsResult> BatchDnsRecordsAsync(string zoneId, BatchDnsRecordsRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

request BatchDnsRecordsRequest

The batch request containing operations to perform.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<BatchDnsRecordsResult>

The result containing the outcome of each operation type.

Examples

var batch = new BatchDnsRecordsRequest(
  Deletes: [new BatchDeleteOperation("old-record-id")],
  Posts: [new CreateDnsRecordRequest(DnsRecordType.A, "new.example.com", "192.0.2.1")]
);
var result = await dns.BatchDnsRecordsAsync(zoneId, batch);
Console.WriteLine($"Deleted: {result.Deletes?.Count ?? 0}, Created: {result.Posts?.Count ?? 0}");

Exceptions

ArgumentNullException

Thrown when zoneId or request is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

CreateCnameRecordAsync(string, string, string, bool, int, CancellationToken)

Creates a CNAME record (convenience method).

Task<DnsRecord> CreateCnameRecordAsync(string zoneId, string name, string target, bool proxied = false, int ttl = 1, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

name string

The hostname for the CNAME record (e.g., "cdn.example.com").

target string

The target hostname the CNAME points to.

proxied bool

Whether to proxy the record through Cloudflare.

ttl int

Time to live in seconds. Default: 1 (automatic).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsRecord>

The newly created CNAME record.

Examples

var record = await dns.CreateCnameRecordAsync(zoneId, "cdn.example.com", "cdn.provider.com", proxied: true);

Exceptions

ArgumentNullException

Thrown when zoneId, name, or target is null.

ArgumentException

Thrown when any required string parameter is empty or whitespace.

CreateDnsRecordAsync(string, CreateDnsRecordRequest, CancellationToken)

Creates a new DNS record of any type.

Task<DnsRecord> CreateDnsRecordAsync(string zoneId, CreateDnsRecordRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

request CreateDnsRecordRequest

The DNS record creation request.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsRecord>

The newly created DNS record with its assigned ID.

Examples

var request = new CreateDnsRecordRequest(DnsRecordType.A, "www.example.com", "192.0.2.1", Proxied: true);
var record = await dns.CreateDnsRecordAsync(zoneId, request);
Console.WriteLine($"Created record with ID: {record.Id}");

Exceptions

ArgumentNullException

Thrown when zoneId or request is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

DeleteDnsRecordAsync(string, string, CancellationToken)

Deletes a DNS record by its ID.

Task DeleteDnsRecordAsync(string zoneId, string dnsRecordId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

dnsRecordId string

The DNS record identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task representing the asynchronous operation.

Examples

await dns.DeleteDnsRecordAsync(zoneId, recordId);
Console.WriteLine("Record deleted successfully.");

Exceptions

ArgumentNullException

Thrown when zoneId or dnsRecordId is null.

ArgumentException

Thrown when any required string parameter is empty or whitespace.

See Also

ExportDnsRecordsAsync(string, CancellationToken)

Exports DNS records in BIND zone file format.

Task<string> ExportDnsRecordsAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<string>

A string containing the zone's records in BIND format.

Examples

var bindContent = await dns.ExportDnsRecordsAsync(zoneId);
await File.WriteAllTextAsync("zone.txt", bindContent);

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

FindDnsRecordByNameAsync(string, string, DnsRecordType?, CancellationToken)

Finds a DNS record by its hostname within a zone.

Task<DnsRecord?> FindDnsRecordByNameAsync(string zoneId, string hostname, DnsRecordType? type = null, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

hostname string

The fully qualified domain name to search for.

type DnsRecordType?

Optional: filter by record type to avoid ambiguity when multiple record types exist for the same name.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsRecord>

The matching DNS record, or null if not found. If multiple records match (e.g., both A and AAAA), returns the first one.

Examples

var record = await dns.FindDnsRecordByNameAsync(zoneId, "www.example.com");
if (record != null)
{
  Console.WriteLine($"Found: {record.Content}");
}

Exceptions

ArgumentNullException

Thrown when zoneId or hostname is null.

ArgumentException

Thrown when zoneId or hostname is empty or whitespace.

GetDnsRecordAsync(string, string, CancellationToken)

Gets a DNS record by its unique identifier.

Task<DnsRecord> GetDnsRecordAsync(string zoneId, string dnsRecordId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

dnsRecordId string

The DNS record identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsRecord>

The DNS record with all its properties.

Examples

var record = await dns.GetDnsRecordAsync(zoneId, recordId);
Console.WriteLine($"{record.Name}: {record.Content}");

Exceptions

ArgumentNullException

Thrown when zoneId or dnsRecordId is null.

ArgumentException

Thrown when zoneId or dnsRecordId is empty or whitespace.

See Also

GetDnsRecordScanReviewAsync(string, CancellationToken)

Gets DNS records discovered by scanning that are pending review.

These records are temporary until accepted or rejected via SubmitDnsRecordScanReviewAsync(string, DnsScanReviewRequest, CancellationToken). 

Task<IReadOnlyList<DnsRecord>> GetDnsRecordScanReviewAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<IReadOnlyList<DnsRecord>>

List of scanned DNS records pending review.

Examples

var pending = await dns.GetDnsRecordScanReviewAsync(zoneId);
foreach (var record in pending)
{
  Console.WriteLine($"{record.Type} {record.Name} -> {record.Content}");
}

Remarks

Records expire after 30 days if not reviewed. Use SubmitDnsRecordScanReviewAsync(string, DnsScanReviewRequest, CancellationToken) to accept or reject records.

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

ImportDnsRecordsAsync(string, string, bool, CancellationToken)

Imports DNS records from BIND zone file format.

Task<DnsImportResult> ImportDnsRecordsAsync(string zoneId, string bindContent, bool proxied = false, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

bindContent string

The BIND zone file content as a string.

proxied bool

Whether to proxy imported records through Cloudflare.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsImportResult>

A result object with a summary of the import operation.

Examples

var bindContent = await File.ReadAllTextAsync("zone.txt");
var result = await dns.ImportDnsRecordsAsync(zoneId, bindContent, proxied: true);
Console.WriteLine($"Added: {result.RecordsAdded}, Parsed: {result.TotalRecordsParsed}");

Exceptions

ArgumentNullException

Thrown when zoneId or bindContent is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

ListAllDnsRecordsAsync(string, ListDnsRecordsFilters?, CancellationToken)

Lists all DNS records, automatically handling pagination.

IAsyncEnumerable<DnsRecord> ListAllDnsRecordsAsync(string zoneId, ListDnsRecordsFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

filters ListDnsRecordsFilters

Optional filters for sorting and matching. Pagination options will be managed internally.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<DnsRecord>

An asynchronous stream of all matching DNS records.

Examples

await foreach (var record in dns.ListAllDnsRecordsAsync(zoneId))
{
  Console.WriteLine($"{record.Name} ({record.Type}): {record.Content}");
}

Remarks

This method automatically handles pagination by making multiple API requests as needed. The Page and PerPage properties are managed internally and will be ignored if provided.

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

ListDnsRecordsAsync(string, ListDnsRecordsFilters?, CancellationToken)

Lists DNS records with filtering and pagination support.

Task<PagePaginatedResult<DnsRecord>> ListDnsRecordsAsync(string zoneId, ListDnsRecordsFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

filters ListDnsRecordsFilters

Optional filters for pagination, sorting, and matching.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<PagePaginatedResult<DnsRecord>>

A single page of DNS records along with pagination information.

Examples

// Get first page of A records
var result = await dns.ListDnsRecordsAsync(zoneId, new ListDnsRecordsFilters(Type: DnsRecordType.A));
foreach (var record in result.Items)
{
  Console.WriteLine($"{record.Name}: {record.Content}");
}

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

PatchDnsRecordAsync(string, string, PatchDnsRecordRequest, CancellationToken)

Partially updates a DNS record (PATCH).

Task<DnsRecord> PatchDnsRecordAsync(string zoneId, string dnsRecordId, PatchDnsRecordRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

dnsRecordId string

The DNS record identifier.

request PatchDnsRecordRequest

The fields to update. Only non-null fields will be changed.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsRecord>

The updated DNS record.

Examples

// Change only the content
var patch = new PatchDnsRecordRequest(Content: "192.0.2.100");
var updated = await dns.PatchDnsRecordAsync(zoneId, recordId, patch);

Exceptions

ArgumentNullException

Thrown when any required parameter is null.

ArgumentException

Thrown when any required string parameter is empty or whitespace.

See Also

SubmitDnsRecordScanReviewAsync(string, DnsScanReviewRequest, CancellationToken)

Accepts or rejects scanned DNS records.

Accepted records become permanent DNS records in the zone. Rejected records are discarded. 

Task<DnsScanReviewResult> SubmitDnsRecordScanReviewAsync(string zoneId, DnsScanReviewRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

request DnsScanReviewRequest

The accept/reject decisions.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsScanReviewResult>

Counts of accepted and rejected records.

Examples

// Get pending records from scan review queue
var pending = await dns.GetDnsRecordScanReviewAsync(zoneId);

// Accept A and AAAA records (pass full record objects), reject others (pass just IDs)
var accepts = pending
  .Where(r => r.Type == DnsRecordType.A || r.Type == DnsRecordType.AAAA)
  .ToList();

var rejects = pending
  .Where(r => r.Type != DnsRecordType.A && r.Type != DnsRecordType.AAAA)
  .Select(r => r.Id)
  .ToList();

var result = await dns.SubmitDnsRecordScanReviewAsync(zoneId,
  new DnsScanReviewRequest { Accepts = accepts, Rejects = rejects });

Console.WriteLine($"Accepted: {result.Accepts}, Rejected: {result.Rejects}");

Remarks

Preview: This operation has limited test coverage.

Exceptions

ArgumentNullException

Thrown when zoneId or request is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

TriggerDnsRecordScanAsync(string, CancellationToken)

Triggers an asynchronous DNS record scan for the zone.

The scan discovers existing DNS records by querying authoritative nameservers. Results are placed in a review queue accessible via GetDnsRecordScanReviewAsync(string, CancellationToken). 

Task TriggerDnsRecordScanAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task representing the asynchronous operation.

Examples

// Trigger scan
await dns.TriggerDnsRecordScanAsync(zoneId);

// Wait briefly for initial results (in production, use polling)
await Task.Delay(TimeSpan.FromSeconds(5));

// Get scanned records for review
var pending = await dns.GetDnsRecordScanReviewAsync(zoneId);

Remarks

This operation runs asynchronously. The method returns immediately while the scan continues in the background. Poll GetDnsRecordScanReviewAsync(string, CancellationToken) to check for results.

Scanned records remain in the review queue for 30 days before automatic expiration.

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

UpdateDnsRecordAsync(string, string, UpdateDnsRecordRequest, CancellationToken)

Fully replaces a DNS record (PUT).

Task<DnsRecord> UpdateDnsRecordAsync(string zoneId, string dnsRecordId, UpdateDnsRecordRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

dnsRecordId string

The DNS record identifier.

request UpdateDnsRecordRequest

The complete record data to replace with.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsRecord>

The updated DNS record.

Examples

var request = new UpdateDnsRecordRequest(DnsRecordType.A, "www.example.com", "192.0.2.100");
var updated = await dns.UpdateDnsRecordAsync(zoneId, recordId, request);

Remarks

This operation performs a complete replacement. Use PatchDnsRecordAsync(string, string, PatchDnsRecordRequest, CancellationToken) for partial updates when you only want to change specific fields.

Exceptions

ArgumentNullException

Thrown when any required parameter is null.

ArgumentException

Thrown when any required string parameter is empty or whitespace.

See Also

See Also

https://developers.cloudflare.com/api/resources/dns/subresources/records/
Edit this page