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

# Manage DNS Records for Your Domains — NameGrid API

> List, create, update, and delete DNS records for your NameGrid domains via the REST API. Covers A, CNAME, MX, TXT, and all supported record types.

NameGrid gives you full programmatic control over the DNS records attached to your domains. You can list existing records, add new ones, update values in place, and delete records you no longer need — all through a straightforward REST API. Changes are applied automatically, even if the domain is still being provisioned.

## Supported record types

<Info>
  NameGrid supports the following DNS record types: **A**, **AAAA**, **ALIAS**, **CNAME**, **HTTPS**, **MX**, **NS**, **PTR**, **SRV**, **SVCB**, **TLS**, and **TXT**. If you need a record type that is not listed here, contact support.
</Info>

## Listing records

Retrieve all DNS records for a domain with a `GET` request to `/v1/domains/{domain}/dns`.

```bash theme={null}
curl https://api.namegrid.org/v1/domains/yourdomain.com/dns \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

**Response**

```json theme={null}
{
  "records": [
    { "id": "b6b0b6a2-...", "type": "A", "name": "@", "ttl": 3600, "value": "192.0.2.1" }
  ],
  "pendingFulfillment": false
}
```

Each record object includes a unique `id` that you use to update or delete that record later.

<Note>
  When `pendingFulfillment` is `true`, the domain is still being provisioned by the registry. Any changes you make are saved immediately and will be applied automatically once provisioning completes — you don't need to resubmit them.
</Note>

## Adding a record

Create a new DNS record by sending a `POST` request to `/v1/domains/{domain}/dns`. The request body supports the following fields:

| Field   | Required | Default | Description                                                              |
| ------- | -------- | ------- | ------------------------------------------------------------------------ |
| `type`  | Yes      | —       | The DNS record type, e.g. `A`, `CNAME`, `MX`, `TXT`.                     |
| `name`  | No       | `@`     | The subdomain label. Use `@` for the root domain, `www` for a subdomain. |
| `ttl`   | No       | `3600`  | Time-to-live in seconds. Clamped to the range `60`–`86400`.              |
| `value` | Yes      | —       | The record value, e.g. an IP address, hostname, or text string.          |

The example below adds a CNAME record pointing `www` to the root domain.

```bash theme={null}
curl -X POST https://api.namegrid.org/v1/domains/yourdomain.com/dns \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "type": "CNAME", "name": "www", "ttl": 3600, "value": "yourdomain.com" }'
```

**Response**

```json theme={null}
{
  "record": { "id": "b6b0b6a2-...", "type": "CNAME", "name": "www", "ttl": 3600, "value": "yourdomain.com" },
  "pendingFulfillment": false
}
```

<Tip>
  Save the `id` returned in the response. You need it to update or delete this record in the future — there is no way to look up a record by its content alone.
</Tip>

## Updating a record

Change an existing record by sending a `PATCH` request to `/v1/domains/{domain}/dns/{recordId}`. Include only the fields you want to change.

The example below updates an A record's IP address.

```bash theme={null}
curl -X PATCH https://api.namegrid.org/v1/domains/yourdomain.com/dns/b6b0b6a2-... \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "value": "203.0.113.5" }'
```

**Response**

```json theme={null}
{
  "record": { "id": "b6b0b6a2-...", "type": "A", "name": "@", "ttl": 3600, "value": "203.0.113.5" }
}
```

## Deleting a record

Remove a record permanently by sending a `DELETE` request to `/v1/domains/{domain}/dns/{recordId}`.

```bash theme={null}
curl -X DELETE https://api.namegrid.org/v1/domains/yourdomain.com/dns/b6b0b6a2-... \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

**Response**

```json theme={null}
{ "success": true }
```

## Common DNS configurations

<AccordionGroup>
  <Accordion title="Point to a web server (A + CNAME for www)">
    To direct your domain to a web server, add an A record at the root (`@`) pointing to your server's IP address. Then add a CNAME for `www` that points back to the root domain so both `yourdomain.com` and `www.yourdomain.com` resolve correctly.

    **Root A record**

    ```bash theme={null}
    curl -X POST https://api.namegrid.org/v1/domains/yourdomain.com/dns \
      -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{ "type": "A", "name": "@", "ttl": 3600, "value": "203.0.113.5" }'
    ```

    **www CNAME record**

    ```bash theme={null}
    curl -X POST https://api.namegrid.org/v1/domains/yourdomain.com/dns \
      -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{ "type": "CNAME", "name": "www", "ttl": 3600, "value": "yourdomain.com" }'
    ```
  </Accordion>

  <Accordion title="Set up email (MX record)">
    An MX record tells other mail servers where to deliver email for your domain. The `value` field must be the hostname of your mail server. Most providers also require a priority value prepended to the hostname (e.g. `10 mail.example.com`).

    ```bash theme={null}
    curl -X POST https://api.namegrid.org/v1/domains/yourdomain.com/dns \
      -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{ "type": "MX", "name": "@", "ttl": 3600, "value": "10 mail.yourmailprovider.com" }'
    ```

    Check your email provider's documentation for the exact hostname and priority values to use.
  </Accordion>

  <Accordion title="Verify domain ownership (TXT record)">
    Many services (Google Workspace, GitHub, SSL certificate authorities, etc.) ask you to prove that you own a domain by adding a TXT record containing a verification token they provide.

    ```bash theme={null}
    curl -X POST https://api.namegrid.org/v1/domains/yourdomain.com/dns \
      -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{ "type": "TXT", "name": "@", "ttl": 3600, "value": "google-site-verification=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }'
    ```

    Replace the `value` with the exact token string supplied by the service you are verifying with.
  </Accordion>
</AccordionGroup>