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

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

string

required

The domain name to add the record to (e.g. example.com).

Body Parameters

string

required

The DNS record type. Must be one of: A, AAAA, ALIAS, CNAME, HTTPS, MX, NS, PTR, SRV, SVCB, TLS, TXT.

string

The record name. Use @ to target the domain apex (root). Defaults to @ if omitted.

integer

Time to live in seconds. Defaults to 3600 (1 hour). Values are clamped to the range 60–86400.

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.

Request Example

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

object

The newly created DNS record.

Show record object

string

Opaque record identifier. Save this value — you’ll need it to update or delete this record later.

string

The DNS record type as provided in the request.

string

The record name. @ represents the domain apex (root).

integer

Time to live in seconds.

string

The record value as provided in the request.

boolean

true if the domain is still being provisioned at the registrar. The record is saved and will be applied automatically once provisioning completes.

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

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.

More Examples

{ "type": "A", "name": "@", "value": "192.0.2.1" }

{ "type": "MX", "name": "@", "value": "mail.example.com" }

{ "type": "TXT", "name": "@", "value": "v=spf1 include:example.com ~all" }

Errors

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

Overview

Domains

DNS Records

Account

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

Endpoint

Path Parameters

Body Parameters

Request Example

Response

More Examples

Errors

​Endpoint

​Path Parameters

​Body Parameters

​Request Example

​Response

​More Examples

​Errors

Endpoint

Path Parameters

Body Parameters

Request Example

Response

More Examples

Errors