API reference

Domains

Registered domains, registration orders and DNS records.

List domains GET /v1/domains
Retrieve a domain GET /v1/domains/{id}
Order a domain registration POST /v1/domains
List DNS records GET /v1/domains/{id}/dns
Add a DNS record POST /v1/domains/{id}/dns
Delete a DNS record DELETE /v1/domains/{id}/dns/{recordId}

List domains

GET/v1/domains

Requires a secret key with the read scope.

Parameters

Name	In	Type	Description
`limit`	query	integer	Items per page, 1-100 (default 50).
`offset`	query	integer	Items to skip (default 0).

Request

curl "https://api.newhost.co.za/v1/domains" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": [
    {
      "id": "clx8dom0001",
      "name": "acme.co.za",
      "tld": "co.za",
      "status": "ACTIVE",
      "autoRenew": true,
      "registeredAt": "2025-10-01T00:00:00.000Z",
      "expiresAt": "2026-10-01T00:00:00.000Z",
      "nameservers": [
        "ns1.newhost.co.za",
        "ns2.newhost.co.za"
      ],
      "dnsProvider": "NEWHOST"
    }
  ],
  "has_more": false
}

Retrieve a domain

GET/v1/domains/{id}

Requires a secret key with the read scope.

Parameters

Name	In	Type	Description
`id`required	path	string	The domain ID.

Request

curl "https://api.newhost.co.za/v1/domains/ID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "id": "clx8dom0001",
    "name": "acme.co.za",
    "tld": "co.za",
    "status": "ACTIVE",
    "autoRenew": true,
    "registeredAt": "2025-10-01T00:00:00.000Z",
    "expiresAt": "2026-10-01T00:00:00.000Z",
    "nameservers": [
      "ns1.newhost.co.za",
      "ns2.newhost.co.za"
    ],
    "dnsProvider": "NEWHOST"
  }
}

Order a domain registration

POST/v1/domains

Creates an invoice. It is paid from your wallet when the balance allows, and the domain is registered once paid. Registrant details must be the domain owner's.

Requires a secret key with the domains scope. Returns 201 on success.

Body

Field	Type	Description
`domain`required	string	Domain to register.
`years`	integer	1-10 (default 1).
`registrant`required	object	name, email, contactNumber (+27.821234567), address1, city, province, postalCode, country (ISO-2).
`nameservers`	string[]	2-5 nameservers. Defaults to NewHost's.

Request

curl -X POST "https://api.newhost.co.za/v1/domains" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme-shop.co.za","years":1,"registrant":{"name":"Jane Doe","email":"[email protected]","contactNumber":"+27.821234567","address1":"1 Main Road","city":"Cape Town","province":"Western Cape","postalCode":"8001","country":"ZA"}}'

Response

{
  "data": {
    "invoice": {
      "id": "clx8inv0001",
      "number": "NH-2026-000123",
      "kind": "DOMAIN",
      "status": "PAID",
      "amount": "123.05",
      "vat": "15.00",
      "issuedAt": "2026-09-01T08:00:00.000Z",
      "dueAt": "2026-09-08T08:00:00.000Z",
      "paidAt": "2026-09-01T08:02:11.000Z"
    }
  }
}

List DNS records

GET/v1/domains/{id}/dns

Requires a secret key with the read scope.

Parameters

Name	In	Type	Description
`id`required	path	string	The domain ID.

Request

curl "https://api.newhost.co.za/v1/domains/ID/dns" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": [
    {
      "id": "8812",
      "type": "A",
      "name": "",
      "content": "102.206.119.170",
      "ttl": 3600,
      "prio": 0
    }
  ],
  "provider": "NEWHOST"
}

Add a DNS record

POST/v1/domains/{id}/dns

Requires a secret key with the domains scope. Returns 201 on success.

Parameters

Name	In	Type	Description
`id`required	path	string	The domain ID.

Body

Field	Type	Description
`type`required	string	A, AAAA, CNAME, MX, TXT, SRV, CAA or NS.
`name`	string	Host relative to the domain; empty for the apex.
`content`required	string	Record value.
`ttl`	integer	60-86400 (default 3600).
`prio`	integer	Priority for MX / SRV.

Request

curl -X POST "https://api.newhost.co.za/v1/domains/ID/dns" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"type":"TXT","name":"_verify","content":"token-123","ttl":3600}'

Response

{
  "data": {
    "ok": true
  }
}

Delete a DNS record

DELETE/v1/domains/{id}/dns/{recordId}

Requires a secret key with the domains scope.

Parameters

Name	In	Type	Description
`id`required	path	string	The domain ID.
`recordId`required	path	string	Record ID from List DNS records.

Request

curl -X DELETE "https://api.newhost.co.za/v1/domains/ID/dns/RECORDID" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "ok": true
  }
}

Next: Web & email hosting →