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

# Get Started with NameGrid: Register Your First Domain

> Learn how to authenticate, check domain availability, and register your first domain using the NameGrid REST API in just a few steps.

This guide walks you through everything you need to go from zero to a registered domain using the NameGrid API. By the end you'll have an API key, you'll know how to check whether a domain is available, and you'll have registered your first domain — all from the command line.

<Steps>
  <Step title="Create an API key">
    Every request to the NameGrid API must include an API key. To generate one:

    1. Sign in to your dashboard at [app.namegrid.org](https://app.namegrid.org).
    2. Go to **Settings → API tokens**.
    3. Click **Create token**, give it a descriptive name (e.g. `my-first-key`), and confirm.
    4. Copy the key immediately — it is displayed **only once**.

    Your key looks like this:

    ```
    ng_live_xxxxxxxxxxxxxxxxxxxxxxxx
    ```

    <Note>
      NameGrid stores only a hash of your API key, not the raw value. If you lose your key, revoke it from the dashboard and create a new one.
    </Note>
  </Step>

  <Step title="Check domain availability">
    Before registering, confirm the domain you want is available. Send a `POST` request to `/v1/domains/check` with a list of domain names:

    ```bash theme={null}
    curl -X POST https://api.namegrid.org/v1/domains/check \
      -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{"domains": ["example.com", "example.net"]}'
    ```

    **Response:**

    ```json theme={null}
    {
      "results": [
        { "domain": "example.com", "available": true, "isPremium": false },
        { "domain": "example.net", "available": false, "isPremium": false }
      ]
    }
    ```

    Each result tells you whether the domain is `available` and whether it carries a premium price. Only proceed to registration with domains where `"available": true`.
  </Step>

  <Step title="Register a domain">
    Once you've confirmed availability, register the domain with a `POST` to `/v1/domains`. Include a contact object with the registrant's details — this is required by ICANN for all new registrations.

    <Tip>
      NameGrid uses a credit-based billing model where **1 credit = \$1**. Make sure your account has enough credits before registering. Check your balance in the dashboard or via the [Account API](/api-reference/account/get).
    </Tip>

    ```bash theme={null}
    curl -X POST https://api.namegrid.org/v1/domains \
      -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "domain": "example.com",
        "years": 1,
        "autoRenew": true,
        "privacyEnabled": true,
        "contact": {
          "firstName": "Jane",
          "lastName": "Doe",
          "organization": "Acme Inc",
          "email": "jane@example.com",
          "phone": "+1.5555550123",
          "address1": "123 Main St",
          "city": "Springfield",
          "stateProvince": "IL",
          "postalCode": "62704",
          "country": "US"
        }
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "domain": {
        "name": "example.com",
        "status": "active",
        "autoRenew": true,
        "privacyEnabled": true,
        "years": 1,
        "creditsCharged": 12,
        "expiresAt": "2027-01-04T12:00:00.000Z",
        "createdAt": "2026-01-04T12:00:00.000Z"
      }
    }
    ```

    The `creditsCharged` field confirms how many credits were deducted. The domain is active immediately — you can start managing DNS records right away.
  </Step>

  <Step title="List your domains">
    To see all domains registered under your workspace, send a `GET` request to `/v1/domains`:

    ```bash theme={null}
    curl https://api.namegrid.org/v1/domains \
      -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"
    ```

    The response returns a list of your domains with their status, expiry dates, and renewal settings. Use this endpoint to build dashboards, trigger renewal reminders, or audit your portfolio.
  </Step>
</Steps>

## Next steps

You've registered your first domain — here's where to go from here:

* [Manage DNS records](/guides/manage-dns) — add A, CNAME, MX, and TXT records to your domain.
* [Renew a domain](/guides/renew-domain) — manually renew or verify auto-renewal is configured.
* [Authentication](/authentication) — learn about API key security, workspace scope, and rate limits.
* [API Reference](/api-reference/overview) — explore every available endpoint with full parameter documentation.