DNS Record and Name Server Management: API Write Endpoints

The 101domain API now supports full DNS record management and name server updates. Using these endpoints, you can create, edit, and delete individual DNS records, and programmatically replace the name servers for any domain in your account.

DNS record management is available only for domains using 101domain managed name servers or Secure Web Accelerator (SWA) name servers. Domains delegated to external name servers cannot have their DNS records read or managed via the API.

For more detail, see Why Does the DNS Records Endpoint Return an Empty Array or Error?

Understanding Record IDs

Every DNS record returned by the API includes a unique id. This ID is used to identify a specific record when editing or deleting it.

Update name servers: PUT /v1/dns/{domain_name}/name servers

Replaces the name servers for a domain. Submit a complete list of 2–13 name server hostnames. The existing name servers are replaced in full; there is no partial update.

Required scope: dns_write

Request body:

{
  "name servers": [
    "ns1.example.com",
    "ns2.example.com"
  ]
}

Constraints:

• Minimum 2 name servers, maximum 13.

• name servers must be distinct (case-insensitive).

• Each name server must be a valid fully qualified hostname.

• Glue records are not supported. Contact support if your name servers require them.

Response codes

400 error codes for name server updates

Domain states that block name server changes

A name server update will be rejected with a 400 error if the domain has any of the following conditions:

• Domain status is cancelled, deleted, or in a transfer-away state.

• Domain is currently transferring in. Complete the transfer first.

• Domain has a registry-side update lock (serverUpdateProhibited). Please contact support to remove the lock.

• Domain has a client update lock (clientUpdateProhibited). Disable the lock before making changes

• Domain has DNSSEC or Secure Web Accelerator (SWA) active. Contact our support team.

• A paid name server change product is required for the domain's TLD. Complete through the control panel

You can check the current registry statuses on a domain using GET /v1/domains/{domain_name} and reviewing the registry_statuses field.

202 response example — change pending

{
  "status": "success",
  "code": "OK",
  "message": "",
  "data": {
    "domain_name": "example.com",
    "change_status": "pending",
    "name servers": [
      "ns1.example.com",
      "ns2.example.com"
    ],
    "current_name servers": [
      "ns1.101domain.com",
      "ns2.101domain.com"
    ]
  }
}

When change_status is pending, the current_name servers field shows the name servers currently active on the domain. Use GET /v1/dns/{domain_name}/name servers to confirm when the change has taken effect.

Create DNS Records: POST /v1/dns/{domain_name}/records

Creates one or more DNS records for a domain. You can submit up to 25 records in a single request.

Required scope: dns_write

Supported record types: A, AAAA, CNAME, NS (subdomain delegations only), MX, TXT, SRV, CAA

Request body

{
  "records": [
    {
      "name": "www",
      "type": "A",
      "ttl": 3600,
      "value": "192.0.2.1"
    }
  ]
}

Field reference by record type

• Name field: Use @ or an empty string for the domain root. Use a bare label (e.g. www) or full FQDN (e.g. www.example.com) for subdomains. The API normalizes these in the response.

• TTL: Minimum 300 seconds. Defaults to 3600 if not provided. On SWA-proxied records, a TTL of 1 means "Automatic."

• Idempotency: If all submitted records already exist, the response is 200 with created_count: 0. If at least one new record is created, the response is 201. This allows safe re-submission without creating duplicates.

Response codes

201 response example

{
  "status": "success",
  "code": "OK",
  "message": "",
  "meta": {
    "created_count": 1,
    "existed_count": 1
  },
  "data": [
    {
      "id": "a3f5e8c2d1b9e7f4",
      "name": "www",
      "type": "A",
      "ttl": 3600,
      "value": "192.0.2.1",
      "proxied": false
    }
  ]
}

400 error codes for record creation

Edit DNS Records: PATCH /v1/dns/{domain_name}/records

Edits up to 25 existing DNS records in a single request. Reference each record by its id and include only the fields you want to change.

Required scope: dns_write

What can be changed: TTL, value, priority, weight, port, target, flag, tag, and the proxied flag (SWA zones only).

What cannot be changed: name and type are immutable. To change a record's name or type, delete the record and create a new one.

Request body:

{
  "records": [
    {
      "id": "a3f5e8c2d1b9e7f4",
      "ttl": 7200
    }
  ]
}

Atomicity: If any id in the batch is not found, the entire request fails and no records are changed. The response includes an errors.not_found_ids array identifying which IDs were missing.

ID behavior on edit: When a record is successfully changed, its id changes. The response includes both old_id (the ID you submitted) and the new id. Store the new id or re-fetch the list before your next operation on that record.

Response codes

200 response example

{
  "status": "success",
  "code": "OK",
  "message": "",
  "meta": {
    "edited_count": 1,
    "unchanged_count": 0
  },
  "data": [
    {
      "old_id": "a3f5e8c2d1b9e7f4",
      "id": "e9c8b7a6f5d4c3b2",
      "name": "www",
      "type": "A",
      "ttl": 7200,
      "value": "192.0.2.1",
      "proxied": false
    }
  ]
}

Delete DNS Records: DELETE /v1/dns/{domain_name}/records

Deletes up to 25 DNS records by their id in a single request.

Required scope: dns_write

Request body:

{
  "ids": [
    "a3f5e8c2d1b9e7f4",
    "c2e9b4a8f1d6c3a7"
  ]
}

Atomicity: If any id in the batch is not found, the entire request fails and no records are deleted. The response includes an errors.not_found_ids array.

Response codes

200 response example

{
  "status": "success",
  "code": "OK",
  "message": "",
  "data": null
}

For troubleshooting help, see Why Was My name server Change Rejected? and Why Can't I Edit or Delete a DNS Record?

For full technical documentation, visit the 101domain API documentation.