dns.records.set

Create or replace the record set at a name and type

POST /dns/api/zones/{id}/recordsIAM dns:ChangeRecordsChanges stateDestructive

name is "@", a relative label such as "www", or a fully qualified name in the zone. ALIAS takes exactly one of appId, loadBalancerId, bucket or distributionId instead of values, and works at the apex. A, AAAA and CNAME may name an uptime check (healthCheckId) and failoverValues answered while it is down; their TTL is then served as at most 60 seconds.

Request syntax

POST /dns/api/zones/{id}/records
{
  "name": "string",
  "type": "enum",
  "ttl": "number",
  "values": "array of string",
  "appId": "string",
  "loadBalancerId": "string",
  "bucket": "string",
  "distributionId": "string",
  "healthCheckId": "string",
  "failoverValues": "array of string",
  "routing": "object"
}

Path parameters

  • idRequired

    string

    Constraints: uuid

Request body

  • nameRequired

    string

    Where the set sits: "@" or empty for the apex, a relative label such as "www", or a fully qualified name inside the zone. Refused (400) outside the zone, for NS or CNAME at the apex, for a CNAME next to other records, and for another type at a name that has a CNAME

    Constraints: max 253 chars

  • typeRequired

    enum

    Record type. ALIAS is the platform type that answers with the address of an app, load balancer, bucket website or CDN distribution. Writing a set replaces the one at the same name and type

    One of: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, ALIAS

  • ttlOptional

    number

    Seconds resolvers may cache the set, 1 to 604800. Absent: 300 in the API (the console form starts at 3600). A set with a health check or routed variant checks is served with at most 60

    Constraints: integer, 1-604800

  • valuesOptional

    array of string

    The record data in presentation format, one entry per value, at most 100 of at most 4096 characters each: A "203.0.113.7", MX "10 mail.example.com", SRV "10 5 5060 sip.example.com", CAA "0 issue letsencrypt.org", TXT the text. Duplicates are merged. A CNAME takes exactly one. Required (400 "At least one value is required") unless the type is ALIAS or routing supplies them, when a routed set takes the first variant's values

    Constraints: 1-4096 chars

  • appIdOptional

    string

    ALIAS: the app whose address is answered

  • loadBalancerIdOptional

    string

    ALIAS: a load balancer, answered with its IPv4 (A) and IPv6 (AAAA)

  • bucketOptional

    string

    ALIAS: a bucket name; the name answers with the bucket's static website

  • distributionIdOptional

    string

    ALIAS: a CDN distribution, answered with its healthy edge nodes (TTL at most 30 s); list the name among the distribution's aliases too, for its certificate

  • healthCheckIdOptional

    string

    A, AAAA, CNAME: an uptime check; null removes it

    May be null.

  • failoverValuesOptional

    array of string

    Answered instead of values while the health check is down

  • routingOptional

    object

    Weighted ({policy:"weighted", variants:[{id, weight 0-255, values, healthCheckId?}]}) or geolocation ({policy:"geo", variants:[{id, country|continent, values, healthCheckId?}]}) routing; null removes it. For geo, values are the default answer.

    Constraints: JSON

    May be null.

Response

201 with the record set as stored, new or replaced: id, zoneId, name (fully qualified), type, ttl, values, aliasAppId, aliasLoadBalancerId, aliasBucketId, aliasDistributionId, healthCheckId, failoverValues, routing, createdAt, updatedAt. 400 with the reason when the name, a value, the ALIAS target, the health check or the routing does not validate, or a target is not found; 409 when a new set would take the zone past 10,000 record sets; 404 when the organization has no such zone.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow dns:ChangeRecords on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud dns records set id --name example --type A

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_dns_records_set.