Cloudflare API | DNS › Records › Create DNS Record

Optional

Request example

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{
          "name": "example.com",
          "ttl": 3600,
          "type": "A",
          "comment": "Domain verification record",
          "content": "198.51.100.4",
          "proxied": true
        }'

200Example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "name": "example.com",
    "ttl": 3600,
    "type": "A",
    "comment": "Domain verification record",
    "content": "198.51.100.4",
    "proxied": true,
    "settings": {
      "ipv4_only": true,
      "ipv6_only": true
    },
    "tags": [
      "owner:dns-team"
    ],
    "id": "023e105f4ecef8ad9ca31a8372d0c353",
    "created_on": "2014-01-01T05:20:00.12345Z",
    "meta": {},
    "modified_on": "2014-01-01T05:20:00.12345Z",
    "proxiable": true,
    "comment_modified_on": "2024-01-01T05:20:00.12345Z",
    "tags_modified_on": "2025-01-01T05:20:00.12345Z"
  }
}

Overwrite DNS Record -> Envelope<

put/zones/{zone_id}/dns_records/{dns_record_id}

Overwrite an existing DNS record.

Notes:

A/AAAA records cannot exist on the same name as CNAME records.
NS records cannot exist on the same name as any other record type.
Domain names are always represented in Punycode, even if Unicode characters were used when creating the record.

Update DNS Record -> Envelope<

patch/zones/{zone_id}/dns_records/{dns_record_id}

Update an existing DNS record.

Notes:

A/AAAA records cannot exist on the same name as CNAME records.
NS records cannot exist on the same name as any other record type.
Domain names are always represented in Punycode, even if Unicode characters were used when creating the record.

Delete DNS Record -> Envelope<{ id }>

delete/zones/{zone_id}/dns_records/{dns_record_id}

Delete DNS Record

Export DNS Records -> string

get/zones/{zone_id}/dns_records/export

You can export your BIND config through this endpoint.

See the documentation for more information.

Import DNS Records -> Envelope<{ recs_added, total_records_parsed }>

post/zones/{zone_id}/dns_records/import

You can upload your BIND config through this endpoint. It assumes that cURL is called from a location with bind_config.txt (valid BIND config) present.

See the documentation for more information.

Scan DNS Records -> Envelope<{ recs_added, total_records_parsed }>

Deprecated

post/zones/{zone_id}/dns_records/scan

Deprecated

This endpoint is deprecated in favor of a new asynchronous version. Please use the /scan/trigger and /scan/review endpoints instead.

Scan for common DNS records on your domain and automatically add them to your zone. Useful if you haven't updated your nameservers yet.

Trigger DNS Record Scan -> { errors, messages, success }

post/zones/{zone_id}/dns_records/scan/trigger

Initiates an asynchronous scan for common DNS records on your domain. Note that this does not automatically add records to your zone. The scan runs in the background, and results can be reviewed later using the /scan/review endpoints. Useful if you haven't updated your nameservers yet.

Review Scanned DNS Records -> Envelope<{ accepts, rejects }>

post/zones/{zone_id}/dns_records/scan/review

Accept or reject DNS records found by the DNS records scan. Accepted records will be permanently added to the zone, while rejected records will be permanently deleted.

List Scanned DNS Records -> SinglePage<

get/zones/{zone_id}/dns_records/scan/review

Retrieves the list of DNS records discovered up to this point by the asynchronous scan. These records are temporary until explicitly accepted or rejected via POST /scan/review. Additional records may be discovered by the scan later.

Batch DNS Records -> Envelope<{ deletes, patches, posts, 1 more... }>

post/zones/{zone_id}/dns_records/batch

Send a Batch of DNS Record API calls to be executed together.

Notes:

Although Cloudflare will execute the batched operations in a single database transaction, Cloudflare's distributed KV store must treat each record change as a single key-value pair. This means that the propagation of changes is not atomic. See the documentation for more information.
The operations you specify within the /batch request body are always executed in the following order:
- Deletes
- Patches
- Puts
- Posts

Domain types

ARecord = { name, ttl, type, 5 more... }

AAAARecord = { name, ttl, type, 5 more... }

BatchPatch =

| 18 more...

BatchPut =

| 18 more...

CAARecord = { name, ttl, type, 6 more... }

CERTRecord = { name, ttl, type, 6 more... }

CNAMERecord = { name, ttl, type, 5 more... }

DNSKEYRecord = { name, ttl, type, 6 more... }

DSRecord = { name, ttl, type, 6 more... }

HTTPSRecord = { name, ttl, type, 6 more... }

LOCRecord = { name, ttl, type, 6 more... }

MXRecord = { name, ttl, type, 6 more... }

NAPTRRecord = { name, ttl, type, 6 more... }

NSRecord = { name, ttl, type, 5 more... }

PTRRecord = { name, ttl, type, 5 more... }

Record =

| 18 more...

RecordResponse =

| 18 more...

RecordTags = string

Individual tag of the form name:value (the name must consist of only letters, numbers, underscores and hyphens)

SMIMEARecord = { name, ttl, type, 6 more... }

SRVRecord = { name, ttl, type, 6 more... }

SSHFPRecord = { name, ttl, type, 6 more... }

SVCBRecord = { name, ttl, type, 6 more... }

TLSARecord = { name, ttl, type, 6 more... }

TTL = number | 1

Time To Live (TTL) of the DNS record in seconds. Setting to 1 means 'automatic'. Value must be between 60 and 86400, with the minimum reduced to 30 for Enterprise zones.

TXTRecord = { name, ttl, type, 5 more... }

URIRecord = { name, ttl, type, 7 more... }

DNS

Settings

dns.settings

DNS Settings

Account

dns.settings.account

Methods

Show DNS Settings -> Envelope<{ zone_defaults }>

get/accounts/{account_id}/dns_settings

Show DNS settings for an account

Update DNS Settings -> Envelope<{ zone_defaults }>

patch/accounts/{account_id}/dns_settings

Update DNS settings for an account

DNS Settings Account

Views

dns.settings.account.views

Methods

List Internal DNS Views -> V4PagePaginationArray<{ id, created_time, modified_time, 2 more... }>

get/accounts/{account_id}/dns_settings/views

List DNS Internal Views for an Account

DNS Internal View Details -> Envelope<{ id, created_time, modified_time, 2 more... }>

get/accounts/{account_id}/dns_settings/views/{view_id}

Get DNS Internal View

Create Internal DNS View -> Envelope<{ id, created_time, modified_time, 2 more... }>

post/accounts/{account_id}/dns_settings/views

Create Internal DNS View for an account

Update Internal DNS View -> Envelope<{ id, created_time, modified_time, 2 more... }>

patch/accounts/{account_id}/dns_settings/views/{view_id}

Update an existing Internal DNS View

Delete Internal DNS View -> Envelope<{ id }>

delete/accounts/{account_id}/dns_settings/views/{view_id}

Delete an existing Internal DNS View

DNS Settings

Zone

dns.settings.zone

Methods

Show DNS Settings -> Envelope<{ flatten_all_cnames, foundation_dns, internal_dns, 6 more... }>

get/zones/{zone_id}/dns_settings

Show DNS settings for a zone

Update DNS Settings -> Envelope<{ flatten_all_cnames, foundation_dns, internal_dns, 6 more... }>

patch/zones/{zone_id}/dns_settings

Update DNS settings for a zone

DNS

Zone Transfers

dns.zone_transfers

ACLs

dns.zone_transfers.acls

Methods

List ACLs -> SinglePage<

get/accounts/{account_id}/secondary_dns/acls

List ACLs.

ACL Details -> Envelope<

get/accounts/{account_id}/secondary_dns/acls/{acl_id}

Get ACL.

Create ACL -> Envelope<

post/accounts/{account_id}/secondary_dns/acls

Create ACL.

Update ACL -> Envelope<

put/accounts/{account_id}/secondary_dns/acls/{acl_id}

Modify ACL.

Delete ACL -> Envelope<{ id }>

delete/accounts/{account_id}/secondary_dns/acls/{acl_id}

Delete ACL.

Domain types

ACL = { id, ip_range, name }

Force AXFR

dns.zone_transfers.force_axfr

Methods

Force AXFR -> Envelope<

ForceAXFR

post/zones/{zone_id}/secondary_dns/force_axfr

Sends AXFR zone transfer request to primary nameserver(s).

Domain types

ForceAXFR = string

When force_axfr query parameter is set to true, the response is a simple string.

Incoming

dns.zone_transfers.incoming

Methods

Secondary Zone Configuration Details -> Envelope<{ id, auto_refresh_seconds, checked_time, 5 more... }>

get/zones/{zone_id}/secondary_dns/incoming

Get secondary zone configuration for incoming zone transfers.

Create Secondary Zone Configuration -> Envelope<{ id, auto_refresh_seconds, checked_time, 5 more... }>

post/zones/{zone_id}/secondary_dns/incoming

Create secondary zone configuration for incoming zone transfers.

Update Secondary Zone Configuration -> Envelope<{ id, auto_refresh_seconds, checked_time, 5 more... }>

put/zones/{zone_id}/secondary_dns/incoming

Update secondary zone configuration for incoming zone transfers.

Delete Secondary Zone Configuration -> Envelope<{ id }>

delete/zones/{zone_id}/secondary_dns/incoming

Delete secondary zone configuration for incoming zone transfers.

Domain types

Incoming = { id, auto_refresh_seconds, checked_time, 5 more... }

DNS Zone Transfers Outgoing

Outgoing

dns.zone_transfers.outgoing

Methods

Primary Zone Configuration Details -> Envelope<{ id, checked_time, created_time, 4 more... }>

get/zones/{zone_id}/secondary_dns/outgoing

Get primary zone configuration for outgoing zone transfers.

Create Primary Zone Configuration -> Envelope<{ id, checked_time, created_time, 4 more... }>

post/zones/{zone_id}/secondary_dns/outgoing

Create primary zone configuration for outgoing zone transfers.

Update Primary Zone Configuration -> Envelope<{ id, checked_time, created_time, 4 more... }>

put/zones/{zone_id}/secondary_dns/outgoing

Update primary zone configuration for outgoing zone transfers.

Delete Primary Zone Configuration -> Envelope<{ id }>

delete/zones/{zone_id}/secondary_dns/outgoing

Delete primary zone configuration for outgoing zone transfers.

Disable Outgoing Zone Transfers -> Envelope<

DisableTransfer

post/zones/{zone_id}/secondary_dns/outgoing/disable

Disable outgoing zone transfers for primary zone and clears IXFR backlog of primary zone.

Enable Outgoing Zone Transfers -> Envelope<

EnableTransfer

post/zones/{zone_id}/secondary_dns/outgoing/enable

Enable outgoing zone transfers for primary zone.

Force DNS Notify -> Envelope<string>

post/zones/{zone_id}/secondary_dns/outgoing/force_notify

Notifies the secondary nameserver(s) and clears IXFR backlog of primary zone.

Domain types

DisableTransfer = string

The zone transfer status of a primary zone.

EnableTransfer = string

The zone transfer status of a primary zone.

Outgoing = { id, checked_time, created_time, 4 more... }

OutgoingStatus = string

The zone transfer status of a primary zone.

Status

dns.zone_transfers.outgoing.status

Methods

Get Outgoing Zone Transfer Status -> Envelope<

EnableTransfer

get/zones/{zone_id}/secondary_dns/outgoing/status

Get primary zone transfer status.

Peers

dns.zone_transfers.peers

Methods

List Peers -> SinglePage<

get/accounts/{account_id}/secondary_dns/peers

List Peers.

Peer Details -> Envelope<

get/accounts/{account_id}/secondary_dns/peers/{peer_id}

Get Peer.

Create Peer -> Envelope<

post/accounts/{account_id}/secondary_dns/peers

Create Peer.

Update Peer -> Envelope<

put/accounts/{account_id}/secondary_dns/peers/{peer_id}

Modify Peer.

Delete Peer -> Envelope<{ id }>

delete/accounts/{account_id}/secondary_dns/peers/{peer_id}

Delete Peer.

Domain types

Peer = { id, name, ip, 3 more... }

TSIGs

dns.zone_transfers.tsigs

Methods

List TSIGs -> SinglePage<

get/accounts/{account_id}/secondary_dns/tsigs

List TSIGs.

TSIG Details -> Envelope<

get/accounts/{account_id}/secondary_dns/tsigs/{tsig_id}

Get TSIG.

Create TSIG -> Envelope<

post/accounts/{account_id}/secondary_dns/tsigs

Create TSIG.

Update TSIG -> Envelope<