Skip to content
Cloudflare API
Start here
API Reference
DNS
Records

Create DNS Record

POST/zones/{zone_id}/dns_records

Create a new DNS record for a zone.

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.
Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
Accepted Permissions (at least one required)
DNS Write
Path ParametersExpand Collapse
zone_id: string

Identifier.

maxLength32
Query ParametersExpand Collapse
include_shadow_metadata: optional boolean

Whether to include shadow metadata in the meta field of each record in the response. See Shadowed records.

Body ParametersJSONExpand Collapse
body: ARecord { name, ttl, type, 6 more } or AAAARecord { name, ttl, type, 6 more } or CNAMERecord { name, ttl, type, 5 more } or 18 more
One of the following:
ARecord object { name, ttl, type, 6 more }
name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255
minLength1
ttl: TTL

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.

One of the following:
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.

type: "A"

Record type.

comment: optional string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: optional string

A valid IPv4 address.

formatipv4
private_routing: optional boolean

Enables private network routing to the origin.

proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: optional object { ipv4_only, ipv6_only }

Settings for the DNS record.

ipv4_only: optional boolean

When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

ipv6_only: optional boolean

When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

tags: optional array of RecordTags

Custom tags for the DNS record. This field has no effect on DNS responses.

AAAARecord object { name, ttl, type, 6 more }
name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255
minLength1
ttl: TTL

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.

One of the following:
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.

type: "AAAA"

Record type.

comment: optional string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: optional string

A valid IPv6 address.

formatipv6
private_routing: optional boolean

Enables private network routing to the origin.

proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: optional object { ipv4_only, ipv6_only }

Settings for the DNS record.

ipv4_only: optional boolean

When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

ipv6_only: optional boolean

When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

tags: optional array of RecordTags

Custom tags for the DNS record. This field has no effect on DNS responses.

CNAMERecord object { name, ttl, type, 5 more }
name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255
minLength1
ttl: TTL

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.

One of the following:
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.

type: "CNAME"

Record type.

comment: optional string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: optional string

A valid hostname. Must not match the record’s name.

proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: optional object { flatten_cname, ipv4_only, ipv6_only }

Settings for the DNS record.

flatten_cname: optional boolean

If enabled, causes the CNAME record to be resolved externally and the resulting address records (e.g., A and AAAA) to be returned instead of the CNAME record itself. This setting is unavailable for proxied records, since they are always flattened.

ipv4_only: optional boolean

When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

ipv6_only: optional boolean

When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

tags: optional array of RecordTags

Custom tags for the DNS record. This field has no effect on DNS responses.

MXRecord object { name, ttl, type, 6 more }
name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255
minLength1
ttl: TTL

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.

One of the following:
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.

type: "MX"

Record type.

comment: optional string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: optional string

A valid mail server hostname.

formathostname
priority: optional number

Required for MX and URI records; ignored for other record types (but may still be returned by the API). Records with lower priorities are preferred. This field is to be deprecated in favor of the priority field within the data map.

maximum65535
minimum0
proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: optional object { ipv4_only, ipv6_only }

Settings for the DNS record.

ipv4_only: optional boolean

When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

ipv6_only: optional boolean

When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

tags: optional array of RecordTags

Custom tags for the DNS record. This field has no effect on DNS responses.

NSRecord object { name, ttl, type, 5 more }
name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255
minLength1
ttl: TTL

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.

One of the following:
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.

type: "NS"

Record type.

comment: optional string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: optional string

A valid name server host name.

proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: optional object { ipv4_only, ipv6_only }

Settings for the DNS record.

ipv4_only: optional boolean

When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

ipv6_only: optional boolean

When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

tags: optional array of RecordTags

Custom tags for the DNS record. This field has no effect on DNS responses.

DNSRecordsOpenpgpkeyRecord object { name, ttl, type, 5 more }
name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255
minLength1
ttl: TTL

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.

One of the following:
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.

type: "OPENPGPKEY"

Record type.

comment: optional string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: optional string

A single Base64-encoded OpenPGP Transferable Public Key (RFC 4880 Section 11.1)

proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: optional object { ipv4_only, ipv6_only }

Settings for the DNS record.

ipv4_only: optional boolean

When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

ipv6_only: optional boolean

When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

tags: optional array of RecordTags

Custom tags for the DNS record. This field has no effect on DNS responses.

PTRRecord object { name, ttl, type, 5 more }
name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255
minLength1
ttl: TTL

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.

One of the following:
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.

type: "PTR"

Record type.

comment: optional string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: optional string

Domain name pointing to the address.

proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: optional object { ipv4_only, ipv6_only }

Settings for the DNS record.

ipv4_only: optional boolean

When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

ipv6_only: optional boolean

When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

tags: optional array of RecordTags

Custom tags for the DNS record. This field has no effect on DNS responses.

TXTRecord object { name, ttl, type, 5 more }
name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255
minLength1
ttl: TTL

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.

One of the following:
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.

type: "TXT"

Record type.

comment: optional string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: optional string

Text content for the record. The content must consist of quoted “character strings” (RFC 1035), each with a length of up to 255 bytes. Strings exceeding this allowed maximum length are automatically split.

Learn more at https://www.cloudflare.com/learning/dns/dns-records/dns-txt-record/.

proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: optional object { ipv4_only, ipv6_only }

Settings for the DNS record.

ipv4_only: optional boolean

When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

ipv6_only: optional boolean

When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

tags: optional array of RecordTags

Custom tags for the DNS record. This field has no effect on DNS responses.

CAARecord object { name, ttl, type, 6 more }
name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255
minLength1
ttl: TTL

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.

One of the following:
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.

type: "CAA"

Record type.

comment: optional string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: optional string

Formatted CAA content. See ‘data’ to set CAA properties.

data: optional object { flags, tag, value }

Components of a CAA record.

flags: optional number

Flags for the CAA record.

maximum255
minimum0
tag: optional string

Name of the property controlled by this record (e.g.: issue, issuewild, iodef).

value: optional string

Value of the record. This field’s semantics depend on the chosen tag.

proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: optional object {