[DNS] Records batched operations (#16984)

* Create new page for DNS records batch operations

* Adjust pages order within how-to folder

* Fill in intro and add more to the outline

* Adjust pages order to ascending complexity and specificity

* Make Dash h3s more generic and fill in content placeholders

* More specific on UI capabilities and add different Free limits

* Fix typo

* Fill in Dash deletion section

* Fill in API intro and operations requirements following PM feedback

* Overall review and add execution order and fail API behavior

* Fill in Dashboard instructions for editing proxy status

* Remove use-cases section and change mixed status callout to Note

* Text review

* Reference batch option from subdomain setup instructions

* Reference batch option from the delete-all-records page

* Fix record limit

* Mention tags and comments are also supported and cross-link

* Process PM feedback

* Fix required fields for 'puts' and update example

* Update example

* More visible and detailed callout around propagation

* Update note with Eng feedback

* Replace TBDs with actual URL references

* Overall review and fix typo

* Remove specific blog link - to be added again later

* Improve manage DNS records page and link to batched option

* Overall review and improve text for clarity

src/content/docs/dns/manage-dns-records/how-to/batch-record-changes.mdx

@@ -0,0 +1,162 @@
+---
+pcx_content_type: how-to
+title: Batch record changes
+sidebar:
+  order: 7
+---
+
+import { GlossaryTooltip, Example, Render } from "~/components";
+
+Cloudflare allows you to apply several changes to your zone records in just one action. You can [use the dashboard](#use-the-dashboard) to delete DNS records or update their <GlossaryTooltip term="proxy status">proxy status</GlossaryTooltip> in bulk, or [use the API](#use-the-api) to perform further batched operations.
+
+:::caution[Propagation through the Cloudflare network]
+Although Cloudflare will execute the batched operations in a single [database transaction](https://en.wikipedia.org/wiki/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. Refer to our [blog post](https://blog.cloudflare.com/) for details.
+:::
+
+## Availability and limits
+
+Batch DNS record changes is available on all plans.
+
+The number of records that you can operate with in one action depends on your zone plan:
+
+- Free: 200
+- Pro: 3,500
+- Business: 3,500
+- Enterprise: 3,500
+
+---
+
+## Use the dashboard
+
+### Edit proxy status in bulk
+
+`A`,`AAAA`, and `CNAME` records can be [proxied](/dns/manage-dns-records/reference/proxied-dns-records/). The **Proxy status** of a DNS record affects [how Cloudflare responds to DNS queries](/fundamentals/concepts/how-cloudflare-works/) to that record.
+
+<Render file="mix-proxied-and-unproxied" product="dns" />
+
+1. Go to [**DNS** > **Records**](https://dash.cloudflare.com/?to=/:account/:zone/dns/records).
+2. Select the DNS records you want to set the proxy status for. Note that only `A`, `AAAA`, and `CNAME` records can be proxied.
+3. Select **Edit records**.
+4. Choose the proxy status you want to apply to the selected records.
+5. Select **Save** to confirm.
+
+You can only set records to either **Proxied** or **DNS only** in bulk. This means that if your selection includes both proxied and DNS-only records, some of them will have the proxy status updated while others will keep their original value:
+
+<Example>
+
+For example, if you select the following records and then edit their proxy status in bulk, choosing **Proxied** in [step 4 above](#edit-proxy-status-in-bulk), the outcome will be:
+
+| Selected records | Original proxy status | Resulting proxy status |
+| ---------------- | --------------------- | ---------------------- |
+| `www`            | DNS only              | Proxied                |
+| `blog`           | DNS only              | Proxied                |
+| `docs`           | Proxied               | Proxied                |
+
+</Example>
+
+### Delete records in bulk
+
+:::caution
+
+Deleting DNS records can cause downtime and cannot be reverted. Make sure you only select DNS records that you can safely delete.
+
+:::
+
+1. Go to [**DNS** > **Records**](https://dash.cloudflare.com/?to=/:account/:zone/dns/records).
+2. Select the DNS records you want to delete.
+3. Select **Delete records**.
+4. In the **Delete DNS records** prompt, type in `DELETE` and select **Delete** to confirm.
+
+## Use the API
+
+:::note
+
+This option requires familiarity with API usage and concepts. For further information about the Cloudflare API, refer to [Fundamentals](/fundamentals/api/get-started/).
+
+:::
+
+The [Batched DNS record changes](/api/operations/dns-records-for-a-zone-batch-dns-records) endpoint allows you to trigger the execution of `DELETES`, `PATCHES`, `PUTS`, and `POSTS` in a single request.
+
+[Tags and comments](/dns/manage-dns-records/reference/record-attributes/) are also supported with batch changes.
+
+The operations you specify within the `/batch` request body are always executed in the following order:
+
+1. Deletes
+2. Patches
+3. Puts
+4. Posts
+
+Within each of these four lists, each individual action is executed following the DNS records order you provide. If any of the individual action fails, no changes are applied and the API returns the first error it encountered.
+
+### Aspects to consider
+
+:::caution[Propagation through the Cloudflare network]
+Although Cloudflare will execute the batched operations in a single [database transaction](https://en.wikipedia.org/wiki/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. Refer to our [blog post](https://blog.cloudflare.com/) for details.
+:::
+
+For each operation that you list in the `/batch` request body, consider the required information and how unspecified fields will behave:
+
+- **`deletes`**: only the `id` is required for each record object. You can keep additional parameters such as `name` for readability, but any other fields aside from `id` will be ignored in this case.
+- **`patches`**: aside from each record `id`, you should specify the fields you want to update. All unspecified fields will remain as they are.
+- **`puts`**: you must specify each record `id`, `content`, `name`, and `type`. You should also specify any other fields you want to set to a value that is not the default. Any unspecified fields will assume their default value for each [record type](/dns/manage-dns-records/reference/dns-record-types/). This operation works as an overwrite, so all fields in a given record are always affected.
+- **`posts`**: since you are creating a new record, `id` is not required. For field definitions, refer to the [Create DNS Record](/api/operations/dns-records-for-a-zone-create-dns-record) endpoint and select the desired record type under the request body specification.
+
+### Example request
+
+In this example, the `proxied` field for the first record listed under `"puts"` will assume the default value (`false`).
+
+```bash
+{
+    "deletes": [
+        {
+            "id": "2bff0ebc4df64beaa44b0dca93e37a28"
+        },
+        {
+            "id": "31d1d6e79ce04b8d93cbc5a13401d728"
+        }
+    ],
+    "patches": [
+        {
+            "id": "62276440f783445380480484648c1017",
+            "content": "192.0.2.46"
+        },
+        {
+            "id": "c942d948dc2343b9b97aed78479c9fb9",
+            "name": "update.example.com",
+            "proxied": true
+        }
+    ],
+    "puts": [
+        {
+            "id": "a50364543094428abde0f14061d42b0e",
+            "content": "192.0.2.50",
+            "name": "change.example.com",
+						"type": "A",
+            "ttl:": 1
+        },
+        {
+            "id": "3bce0920f19d43949498bd067b05dfa9",
+            "content": "192.0.2.45",
+            "name": "no-change.example.com",
+						"type": "A",
+            "proxied": false,
+            "ttl:": 3000
+        }
+    ],
+    "posts": [
+        {
+            "name": "@",
+            "type": "A",
+            "content": "192.0.2.41",
+            "proxied": false,
+            "ttl": 3000
+        },
+        {
+            "name": "a.example.com",
+            "type": "A",
+            "content": "192.0.2.42",
+            "proxied": true
+        }
+    ]
+}
+```

src/content/docs/dns/manage-dns-records/how-to/create-dns-records.mdx

@@ -5,11 +5,13 @@ sidebar:
   order: 1
 ---
 
-import { GlossaryTooltip, Render, TabItem, Tabs } from "~/components";
+import { GlossaryTooltip, Render, TabItem, Tabs, Details } from "~/components";
 
-<Render file="dns-scan-intro" /> <br />
+<Render file="dns-scan-intro" />
 
+<Details header="When the quick scan is not automatically invoked">
 <Render file="dns-scan-note" />
+</ Details>
 
 <Render file="dns-scan-procedure" />
 
@@ -29,13 +31,13 @@ To create a DNS record in the dashboard:
 
 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select an account and domain.
 2. Go to **DNS** > **Records**.
-3. Click **Add record**.
+3. Select **Add record**.
 4. Choose a record [**Type**](/dns/manage-dns-records/reference/dns-record-types/).
 5. Complete the required fields, which vary per record. Particularly important fields (for some records) include:
    - **Proxy status**: For `A`, `AAAA`, and `CNAME` records, decide whether hostname traffic is <GlossaryTooltip term="proxy status" link="/dns/manage-dns-records/reference/proxied-dns-records/">proxied through Cloudflare</GlossaryTooltip>.
    - **TTL**: Short for [_Time to Live_](/dns/manage-dns-records/reference/ttl/), this field controls how long each record is valid and — as a result — how long it takes for record updates to reach your end users.
    - **Comment** and **Tag**: [Record attributes](/dns/manage-dns-records/reference/record-attributes/) meant for your reference.
-6. Click **Save**.
+6. Select **Save**.
 
 </TabItem>
 
@@ -57,9 +59,9 @@ To edit DNS records in the dashboard:
 
 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select an account and domain.
 2. Go to **DNS** > **Records**.
-3. On a specific record, click **Edit**.
+3. On a specific record, select **Edit**.
 4. Make any necessary changes.
-5. Click **Save**.
+5. Select **Save**.
 
 </TabItem>
 
@@ -79,9 +81,9 @@ To delete DNS records in the dashboard:
 
 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select an account and domain.
 2. Go to **DNS** > **Records**.
-3. On a specific record, click **Edit**.
-4. Click **Delete**.
-5. Click **Delete** again to confirm.
+3. On a specific record, select **Edit**.
+4. Select **Delete**.
+5. Select **Delete** again to confirm.
 
 </TabItem>
 
@@ -90,3 +92,9 @@ To delete DNS records in the dashboard:
 To delete records with the API, use a [DELETE request](/api/operations/dns-records-for-a-zone-delete-dns-record).
 
 </TabItem> </Tabs>
+
+---
+
+## Batch record changes
+
+For guidance on how to apply several changes to your zone records in just one action, refer to [Batch record changes](/dns/manage-dns-records/how-to/batch-record-changes/).

src/content/docs/dns/manage-dns-records/how-to/create-subdomain.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: reference
 title: Create subdomain records
 sidebar:
-  order: 4
+  order: 3
 
 ---
 

src/content/docs/dns/manage-dns-records/how-to/create-zone-apex.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: reference
 title: Create zone apex record
 sidebar:
-  order: 3
+  order: 2
 
 ---
 

src/content/docs/dns/manage-dns-records/how-to/email-records.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: how-to
 title: Set up email records
 sidebar:
-  order: 5
+  order: 4
 
 ---
 

src/content/docs/dns/manage-dns-records/how-to/import-and-export.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: how-to
 title: Import and export records
 sidebar:
-  order: 2
+  order: 6
 ---
 
 import { Render, TabItem, Tabs } from "~/components";

src/content/docs/dns/manage-dns-records/how-to/managing-dynamic-ip-addresses.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: reference
 title: Dynamically update DNS records
 sidebar:
-  order: 6
+  order: 9
 
 ---
 

src/content/docs/dns/manage-dns-records/how-to/round-robin-dns.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: reference
 title: Round-robin DNS
 sidebar:
-  order: 7
+  order: 10
 
 ---
 

src/content/docs/dns/manage-dns-records/reference/record-attributes.mdx

@@ -49,7 +49,7 @@ Comments and tags are only supported for [full](/dns/zone-setups/full-setup/) an
 
 Create or edit record attributes just like any other aspect of DNS records, whether through the [dashboard](/dns/manage-dns-records/how-to/create-dns-records/) or [API](/api/operations/dns-records-for-a-zone-create-dns-record).
 
-You can also add or edit attributes by [exporting and re-importing](/dns/manage-dns-records/how-to/import-and-export/#dns-record-attributes) your records.
+You can also add or edit attributes by [exporting and re-importing](/dns/manage-dns-records/how-to/import-and-export/#dns-record-attributes) your records, or using the [Batch record changes API](/dns/manage-dns-records/how-to/batch-record-changes/#use-the-api).
 
 ***
 

src/content/docs/dns/zone-setups/full-setup/setup.mdx

@@ -52,7 +52,9 @@ When you start using Cloudflare's nameservers for authoritative DNS and your zon
 
 <Render file="dns-scan-intro" /> <br />
 
+:::note
 <Render file="dns-scan-note" />
+:::
 
 <Render file="dns-scan-procedure" />
 
@@ -78,7 +80,7 @@ When you start using Cloudflare's nameservers for authoritative DNS and your zon
 
 :::note
 
-Cloudflare automatically assigns nameservers to a domain and these assignments cannot be changed. For more details, refer to [Nameserver assignments](/dns/zone-setups/reference/nameserver-assignment/). 
+Cloudflare automatically assigns nameservers to a domain and these assignments cannot be changed. For more details, refer to [Nameserver assignments](/dns/zone-setups/reference/nameserver-assignment/).
 :::
 
 ### Update your registrar
@@ -87,7 +89,7 @@ Cloudflare automatically assigns nameservers to a domain and these assignments c
 
 :::note
 
-Depending on your use case, you may have to perform this step on the DNS records management of your domain parent zone, or at a domain reseller, instead. Refer to [Nameservers](/dns/nameservers/update-nameservers/#specific-processes) for details. 
+Depending on your use case, you may have to perform this step on the DNS records management of your domain parent zone, or at a domain reseller, instead. Refer to [Nameservers](/dns/nameservers/update-nameservers/#specific-processes) for details.
 :::
 
 2. Remove your existing authoritative nameservers.

src/content/docs/dns/zone-setups/subdomain-setup/setup/parent-on-full.mdx

@@ -55,15 +55,19 @@ If you have already created DNS records covering your subdomain in the parent zo
 3. In your child zone, make sure you have all DNS records that relate to the subdomain. This includes all DNS records deeper than the delegated subdomain. For example, if you are delegating `www.example.com`, you should also move over records for `api.www.example.com`.
 
    :::note
-   If your child zone is on a full setup, consider [exporting](/dns/manage-dns-records/how-to/import-and-export/#export-records) records from the parent zone, deleting all unnecessary records, and then [importing](/dns/manage-dns-records/how-to/import-and-export/#import-records) the records into your new zone. 
+   If your child zone is on a full setup, consider [exporting](/dns/manage-dns-records/how-to/import-and-export/#export-records) records from the parent zone, deleting all unnecessary records, and then [importing](/dns/manage-dns-records/how-to/import-and-export/#import-records) the records into your new zone.
    :::
 
-4. If the parent zone is in Cloudflare, make sure that you migrate over any settings ([WAF custom rules](/waf/custom-rules/), [Rules](/rules/), [Workers](/workers/), and more) that might be needed for the child zone.
+4. If the parent zone is on Cloudflare, make sure that you migrate over any settings ([WAF custom rules](/waf/custom-rules/), [Rules](/rules/), [Workers](/workers/), and more) that might be needed for the child zone.
 
 5. In the child zone, [order an advanced SSL certificate](/ssl/edge-certificates/advanced-certificate-manager/) that covers the child subdomain and any deeper subdomains (if present).
 
 6. Get the nameserver names for the subdomain. These can be found within your newly created child zone in [DNS > Records](https://dash.cloudflare.com/?to=/:account/:zone/dns/records), and will **not** be the same nameservers as the ones used in the parent zone.
 
+   :::note
+   If the parent zone is on Cloudflare, steps 7 and 9 below can be achieved via API. Use the [`/batch` endpoint](/api/operations/dns-records-for-a-zone-batch-dns-records) to delete and create or update DNS records within a single request. Refer to [Batch record changes](/dns/manage-dns-records/how-to/batch-record-changes/) for further guidance.
+   :::
+
 7. Within the **DNS** > **Records** of the parent zone, update existing address records (`A/AAAA`) on your subdomain to `NS` records. If you only have one address record, update the existing one and add a new `NS` record. If you have multiple address records, update any two of them.
 
    For example, to delegate the subdomain `www.example.com`, the updated records in the parent zone `example.com` should contain `NS` records similar to the following:

src/content/docs/dns/zone-setups/troubleshooting/delete-all-records.mdx

@@ -7,17 +7,23 @@ description: Learn how to bulk delete DNS records in Cloudflare with a script so
 
 ---
 
+import { Example } from "~/components";
+
 When you connect your domain to Cloudflare, the [DNS records quick scan](/dns/zone-setups/reference/dns-quick-scan/) may automatically add several records to your zone.
 
 If you realize most of them are not applicable and want to bulk delete DNS records, follow the steps below. This method assumes you are familiar with [API calls fundamentals](/fundamentals/api/).
 
+:::note[Bulk deletion available in the dashboard]
+You can delete records in bulk via the dashboard, which removes the need for custom scripts as the one below. Refer to [Batch record changes](/dns/manage-dns-records/how-to/batch-record-changes/#delete-records-in-bulk) for details.
+:::
+
 1. Make sure you have [an API token](/fundamentals/api/get-started/create-token/) that allows you to edit DNS for your zone.
 2. Get your [zone ID](/fundamentals/setup/find-account-and-zone-ids/).
 3. Run the following script, replacing `<ZONE_ID>` and `<API_TOKEN>` with the values you got from the previous steps.
 
-:::caution
-
-This script uses [jq](https://jqlang.github.io/jq/) to format `JSON` outputs for readability. Refer to [Make API calls](/fundamentals/api/how-to/make-api-calls/) for details. 
+<Example>
+:::caution[Warning]
+This script uses [jq](https://jqlang.github.io/jq/) to format `JSON` outputs for readability. Refer to [Make API calls](/fundamentals/api/how-to/make-api-calls/) for details.
 :::
 
 ```bash
@@ -31,3 +37,4 @@ do
 --header "Authorization: Bearer $bearer"
 done
 ```
+</Example>

src/content/partials/dns/dns-scan-note.mdx

@@ -3,16 +3,11 @@
 
 ---
 
-:::note
-
 The [DNS records quick scan](/dns/zone-setups/reference/dns-quick-scan/) is not automatically invoked in the following cases:
 
 * If you choose Enterprise plan and, instead of the **Quick Scan**, choose to upload a DNS zone file or add records manually.
 * If you add a zone via the [API](/api/operations/zones-post).
 
 You can manually invoke the quick scan via API with the [Scan DNS Records endpoint](/api/operations/dns-records-for-a-zone-scan-dns-records).
 
-Note that the quick scan is a best effort attempt based on a predefined list of commonly used record names and types. You can read more about this in the [reference page](/dns/zone-setups/reference/dns-quick-scan/).
-
-
-:::
+Note that the quick scan is a best effort attempt based on a predefined list of commonly used record names and types. You can read more about this in the [reference page](/dns/zone-setups/reference/dns-quick-scan/).