> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotlet.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage DNS records

> Create, update, and sync DNS records for a domain you've registered or hosted with Dotlet.

Once a domain has a DNS zone, created during purchase or with [setup-dns](/api-reference/domains/setup-dns-for-domain), you can manage its records directly through the API.

<Note>
  Listing records accepts either an API key or a bearer token. Creating, reading a single record, updating, deleting, and syncing currently accept an **API key only**. See [Authentication](/authentication) for the full breakdown.
</Note>

## List existing records

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records \
    -H "X-API-Key: dk_••••••••••••••••"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records', {
    headers: { 'X-API-Key': 'dk_••••••••••••••••' }
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records',
      headers={'X-API-Key': 'dk_••••••••••••••••'}
  )
  print(response.json())
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	req, _ := http.NewRequest("GET", "https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records", nil)
  	req.Header.Set("X-API-Key", "dk_••••••••••••••••")

  	resp, _ := http.DefaultClient.Do(req)
  	defer resp.Body.Close()

  	body, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

Results are paginated with `skip` and `limit` query parameters (default `limit` is 100):

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records?skip=0&limit=50" \
    -H "X-API-Key: dk_••••••••••••••••"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records?skip=0&limit=50', {
    headers: { 'X-API-Key': 'dk_••••••••••••••••' }
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records',
      headers={'X-API-Key': 'dk_••••••••••••••••'},
      params={'skip': 0, 'limit': 50}
  )
  print(response.json())
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	req, _ := http.NewRequest("GET", "https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records?skip=0&limit=50", nil)
  	req.Header.Set("X-API-Key", "dk_••••••••••••••••")

  	resp, _ := http.DefaultClient.Do(req)
  	defer resp.Body.Close()

  	body, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

## Create a record

Point your domain at a server by creating an `A` record. `record_type` accepts `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV`, or `CAA`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records \
    -H "X-API-Key: dk_••••••••••••••••" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "acmewidgets.com",
      "record_type": "A",
      "content": "203.0.113.10",
      "ttl": 300
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records', {
    method: 'POST',
    headers: {
      'X-API-Key': 'dk_••••••••••••••••',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'acmewidgets.com',
      record_type: 'A',
      content: '203.0.113.10',
      ttl: 300
    })
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records',
      headers={'X-API-Key': 'dk_••••••••••••••••'},
      json={
          'name': 'acmewidgets.com',
          'record_type': 'A',
          'content': '203.0.113.10',
          'ttl': 300
      }
  )
  print(response.json())
  ```

  ```go Go theme={null}
  package main

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	payload := map[string]interface{}{
  		"name":        "acmewidgets.com",
  		"record_type": "A",
  		"content":     "203.0.113.10",
  		"ttl":         300,
  	}
  	body, _ := json.Marshal(payload)

  	req, _ := http.NewRequest("POST", "https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records", bytes.NewBuffer(body))
  	req.Header.Set("X-API-Key", "dk_••••••••••••••••")
  	req.Header.Set("Content-Type", "application/json")

  	resp, _ := http.DefaultClient.Do(req)
  	defer resp.Body.Close()

  	respBody, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(respBody))
  }
  ```
</CodeGroup>

```json theme={null}
{
  "id": "9c858901-8a57-4791-81fe-4c455b099bc9",
  "name": "acmewidgets.com",
  "record_type": "A",
  "content": "203.0.113.10",
  "ttl": 300,
  "priority": null,
  "proxied": false
}
```

For subdomains, include the full hostname in `name`, for example, `api.acmewidgets.com`. For an `MX` record, also set `priority`; for a Cloudflare-hosted zone, set `proxied: true` to route traffic through Cloudflare's proxy.

## Update a record

Send only the fields you want to change, `PUT` here behaves as a partial update, so omitted fields keep their current value.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records/9c858901-8a57-4791-81fe-4c455b099bc9 \
    -H "X-API-Key: dk_••••••••••••••••" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "203.0.113.55"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records/9c858901-8a57-4791-81fe-4c455b099bc9', {
    method: 'PUT',
    headers: {
      'X-API-Key': 'dk_••••••••••••••••',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: '203.0.113.55'
    })
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      'https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records/9c858901-8a57-4791-81fe-4c455b099bc9',
      headers={'X-API-Key': 'dk_••••••••••••••••'},
      json={'content': '203.0.113.55'}
  )
  print(response.json())
  ```

  ```go Go theme={null}
  package main

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	payload := map[string]interface{}{
  		"content": "203.0.113.55",
  	}
  	body, _ := json.Marshal(payload)

  	req, _ := http.NewRequest("PUT", "https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records/9c858901-8a57-4791-81fe-4c455b099bc9", bytes.NewBuffer(body))
  	req.Header.Set("X-API-Key", "dk_••••••••••••••••")
  	req.Header.Set("Content-Type", "application/json")

  	resp, _ := http.DefaultClient.Do(req)
  	defer resp.Body.Close()

  	respBody, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(respBody))
  }
  ```
</CodeGroup>

## Delete a record

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records/9c858901-8a57-4791-81fe-4c455b099bc9 \
    -H "X-API-Key: dk_••••••••••••••••"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records/9c858901-8a57-4791-81fe-4c455b099bc9', {
    method: 'DELETE',
    headers: { 'X-API-Key': 'dk_••••••••••••••••' }
  });
  console.log(response.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      'https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records/9c858901-8a57-4791-81fe-4c455b099bc9',
      headers={'X-API-Key': 'dk_••••••••••••••••'}
  )
  print(response.status_code)
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  )

  func main() {
  	req, _ := http.NewRequest("DELETE", "https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/records/9c858901-8a57-4791-81fe-4c455b099bc9", nil)
  	req.Header.Set("X-API-Key", "dk_••••••••••••••••")

  	resp, _ := http.DefaultClient.Do(req)
  	defer resp.Body.Close()

  	fmt.Println(resp.StatusCode)
  }
  ```
</CodeGroup>

A successful delete returns `204 No Content`.

## Sync records from the provider

If records were changed directly in your DNS provider's dashboard (for example, in Cloudflare) rather than through this API, sync them back into Dotlet so future API calls reflect the current state.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/sync \
    -H "X-API-Key: dk_••••••••••••••••"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/sync', {
    method: 'POST',
    headers: { 'X-API-Key': 'dk_••••••••••••••••' }
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/sync',
      headers={'X-API-Key': 'dk_••••••••••••••••'}
  )
  print(response.json())
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	req, _ := http.NewRequest("POST", "https://api.dotlet.net/api/v1/registrar/dns/acmewidgets.com/sync", nil)
  	req.Header.Set("X-API-Key", "dk_••••••••••••••••")

  	resp, _ := http.DefaultClient.Do(req)
  	defer resp.Body.Close()

  	body, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

Run a sync before scripting bulk updates, so you're not overwriting changes the API doesn't know about yet.

## Next steps

<Card title="DNS API reference" icon="server" href="/api-reference/dns/list-dns-records">
  Full parameter and response details for every DNS endpoint.
</Card>