---
title: Public API quickstart
description: Fetch the catalog and search for domains with curl or the official JavaScript
  and TypeScript SDK. No account or API key is required.
url: https://namegarage.com/docs/quickstart
---


# Public API quickstart

Find published domains with `curl` or the official JavaScript and TypeScript client.

## Authentication

These requests are anonymous. Do not add an `Authorization` header, API key, or browser cookie.

## 1. Read the catalog

```bash
curl --fail-with-body --silent --show-error 'https://namegarage.com/domains.json'
```

The response is JSON with `brand`, `count`, and a `domains` array.
For filtered results with current prices, use search instead of downloading the catalog repeatedly.

## 2. Search by project description

```bash
curl --fail-with-body --silent --show-error --get 'https://namegarage.com/api/search' \
  --data-urlencode 'q=meal-planning app' \
  --data-urlencode 'limit=3'
```

The JSON response has `query`, `priced_at`, `meaning`, `count`, and `results`.
Each result has `name`, `url`, `tier`, `price_usd`, `match`, and `fits`.
A query may return no matches. A null `price_usd` means offer-only, not zero.

Add `--data-urlencode 'max_price=5000'` to set a whole-USD budget.
You can also filter by `tier`, `tld`, or `max_length`. The maximum `limit` is 50.
The [OpenAPI reference](https://namegarage.com/openapi.json) describes every parameter.


## 3. Connect an MCP client

In a client that supports remote MCP, choose Streamable HTTP and no authentication.
Use this server URL:

```text
https://namegarage.com/api/mcp
```

Call `search_domains` with these arguments:

```json
{"query":"meal-planning app","limit":3}
```

To check one result, call `get_domain` with its complete `name`, including the suffix.
`get_domain` also returns the published `domain.description` and `domain.use_cases`. Empty fields mean no copy is published or the copy is withheld.
Call `get_purchase_options` with the same `name` to compare the outright price with standard zero-down lease plans.
Call `suggest_alternatives` with a complete reference `name` to find other published listings. Add your project description in `query` and your cash budget in `max_price`. This does not check registration availability.
See [MCP connection instructions](https://namegarage.com/mcp/) for client guidance.


## Handle the response

Open a returned `url` to review the domain. Prices and availability can change.
Search and MCP do not reserve names or buy them.

If you receive 429 or 503, wait for `Retry-After` before retrying.
For HTTP 400, correct the parameter named in the error.
Do not retry form, account, or transaction endpoints as alternatives.

Read the [API documentation](https://namegarage.com/docs/) for limits and price semantics.

## JavaScript and TypeScript

Install the [official SDK](https://registry.npmjs.org/@namegarage%2fsdk):

```bash
npm install @namegarage/sdk@0.1.0
```

```typescript
import { Namegarage } from '@namegarage/sdk';

const client = new Namegarage();
const matches = await client.searchDomains('meal-planning app', {
  maxPrice: 5000,
  limit: 3,
});

for (const domain of matches.results) {
  console.log(domain.name, domain.price_usd, domain.url);
}

const catalog = await client.getCatalog();
console.log(catalog.count);
```

Use Node.js 22 or later, or bundle the SDK for a modern browser. It supports ESM and CommonJS,
includes TypeScript declarations, and has no runtime dependencies. No credentials are required.
Options use `maxPrice` and `maxLength`; response fields keep their API names, including `price_usd`.

The client never retries automatically. HTTP failures throw `NamegarageApiError`, with `status`,
`code`, and `retryAfterSeconds`; honor the server's retry time. A null price still means offer-only.
See the [source and complete examples](https://github.com/namegarage/sdk) for cancellation,
timeouts, and error handling. The SDK only reads the public catalog and search API.

## Look up a name, compare payments and find alternatives

Use the documented GET routes `/api/domain`, `/api/purchase-options` and
`/api/alternatives`, each with a complete URL-encoded `name` parameter.
Alternatives also accept `query`, whole-USD `max_price` and `limit` (1–50).
The reference is excluded before limiting and need not be in our catalog.



Payment amounts come from the server. Compare the final payment and total as
well as the monthly amount; a cash-only discount can leave the lease principal
unchanged. Follow the returned page for current terms and additional checkout fees.
The [developer changelog](https://namegarage.com/developers/changelog/) records the compatible releases.