> ## 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.

# POST /v1/domains/{domain}/dns — Create a DNS Record

> POST /v1/domains/{domain}/dns — Create a new DNS record. Supports A, AAAA, ALIAS, CNAME, HTTPS, MX, NS, PTR, SRV, SVCB, TLS, and TXT records.

Use this endpoint to add a new DNS record to a domain in your workspace. You can create any standard record type including `A`, `AAAA`, `CNAME`, `MX`, and `TXT`, as well as newer types like `HTTPS`, `SVCB`, and `ALIAS`. The response includes the full record object with its assigned `id` — store that value, as you'll need it to update or delete the record later.

## Endpoint

**POST** `/v1/domains/{domain}/dns`

## Path Parameters

<ParamField path="domain" type="string" required>
  The domain name to add the record to (e.g. `example.com`).
</ParamField>

## Body Parameters

<ParamField body="type" type="string" required>
  The DNS record type. Must be one of: `A`, `AAAA`, `ALIAS`, `CNAME`, `HTTPS`, `MX`, `NS`, `PTR`, `SRV`, `SVCB`, `TLS`, `TXT`.
</ParamField>

<ParamField body="name" type="string">
  The record name. Use `@` to target the domain apex (root). Defaults to `@` if omitted.
</ParamField>

<ParamField body="ttl" type="integer">
  Time to live in seconds. Defaults to `3600` (1 hour). Values are clamped to the range `60`–`86400`.
</ParamField>

<ParamField body="value" type="string" required>
  The record value. Format depends on the record type — for example, an IPv4 address for `A` records, or a fully-qualified hostname for `CNAME` records.
</ParamField>

## Request Example

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

## Response

**200 OK**

<ResponseField name="record" type="object">
  The newly created DNS record.

  <Expandable title="record object">
    <ResponseField name="id" type="string">
      Opaque record identifier. Save this value — you'll need it to update or delete this record later.
    </ResponseField>

    <ResponseField name="type" type="string">
      The DNS record type as provided in the request.
    </ResponseField>

    <ResponseField name="name" type="string">
      The record name. `@` represents the domain apex (root).
    </ResponseField>

    <ResponseField name="ttl" type="integer">
      Time to live in seconds.
    </ResponseField>

    <ResponseField name="value" type="string">
      The record value as provided in the request.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pendingFulfillment" type="boolean">
  `true` if the domain is still being provisioned at the registrar. The record is saved and will be applied automatically once provisioning completes.
</ResponseField>

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

<Tip>
  Save the returned `id` — you'll need it to update or delete this record later. There's no other way to address a specific record once it's been created.
</Tip>

## More Examples

<CodeGroup>
  ```json A Record theme={null}
  { "type": "A", "name": "@", "value": "192.0.2.1" }
  ```

  ```json MX Record theme={null}
  { "type": "MX", "name": "@", "value": "mail.example.com" }
  ```

  ```json TXT Record (SPF) theme={null}
  { "type": "TXT", "name": "@", "value": "v=spf1 include:example.com ~all" }
  ```
</CodeGroup>

## Errors

| Status | Description                                                                          |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | `type` is not a recognized record type, or `value` is missing from the request body. |