---
name: taghost-domains-get-started
area: Domains
supported_surfaces: [api]
description: |-
  Hand your coding agent this playbook to find available domains with the TagHost public Registrar API, compare prices, and return a verified shortlist.
title: 'Find a domain with TagHost'
url: https://taghost.io/domains/get-started.md
runtimes:
  [Claude Code, Cursor, Codex CLI, VS Code with Copilot, Windsurf, Gemini CLI]
---

# Find a domain with TagHost

Find an available domain that fits the user's project and budget with the public TagHost Registrar API. No access token or `Authorization` header is required. TagHost fronts a wholesale registrar (Name.com) and returns availability and registration/renewal prices together.

## How to run

Use the project description, naming preferences, and budget already in the conversation. If you have no naming context, ask what the project does before searching.

Perform actions yourself when HTTP tools are available. Do not merely return commands for the user to copy. Finish with a shortlist; purchasing a domain requires a separate user request completed in the TagHost console.

## Generate candidate names

Use the user's exact names when provided. Otherwise generate candidates by combining relevant keywords with the supported extensions. Get the supported TLDs first:

```sh
curl -fsS 'https://api.taghost.io/tlds/supported'
```

Example response:

```json
["com", "io", "dev", "app", "net", "co"]
```

Combine the keyword with each extension to form exact full domains, e.g. for the brief "developer tool for shipping previews" and keyword `shipit`: `shipit.com`, `shipit.dev`, `gowshipit.com`, `shipitapp.dev`. If the user has no naming context, ask before searching.

## Check availability and prices

Send up to 200 exact domains per request with a POST to the public availability and pricing endpoint:

```sh
curl -fsS 'https://api.taghost.io/domains/check' \
  -H 'Content-Type: application/json' \
  -d '{"domains":["shipit.com","shipit.dev","gowshipit.com","shipitapp.dev"]}'
```

Read the JSON `results` array. Each result contains:

| Field            | Meaning                                                      |
| ---------------- | ------------------------------------------------------------ |
| `domain`         | The full domain checked.                                     |
| `available`      | Whether the domain is available to register.                 |
| `purchasePrice`  | Registration price in USD, or `null` when unavailable.       |
| `renewalPrice`   | Renewal price in USD, or `null` when unavailable.            |
| `transferPrice`  | Transfer price in USD, or `null`.                            |
| `years`          | The term associated with the displayed prices, or `null`.    |
| `premium`        | Whether the registrar priced it as a premium name.           |

Keep results with `available: true` and compare `purchasePrice` against the budget.

## Get final prices

Run final pricing for the shortlisted names, even though `/domains/check` already returned prices:

```sh
curl -fsS 'https://api.taghost.io/domains/price' \
  -H 'Content-Type: application/json' \
  -d '{"domains":["shipit.dev"]}'
```

`/domains/price` returns a `results` array with `purchasePrice`, `renewalPrice`, `transferPrice`, and `years`. Use these final quotes for the shortlist and budget comparison. A price quote alone does not establish availability; combine it with a successful availability check from `/domains/check`.

## Public endpoint reference

All paths below fall under `https://api.taghost.io` and require no authentication. CORS is open for programmatic access.

| Method | Path               | Purpose                                    |
| ------ | ------------------ | ------------------------------------------ |
| POST   | `/domains/check`   | Bulk availability and registration pricing |
| POST   | `/domains/price`   | Bulk final pricing                         |
| GET    | `/tlds/supported`  | Supported TLD extensions                   |
| GET    | `/domains/search`  | Keyword search across supported TLDs       |

Replace `:tld` in the returned list with an extension such as `com`. Prices are quoted in USD for a one-year term; `years` encodes the actual term.

## Recover from blocked queries

Inspect the HTTP status and error body before treating JSON as search results.

| Problem                          | Next action                                                        |
| -------------------------------- | ------------------------------------------------------------------ |
| `400` invalid request            | Submit fully-qualified domain names (no schemes, paths, or spaces). |
| `503` registrar not configured   | Availability cannot be verified right now; do not report names as available. |
| Network or service failure       | Retry transient failures with backoff. If the failure persists, report what could not be verified. |

An error does not mean a domain is unavailable. Preserve successful results and identify any names you could not check.

## Completion

Search and domain pricing can return different registration prices. Use the final domain pricing quotes for the shortlist and budget comparison. A price quote alone does not establish availability; combine it with a successful availability check. A missing or `null` price is unknown, never zero.

Report only verified state. Recommend a small set of available names that match the user's preferences. For each name, include:

- The exact domain and why it fits the project.
- Registration price, renewal price, and the quoted term from the final domain pricing check.
- The availability observed during this search.

Separate checked results from unverified naming ideas. Availability and prices can change; refresh stale results when the user returns to a candidate. If nothing suitable is available within the budget, explain the constraint and suggest a focused change to the name or extensions.

Sources:

- https://taghost.io/domains
- https://api.taghost.io/tlds/supported