NameGrid REST API — Base URL, Auth, and Error Codes

The NameGrid REST API gives you programmatic control over domain registration and DNS management. Every resource — from checking availability to updating nameservers — is accessible over HTTPS using standard JSON request and response bodies. This reference covers everything you need to start making authenticated requests right away.

Base URL

All API requests are made to the following base URL:

https://api.namegrid.org/v1

Until your domain is fully configured, the API is also reachable at https://app.namegrid.org/api/v1. Both URLs are functionally identical and accept the same requests.

Authentication

The NameGrid API uses API keys for authentication. Pass your key in the x-api-key header with every request:

x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx

Requests made without a valid key, or with a revoked key, will receive a 401 Unauthorized response. See the Authentication guide for instructions on generating and managing your API keys.

Rate Limits

Each API key is limited to 30 requests per 60 seconds. If you exceed this limit, the API returns a 429 Too Many Requests response. Your request window resets on a rolling basis, so you can resume sending requests as older ones fall outside the 60-second window.

If you anticipate needing higher throughput, consider batching operations where supported — for example, the Check Availability endpoint accepts up to 20 domains in a single request.

Error Responses

All error responses share a consistent JSON shape:

{ "error": "<message>" }

When a 402 error occurs, the response also includes required (the credit cost of the operation) and balance (your current credit balance) to help you understand exactly how many credits you need:

{
  "error": "Insufficient credits",
  "required": 1200,
  "balance": 800
}

The table below lists every status code the API may return and what it means:

Status	Meaning
`400`	Malformed request — one or more required fields are missing or contain invalid values
`401`	Missing, invalid, or revoked API key
`402`	Insufficient credits — response includes `required` and `balance` fields
`404`	Resource not found, or not owned by your workspace
`409`	Conflict — the domain is already registered or has a pending registration
`429`	Rate limit exceeded — slow down and retry after the current window resets
`502`	The upstream registrar rejected the request — check the `error` message for details

Endpoints Overview

Domains

Check availability, register, list, update, and renew domains. Manage nameservers and WHOIS privacy settings.

DNS Records

Create, read, update, and delete DNS records for any domain in your workspace.

Account

Retrieve your workspace details, credit balance, and API key metadata.

​Base URL

​Authentication

​Rate Limits

​Error Responses

​Endpoints Overview

Domains

DNS Records

Account

Base URL

Authentication

Rate Limits

Error Responses

Endpoints Overview