# Make your first call (https://developer.godaddy.com/en/docs/api-users/quickstart)



<Callout type="info" title="Tip">
  For full API coverage, provide the [Domains v3 OpenAPI spec](https://developer.godaddy.com/openapi/domains-v3.json) as additional context to your LLM or API client.
</Callout>

## Overview

This guide walks through making `GET /v3/domains/check-availability` against the production API. The call is read-only and doesn't require domains to already be registered to your account.

## Prerequisites

Before calling the Domains API, you need:

* a GoDaddy account
* a Personal Access Token (PAT) with the appropriate scopes
  <Callout type="info" title="Note">
    Go to [Authenticate](https://developer.godaddy.com/docs/api-users/auth) to generate a PAT.
  </Callout>
* a terminal with `curl` (macOS, Linux, or WSL)
* Optional: the beta `gddy` CLI, if you prefer CLI workflows. Go to [Set up the CLI](https://developer.godaddy.com/docs/api-users/cli-setup).

## Set the credential as an environment variable

The PAT is passed as a Bearer token in the `Authorization` header on every request. Exporting it as an environment variable keeps it out of your shell history and lets you reference it directly in commands without retyping.

* Export the credential:

```bash
export GODADDY_PAT="<YOUR_GODADDY_PAT>"
```

## Make the call

`GET /v3/domains/check-availability` takes a single `domain` query parameter and returns whether that domain can be registered, along with current pricing for each registration term. The request is read-only, so no charges apply.

* Run the request:

<Tabs items={['curl', 'Node', 'Python']}>
  <>
    <Tab value="curl">
      ```bash
      curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com" \
        -H "Authorization: Bearer $GODADDY_PAT"
      ```
    </Tab>

    <Tab value="Node">
      ```js
      const pat = process.env.GODADDY_PAT;
      const res = await fetch(
        "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com",
        {
          headers: {
            Authorization: "Bearer " + pat,
          },
        }
      );
      const result = await res.json();
      console.log(result);
      ```
    </Tab>

    <Tab value="Python">
      ```python
      import os, requests

      pat = os.environ["GODADDY_PAT"]
      res = requests.get(
          "https://api.godaddy.com/v3/domains/check-availability",
          params={"domain": "your-idea.com"},
          headers={
              "Authorization": "Bearer " + pat,
          },
      )
      print(res.json())
      ```
    </Tab>
  </>
</Tabs>

## Read the response

The API returns a JSON object describing availability and current pricing. `available` tells you whether the domain can be registered right now. `prices[]` contains one entry per registration term. `price.value` and `renewalPrice.value` are expressed in the smallest currency unit, such as cents for USD. Divide by 100 when displaying USD prices.

* Check that your output matches this shape:

```json
{
  "available": true,
  "definitive": false,
  "domain": "your-idea.com",
  "inventory": "REGISTRY",
  "prices": [
    {
      "period": 1,
      "price": {
        "currencyCode": "USD",
        "value": 1199
      },
      "renewalPrice": {
        "currencyCode": "USD",
        "value": 2299
      },
      "term": "YEAR"
    },
    {
      "period": 2,
      "price": {
        "currencyCode": "USD",
        "value": 3098
      },
      "renewalPrice": {
        "currencyCode": "USD",
        "value": 4598
      },
      "term": "YEAR"
    }
  ]
}
```

The API may return more `prices[]` entries for additional periods. Availability and pricing are indicative; the final price is locked when you create a registration quote.

## Common errors

| Error                             | Likely cause                                                           | Fix                                                                                                                                                                                    |
| --------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`                | Token is missing, expired, or wasn't exported                          | Run `echo $GODADDY_PAT` — if blank, re-run the export. If the token was deleted or expired, generate a new one in the [developer dashboard](https://developer.godaddy.com/personal-access-token).                   |
| `403 Forbidden`                   | Token lacks `domains.domain:read` scope, or the account isn't eligible | Check the `code` field in the response body. Scope issues return `UNABLE_TO_AUTHENTICATE`; account issues return a different code. Regenerate the PAT with the correct scope selected. |
| `429 Too Many Requests`           | Rate limit exceeded                                                    | Wait for the number of seconds in the `Retry-After` header before retrying. Go to [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) for current values and retry guidance.                    |
| Response is `null` or `undefined` | The JSON response wasn't awaited or parsed                             | Ensure you `await res.json()` in Node, or `res.json()` in Python.                                                                                                                      |
| `Could not resolve host`          | Wrong base URL                                                         | The API base is `https://api.godaddy.com`. There is no local dev server — all requests go to production.                                                                               |

Go to [Handle errors](https://developer.godaddy.com/docs/api-users/errors) for the full error envelope reference, status code semantics, and retry guidance.

## Next steps

Where you go from here depends on what you're trying to do. If you already own domains at GoDaddy, the most common next call is `GET /v1/domains` which lists the domains on your account (covered in [Manage existing domains](https://developer.godaddy.com/docs/api-users/manage-domains/list)). If you want to acquire new domains, start with search and registration (covered in [Search for domains](https://developer.godaddy.com/docs/api-users/search-domains)).