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

***

title: Make your first call
description: Make your first API call to the Domains API using a Personal Access Token (PAT).
agentNotes:
permissions: \["Any account"]
scopes: \["domains.domain:read"]
idempotent: true
destructive: false
failureRecovery: "Read-only. Safe to retry any failure. On 401, verify token has not expired or been revoked. On 429, wait for Retry-After."
related:
guides:

* title: "Search domain availability"
  href: "/docs/api-users/search-domains"
* title: "Register a domain"
  href: "/docs/api-users/purchase-domains/register"
* title: "Manage existing domains"
  href: "/docs/api-users/manage-domains"
  concepts:
* title: "Authentication"
  href: "/docs/api-users/auth"
* title: "Error handling"
  href: "/docs/api-users/errors"
  apis:
* title: "Domains v3 reference"
  href: "/docs/references/rest/domains/v3"

***

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.

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

  Go to [How to Authenticate](https://developer.godaddy.com/docs/api-users/auth/how-to) to create a PAT.
* 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:

```bash tab="curl"
curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com" \
  -H "Authorization: Bearer $GODADDY_PAT"
```

```js tab="Node"
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);
```

```python tab="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())
```

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