dns/update
Replace an existing DNS record. All required fields must be provided — this is a full replacement (PUT), not a partial update (PATCH).
Full replacement: dns/update sends a PUT request. You must supply all required fields (Type, Name, Content) even if you are only changing one value. Use dns/get first to retrieve the current record values and carry forward any fields you are not changing.
When to Use
- Server migration: Update an A record to a new IP address after completing a server migration, enabling traffic to cut over to the new host.
- Load balancer change: Update a CNAME record to point to a new load balancer hostname after infrastructure reconfiguration.
- DKIM key rotation: Replace a TXT record's DKIM public key value as part of a scheduled cryptographic key rotation procedure.
- TTL adjustment: Reduce the TTL of an A record from 3600 to 60 seconds before a planned migration to speed up propagation.
- MX priority failover: Change the MX record priority to promote a backup mail server during a primary mail server outage.
Configuration
Connection
| Field | Type | Required | Description |
|---|---|---|---|
ApiToken | string | required | Scoped Cloudflare API Token with DNS.Edit permission. Store in BizFirst Credentials Manager. |
Operation Fields
| Field | Type | Required | Description |
|---|---|---|---|
ZoneId | string | required | 32-character hexadecimal Zone ID. |
RecordId | string | required | UUID of the record to update. Obtain from dns/list or dns/create output. |
Type | string | required | Record type — must be provided even if unchanged. |
Name | string | required | Fully-qualified record name — must be provided even if unchanged. |
Content | string | required | New record value — provide the updated value here. |
Ttl | integer | optional | TTL in seconds. Use 1 for automatic. |
Proxied | boolean | optional | Whether to route through Cloudflare proxy. |
Sample Configuration
{
"resource": "dns",
"operation": "update",
"connection": {
"ApiToken": "{{ $credentials.cloudflare_dns_edit }}"
},
"ZoneId": "023e105f4ecef8ad9ca31a8372d0c353",
"RecordId": "372e67954025e0ba6aaa6d586b9e0b59",
"Type": "A",
"Name": "api.example.com",
"Content": "203.0.113.10",
"Ttl": 1,
"Proxied": true
}Validation Errors
| Code | Condition | Resolution |
|---|---|---|
MISSING_API_TOKEN | ApiToken is empty | Set the ApiToken credential with DNS.Edit permission |
MISSING_ZONE_ID | ZoneId is empty | Provide the Zone ID |
MISSING_TYPE | Type field is empty | Provide the record type (carry forward from dns/get if unchanged) |
MISSING_NAME | Name field is empty | Provide the record name (carry forward from dns/get if unchanged) |
MISSING_CONTENT | Content field is empty | Provide the updated record value |
UNKNOWN_ERROR | Record not found or insufficient permissions | Verify RecordId and Zone ID; confirm token has DNS.Edit |
Output
Success Port
| Field | Type | Description |
|---|---|---|
id | string | Record UUID (unchanged) |
type | string | Record type after update |
name | string | Record name after update |
content | string | Record value after update |
ttl | integer | TTL after update |
proxied | boolean | Proxy status after update |
modifiedOn | string | ISO 8601 timestamp of the update |
Error Port
On failure, the error port receives an object with code and message.
Sample Output
{
"id": "372e67954025e0ba6aaa6d586b9e0b59",
"type": "A",
"name": "api.example.com",
"content": "203.0.113.10",
"ttl": 1,
"proxied": true,
"modifiedOn": "2026-05-26T14:00:00Z"
}Expression Reference
| Expression | Returns |
|---|---|
{{ $node.DnsUpdate.output.id }} | Record UUID |
{{ $node.DnsUpdate.output.content }} | Updated record value |
{{ $node.DnsUpdate.output.modifiedOn }} | Timestamp of the update |
{{ $node.DnsUpdate.output.proxied }} | Proxy status after update |
Node Policies & GuardRails
| Policy | Detail |
|---|---|
| Always call dns/get before dns/update | Carry forward Type, Name, and any unchanged fields from dns/get to avoid unintentional resets |
| Store rollback snapshot | Persist the dns/get output before calling dns/update — enables rollback by re-submitting the original values |
| Require DNS.Edit token | Update requires write permission — a read-only token will fail |
| Store ApiToken in Credentials Manager | Never hardcode the token in configuration JSON |
| DNS changes propagate immediately via Cloudflare | Recursive resolvers cache based on TTL — reduce TTL before migration if fast propagation is needed |
Examples
Example 1: Blue-Green IP Switch
After green environment is validated: (1) Call dns/get to read current A record. (2) Call dns/update with new IP in Content, carry forward Type and Name from dns/get. (3) Log the old IP and new IP to the deployment audit trail. On rollback, reverse the update using the saved dns/get snapshot.
Example 2: Pre-Migration TTL Reduction
24 hours before migration: (1) Call dns/get to read current TTL. (2) Call dns/update with Ttl: 60 but keep Content, Type, Name unchanged. This reduces resolver caching so the actual IP switch propagates in under a minute.
Example 3: Automated DKIM Key Rotation
Triggered by a scheduled workflow: (1) Generate new DKIM key pair. (2) dns/list to find the TXT record for selector._domainkey. (3) Call dns/update with the new DKIM public key value in Content. (4) Send a notification with the new key for any external systems that need updating.