Table of Contents

Class ZonesApi

Namespace
Cloudflare.NET.Zones
Assembly
Cloudflare.NET.dll

Implements the API for managing Cloudflare Zone resources.

public class ZonesApi : ApiResource, IZonesApi
Inheritance
ZonesApi
Implements
Inherited Members

Constructors

ZonesApi(HttpClient, ILoggerFactory)

Initializes a new instance of the ZonesApi class.

public ZonesApi(HttpClient httpClient, ILoggerFactory loggerFactory)

Parameters

httpClient HttpClient

The HttpClient for making requests.

loggerFactory ILoggerFactory

The factory to create loggers for this and child resources.

Properties

AccessRules

Gets the API for managing zone-level IP Access Rules.

public IZoneAccessRulesApi AccessRules { get; }

Property Value

IZoneAccessRulesApi

Remarks

Corresponds to the /zones/{zone_id}/firewall/access_rules/rules endpoint.

CustomHostnames

Gets the API for managing Custom Hostnames (Cloudflare for SaaS).

public ICustomHostnamesApi CustomHostnames { get; }

Property Value

ICustomHostnamesApi

Remarks

Corresponds to the /zones/{zone_id}/custom_hostnames endpoint family.

Lockdown

Gets the API for managing Zone Lockdown rules.

public IZoneLockdownApi Lockdown { get; }

Property Value

IZoneLockdownApi

Remarks

Corresponds to the /zones/{zone_id}/firewall/lockdowns endpoint.

Rulesets

Gets the API for managing zone-level Rulesets (e.g., WAF, Redirects).

public IZoneRulesetsApi Rulesets { get; }

Property Value

IZoneRulesetsApi

Remarks

Corresponds to the /zones/{zone_id}/rulesets endpoint family.

UaRules

Gets the API for managing User-Agent blocking rules.

public IZoneUaRulesApi UaRules { get; }

Property Value

IZoneUaRulesApi

Remarks

Corresponds to the /zones/{zone_id}/firewall/ua_rules endpoint.

Methods

CreateCnameRecordAsync(string, string, string, CancellationToken)

Creates a CNAME DNS record, typically used to point a custom domain to Cloudflare's infrastructure.

public Task<DnsRecord> CreateCnameRecordAsync(string zoneId, string hostname, string cnameTarget, CancellationToken cancellationToken = default)

Parameters

zoneId string

The ID of the zone where the record will be created.

hostname string

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

cnameTarget string

The target the CNAME should point to.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsRecord>

A task that represents the asynchronous operation. The task result contains the DnsRecord with details of the created record.

CreateZoneAsync(CreateZoneRequest, CancellationToken)

Creates a new zone.

public Task<Zone> CreateZoneAsync(CreateZoneRequest request, CancellationToken cancellationToken = default)

Parameters

request CreateZoneRequest

The zone creation request with name, type, and account.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Zone>

The newly created zone.

Examples

var request = new CreateZoneRequest(
  Name: "example.com",
  Type: ZoneType.Full,
  Account: new ZoneAccountReference("account-id")
);
var zone = await zonesApi.CreateZoneAsync(request);

Remarks

Preview: This operation has limited test coverage.

The zone will initially have a status of Pending until nameserver verification completes.

Use TriggerActivationCheckAsync(string, CancellationToken) to manually trigger verification.

Exceptions

ArgumentNullException

Thrown when request is null.

See Also

CreateZoneHoldAsync(string, bool, CancellationToken)

Creates/enforces a zone hold, blocking creation of zones with this hostname.

public Task<ZoneHold> CreateZoneHoldAsync(string zoneId, bool includeSubdomains = false, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

includeSubdomains bool

When true, the hold extends to block any subdomain and SSL4SaaS Custom Hostnames. For example, a hold on "example.com" would also block "staging.example.com".

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ZoneHold>

The created zone hold.

Examples

// Create a basic hold
var hold = await zonesApi.CreateZoneHoldAsync(zoneId);

// Create a hold that includes subdomains
var holdWithSubdomains = await zonesApi.CreateZoneHoldAsync(zoneId, includeSubdomains: true);

Remarks

Preview: This operation has limited test coverage.

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

DeleteDnsRecordAsync(string, string, CancellationToken)

Deletes a DNS record by its ID within a specific zone.

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

Parameters

zoneId string

The ID of the zone where the record exists.

dnsRecordId string

The unique identifier of the DNS record to delete.

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

DeleteZoneAsync(string, CancellationToken)

Deletes a zone permanently.

public Task DeleteZoneAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The identifier of the zone to delete.

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

Remarks

Preview: This operation has limited test coverage.

Warning: This operation is irreversible. All DNS records, settings, and configuration for the zone will be permanently deleted.

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

EditZoneAsync(string, EditZoneRequest, CancellationToken)

Edits a zone's properties. Only one property can be changed per call.

public Task<Zone> EditZoneAsync(string zoneId, EditZoneRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The identifier of the zone to edit.

request EditZoneRequest

The edit request with the property to change.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Zone>

The updated zone.

Examples

// Pause a zone
var request = new EditZoneRequest(Paused: true);
var zone = await zonesApi.EditZoneAsync(zoneId, request);

Remarks

Preview: This operation has limited test coverage.

Important: Only one property can be changed per API call. Use the convenience methods (SetZonePausedAsync(string, bool, CancellationToken), SetZoneTypeAsync(string, ZoneType, CancellationToken), SetVanityNameServersAsync(string, IReadOnlyList<string>, CancellationToken)) for clearer intent.

Exceptions

ArgumentNullException

Thrown when zoneId or request is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

ExportDnsRecordsAsync(string, CancellationToken)

Exports all DNS records for a zone in BIND format.

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

Parameters

zoneId string

The ID of the zone.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<string>

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

FindDnsRecordByNameAsync(string, string, CancellationToken)

Finds a DNS record by its fully qualified name within a specific zone.

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

Parameters

zoneId string

The ID of the zone to search in.

hostname string

The name of the DNS record to find (e.g., "test.example.com").

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsRecord>

A task that represents the asynchronous operation. The task result contains the DnsRecord if found; otherwise, null. If multiple records exist with the same name (e.g., A and AAAA), this method returns the first one from the API response.

GetZoneDetailsAsync(string, CancellationToken)

Fetches the details for a specific Zone by its ID.

public Task<Zone> GetZoneDetailsAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The identifier of the Zone.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Zone>

A task that represents the asynchronous operation. The task result contains the Zone details.

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

GetZoneHoldAsync(string, CancellationToken)

Gets the zone hold status and configuration.

public Task<ZoneHold> GetZoneHoldAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ZoneHold>

The zone hold status.

Examples

var hold = await zonesApi.GetZoneHoldAsync(zoneId);
if (hold.Hold)
{
    Console.WriteLine($"Zone is held since {hold.HoldAfter}");
}

Remarks

A zone hold prevents creation and activation of zones with the same hostname. Use CreateZoneHoldAsync(string, bool, CancellationToken) to create a hold and RemoveZoneHoldAsync(string, CancellationToken) to remove it.

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

GetZoneSettingAsync(string, ZoneSettingId, CancellationToken)

Gets a single zone setting by its identifier.

public Task<ZoneSetting> GetZoneSettingAsync(string zoneId, ZoneSettingId settingId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

settingId ZoneSettingId

The setting identifier. Use ZoneSettingId static properties for known settings.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ZoneSetting>

The zone setting with its current value.

Examples

// Using the extensible enum (recommended)
var setting = await zones.GetZoneSettingAsync(zoneId, ZoneSettingId.MinTlsVersion);
string version = setting.Value.GetString(); // "1.2"

var cacheTtl = await zones.GetZoneSettingAsync(zoneId, ZoneSettingId.BrowserCacheTtl);
int ttlSeconds = cacheTtl.Value.GetInt32(); // 14400

// String values are implicitly converted to ZoneSettingId
var custom = await zones.GetZoneSettingAsync(zoneId, "custom_setting");

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

ImportDnsRecordsAsync(string, Stream, bool, bool, CancellationToken)

Imports a BIND file to bulk create/overwrite DNS records.

public Task<DnsImportResult> ImportDnsRecordsAsync(string zoneId, Stream bindStream, bool proxied, bool overwriteExisting, CancellationToken cancellationToken = default)

Parameters

zoneId string

The ID of the zone.

bindStream Stream

A stream containing the BIND configuration file.

proxied bool

Whether to proxy the imported records.

overwriteExisting bool

Whether to overwrite existing records.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DnsImportResult>

A result object with a summary of the import operation.

ListAllDnsRecordsAsync(string, ListDnsRecordsFilters?, CancellationToken)

Lists all DNS records for a zone, automatically handling pagination.

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

Parameters

zoneId string

The ID of the zone.

filters ListDnsRecordsFilters

Optional filters for sorting and matching. Pagination options will be ignored.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<DnsRecord>

An asynchronous stream of all matching DNS records.

ListAllZonesAsync(ListZonesFilters?, CancellationToken)

Lists all zones, automatically handling pagination.

public IAsyncEnumerable<Zone> ListAllZonesAsync(ListZonesFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListZonesFilters

Optional filters for sorting and matching. Pagination options will be ignored.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<Zone>

An asynchronous stream of all matching zones.

Examples

await foreach (var zone in zonesApi.ListAllZonesAsync())
{
    Console.WriteLine($"{zone.Name}: {zone.Status}");
}

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.

See Also

ListDnsRecordsAsync(string, ListDnsRecordsFilters?, CancellationToken)

Lists DNS records for a zone, with filtering and manual pagination.

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

Parameters

zoneId string

The ID of the zone.

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.

ListZonesAsync(ListZonesFilters?, CancellationToken)

Lists zones with filtering and pagination.

public Task<PagePaginatedResult<Zone>> ListZonesAsync(ListZonesFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListZonesFilters

Optional filters for pagination, sorting, and matching.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<PagePaginatedResult<Zone>>

A single page of zones along with pagination information.

Examples

// List active zones
var result = await zonesApi.ListZonesAsync(new ListZonesFilters(Status: ZoneStatus.Active));
foreach (var zone in result.Items)
{
    Console.WriteLine($"{zone.Name}: {zone.Status}");
}
See Also

PurgeCacheAsync(string, PurgeCacheRequest, CancellationToken)

Purges assets from the Cloudflare cache for a zone.

public Task<PurgeCacheResult> PurgeCacheAsync(string zoneId, PurgeCacheRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The ID of the zone.

request PurgeCacheRequest

The request defining what to purge (e.g., files, prefixes, or everything).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<PurgeCacheResult>

The result of the purge operation.

RemoveZoneHoldAsync(string, CancellationToken)

Removes a zone hold, allowing creation of zones with this hostname.

public Task<ZoneHold> RemoveZoneHoldAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ZoneHold>

The removed zone hold (with Hold=false).

Examples

var result = await zonesApi.RemoveZoneHoldAsync(zoneId);
// result.Hold will be false

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

SetVanityNameServersAsync(string, IReadOnlyList<string>, CancellationToken)

Sets the zone's vanity nameservers.

public Task<Zone> SetVanityNameServersAsync(string zoneId, IReadOnlyList<string> nameservers, CancellationToken cancellationToken = default)

Parameters

zoneId string

The identifier of the zone.

nameservers IReadOnlyList<string>

The list of vanity nameservers to set.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Zone>

The updated zone.

Remarks

Vanity nameservers require a Business or Enterprise plan. These are custom-branded nameservers (e.g., ns1.yourdomain.com instead of ns1.cloudflare.com).

Exceptions

ArgumentNullException

Thrown when zoneId or nameservers is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

SetZonePausedAsync(string, bool, CancellationToken)

Sets the zone's paused state.

public Task<Zone> SetZonePausedAsync(string zoneId, bool paused, CancellationToken cancellationToken = default)

Parameters

zoneId string

The identifier of the zone.

paused bool

Whether to pause the zone.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Zone>

The updated zone.

Examples

// Pause traffic proxying
var zone = await zonesApi.SetZonePausedAsync(zoneId, true);

// Resume traffic proxying
zone = await zonesApi.SetZonePausedAsync(zoneId, false);

Remarks

When a zone is paused, Cloudflare stops proxying traffic and the zone essentially becomes DNS-only.

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

SetZoneSettingAsync<T>(string, ZoneSettingId, T, CancellationToken)

Updates a zone setting.

public Task<ZoneSetting> SetZoneSettingAsync<T>(string zoneId, ZoneSettingId settingId, T value, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

settingId ZoneSettingId

The setting identifier. Use ZoneSettingId static properties for known settings.

value T

The new value for the setting.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ZoneSetting>

The updated zone setting.

Type Parameters

T

The value type (string, int, or complex object).

Examples

// Using the extensible enum (recommended)
await zones.SetZoneSettingAsync(zoneId, ZoneSettingId.MinTlsVersion, "1.2");

// Enable development mode
await zones.SetZoneSettingAsync(zoneId, ZoneSettingId.DevelopmentMode, "on");

// Set browser cache TTL to 4 hours
await zones.SetZoneSettingAsync(zoneId, ZoneSettingId.BrowserCacheTtl, 14400);

// String values are implicitly converted to ZoneSettingId
await zones.SetZoneSettingAsync(zoneId, "custom_setting", "value");

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

SetZoneTypeAsync(string, ZoneType, CancellationToken)

Sets the zone's type.

public Task<Zone> SetZoneTypeAsync(string zoneId, ZoneType type, CancellationToken cancellationToken = default)

Parameters

zoneId string

The identifier of the zone.

type ZoneType

The zone type to set.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Zone>

The updated zone.

Remarks

Changing zone type may require Enterprise plan for certain transitions. Not all transitions are supported (e.g., secondary to full may not be available).

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

TriggerActivationCheckAsync(string, CancellationToken)

Triggers activation check for a pending zone.

public Task<ActivationCheckResult> TriggerActivationCheckAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The identifier of the zone to check.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ActivationCheckResult>

The result containing the zone ID.

Remarks

Rate limited: every 5 minutes (paid plans), every hour (free plans). The API only returns the zone ID; use GetZoneDetailsAsync(string, CancellationToken) to fetch updated status.

Exceptions

ArgumentNullException

Thrown when zoneId is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also

UpdateZoneHoldAsync(string, UpdateZoneHoldRequest, CancellationToken)

Updates an existing zone hold's configuration.

public Task<ZoneHold> UpdateZoneHoldAsync(string zoneId, UpdateZoneHoldRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

request UpdateZoneHoldRequest

The update parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ZoneHold>

The updated zone hold.

Examples

// Schedule a hold for the future
var request = new UpdateZoneHoldRequest(HoldAfter: DateTime.UtcNow.AddDays(7));
var hold = await zonesApi.UpdateZoneHoldAsync(zoneId, request);

// Enable subdomain protection
var request2 = new UpdateZoneHoldRequest(IncludeSubdomains: true);
var hold2 = await zonesApi.UpdateZoneHoldAsync(zoneId, request2);

Remarks

Preview: This operation has limited test coverage.

Both HoldAfter and IncludeSubdomains are optional. Only the provided fields will be updated.

Exceptions

ArgumentNullException

Thrown when zoneId or request is null.

ArgumentException

Thrown when zoneId is empty or whitespace.

See Also
Edit this page