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

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

> Complete reference for the NameGrid REST API. Base URL, authentication, rate limits, error codes, and response format for all endpoints.

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
```

<Note>
  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.
</Note>

## 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](/authentication) 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.

<Info>
  If you anticipate needing higher throughput, consider batching operations where supported — for example, the [Check Availability](/api-reference/domains/check) endpoint accepts up to 20 domains in a single request.
</Info>

## Error Responses

All error responses share a consistent JSON shape:

```json theme={null}
{ "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Domains" icon="globe" href="/api-reference/domains/check">
    Check availability, register, list, update, and renew domains. Manage nameservers and WHOIS privacy settings.
  </Card>

  <Card title="DNS Records" icon="server" href="/api-reference/dns/list">
    Create, read, update, and delete DNS records for any domain in your workspace.
  </Card>

  <Card title="Account" icon="user" href="/api-reference/account/get">
    Retrieve your workspace details, credit balance, and API key metadata.
  </Card>
</CardGroup>