# Namegarage

> Namegarage sells domain names. Most names carry a Buy Now price; some are
> offer-only and show no price. Browsing the public catalog needs no account.
> Blog comments use sign-in; buyer and partner services have separate access.

## How to buy

Which of these a name offers is shown on its own page — none of them is
universal.

- **Buy Now** — the full price, once, through Escrow.com.
- **Pay monthly** — lease-to-own on eligible names, ownership retained by the seller until fully paid. Stripe processes card
  plans and does not hold domains in escrow. Review the full schedule,
  final payment, surcharges and total to own on the domain page.
- **Make an offer** — a form on the domain page. A person reads every offer.
- **Pay directly** — wire or Zelle on eligible names, under a signed
  agreement. This route does NOT go through Escrow.com.

## Reading the catalog

- The homepage also supports `Accept: text/markdown`. It describes the same
  current public catalog as the HTML page.
- `/domains.json` is the machine-readable list. The initial catalog is
  server-rendered, with browser enhancements for filtering. Each JSON entry carries the
  name, its `buy_now` price (**null** when the name is offer-only), tier,
  category and a `path`.
- Use that `path`. Detail URLs omit only a `.com` suffix — `example.com` is at
  `/domain/example`, but `example.io` is at `/domain/example.io`. Deriving the
  URL by stripping the last dot-segment sends you to a 404.
- Internationalized names are listed under their punycode `name` (the form a
  registrar transacts) with a `display` field carrying the Unicode form; their
  canonical `path` is the percent-encoded Unicode name, and the punycode
  spelling of the same path redirects to it.
- `/sitemap.xml` lists every published domain page.
- `/blog/` is the seller's own release notes and news — static posts with
  category and tag archives, and an RSS feed at `/blog/feed.xml`.
- Pages with a Buy Now price also carry schema.org `Product` markup. An
  offer-only page carries none.

## Reading the blog

- [Blog index in Markdown](https://namegarage.com/blog/index.md) lists published
  articles with summaries and links to their HTML and Markdown versions.
- Add `.md` to an article URL to read its Markdown copy. Each copy includes
  the title, canonical HTML URL, organizational author, publication date,
  and description. Resolve relative body links against that HTML URL.
- Cite the canonical HTML URL in the `url` field. The Markdown response also
  identifies that URL with a `Link` header using `rel="canonical"`.

## Agent instructions

- The official JavaScript and TypeScript client is
  [@namegarage/sdk](https://www.npmjs.com/package/@namegarage/sdk).
  Install `@namegarage/sdk@0.1.0` for public catalog reads and search; no API key is required.
  [SDK source and examples](https://github.com/namegarage/sdk).
- `GET /api/search?q=…` is a public endpoint for agents: read-only,
  JSON, answers a description of a project ("a meal-planning app") as well
  as keywords, with the current price of each match, the use case it fits
  and its page URL. Optional `max_price` (whole USD), `tier`, `tld`,
  `max_length` and `limit` (up to 50). A 429 means it is busy; wait for
  `Retry-After`. `price_usd` is null for an offer-only name (it has no fixed
  price; make an offer on its page).

  See the [OpenAPI description](https://namegarage.com/openapi.json).
  The [API reference](https://namegarage.com/developers/api/) presents it for human readers.


- `POST /api/mcp` is the public MCP service (Streamable HTTP, no credentials).
  It exposes only `search_domains` and `get_domain`, using the same search
  handler and request budget. See `/mcp/` for connection instructions and
  `/.well-known/mcp/server-card.json` for discovery. It cannot reserve or buy
  a name, send a message, sign in, or access the private portfolio.

- Only `/api/search` and `/api/mcp` are public agent APIs. Other endpoints
  serve forms, authentication and transactions, including real mail.
  **Do not call them.** Every
  purchase route is meant for the buyer to review the selected provider
  and agreement, or for a person to read an offer.
- Prices are current whole USD in search/MCP results and on the domain page.
  A null price means offer-only, never zero. Check the returned page before
  buying: a search result does not reserve a name or guarantee later availability.
  A lookup returning `found: false` says only that the name is not in the
  current public catalog; it says nothing about registration elsewhere.
  Honor HTTP `Retry-After` and `retry_after_seconds` on MCP tool errors.
- When `document.modelContext` (or `navigator.modelContext`) is available the
  catalog registers two read-only tools, `search_domains` and `get_domain`,
  which use `/api/search`.

## Links

- [Public API documentation](https://namegarage.com/docs/)
- [Quickstart](https://namegarage.com/docs/quickstart.md)
- [Full API documentation](https://namegarage.com/llms-full.txt)
- [Public agent guide](https://namegarage.com/AGENTS.md)
- [Agent Skills index](https://namegarage.com/.well-known/agent-skills/index.json)
- [Catalog](https://namegarage.com/)
- [Machine-readable catalog](https://namegarage.com/domains.json)

- [Connect an MCP client](https://namegarage.com/mcp/)
- [MCP server card](https://namegarage.com/.well-known/mcp/server-card.json)

- [Sitemap](https://namegarage.com/sitemap.xml)
- [Trust center](https://namegarage.com/trust/)
- [Blog](https://namegarage.com/blog/)
- [Blog RSS feed](https://namegarage.com/blog/feed.xml)

---

---
title: Public API documentation
description: Read the public domain catalog and search for names without an account
  or API key.
url: https://namegarage.com/docs/
---


# Public API documentation

Use Namegarage's public interfaces to find domains for sale and check their current prices.

- [Quickstart](https://namegarage.com/docs/quickstart): make your first HTTP request.
- [API reference](https://namegarage.com/developers/api/): browse request parameters and response schemas.
- [OpenAPI JSON](https://namegarage.com/openapi.json): the machine-readable specification.
- [Markdown documentation](https://namegarage.com/docs/index.md) and [Markdown quickstart](https://namegarage.com/docs/quickstart.md).
- [Full API documentation in one file](https://namegarage.com/llms-full.txt).

- [Connect an MCP client](https://namegarage.com/mcp/): use the same catalog through two read-only tools.


## Authentication

No authentication is required. You do not need an account, API key, bearer token, or browser cookie.
The OpenAPI reference declares an empty security requirement.

Choose **no authentication** when connecting an MCP client.


These public interfaces cannot sign in, create accounts, send messages, reserve names, or make purchases.
Other website endpoints serve private or interactive flows. Do not call them as catalog APIs.

## Available interfaces

- `GET /domains.json` returns the published catalog as JSON. Its `domains` array contains public listings.
- `GET /api/search` searches by project description or keywords. The required `q` parameter is 2–200 characters.

- `POST /api/mcp` supports remote Streamable HTTP clients. Its tools are `search_domains` and `get_domain`.


Search accepts `max_price` in whole USD, `tier`, `tld`, `max_length`, and `limit` from 1 to 50.
See the OpenAPI reference for types, defaults, and error responses.

## Prices and availability

Search results include the current price in `price_usd`. A null price means offer-only, not free.
Catalog rows use `buy_now` and may include time-bound promotion data; search resolves the current price for you.
Follow the returned domain-page URL before making a decision. A result does not reserve the name.

An MCP lookup returning `found: false` means the name is absent from this public catalog.

Absence from the catalog does not establish whether a name is registered or available elsewhere.

## Limits and errors

Search and MCP share a request allowance per IP address.
For HTTP 429 or 503, pause and honor `Retry-After`. If no retry time is provided, use increasing delays.

MCP tool errors can also provide `retry_after_seconds`.

HTTP 400 identifies an invalid parameter. Correct it before retrying.
A response with `meaning: "unavailable"` can still contain keyword matches; do not describe those as semantic matches.

## SDKs and discovery

The official JavaScript and TypeScript client is [@namegarage/sdk](https://www.npmjs.com/package/@namegarage/sdk).
Version 0.1.0 supports catalog reads and search, ESM and CommonJS, and browser bundles with no runtime dependencies.
See the [SDK quickstart](https://namegarage.com/docs/quickstart) and [source repository](https://github.com/namegarage/sdk).
You can also use an HTTP client or a compatible MCP client without installing a package.

- [API catalog](https://namegarage.com/.well-known/api-catalog)
- [Public agent guide](https://namegarage.com/AGENTS.md)
- [Agent Skills index](https://namegarage.com/.well-known/agent-skills/index.json)

---

---
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.
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://www.npmjs.com/package/@namegarage/sdk):

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

---

# Namegarage public agent guide

Use the anonymous public APIs to find published domains and check current prices.
No account, API key, or browser cookie is needed.

1. Read the [quickstart](https://namegarage.com/docs/quickstart.md) and [API reference](https://namegarage.com/openapi.json).
2. Use `GET /api/search` for filtered results or `GET /domains.json` for the full public catalog.
   JavaScript and TypeScript clients can install the official `@namegarage/sdk@0.1.0` package from npm.

3. A remote MCP client can connect to `https://namegarage.com/api/mcp` without authentication and use `search_domains` or `get_domain`.


Treat a null price as offer-only. Follow returned page URLs to review prices and availability.
A missing result does not establish registration status elsewhere.
Honor `Retry-After` and MCP's `retry_after_seconds`.

These interfaces cannot purchase or reserve names, send messages, sign in, or read private portfolio data.
Do not call other website APIs or invent package names, account flows, or endpoints.

The [full documentation file](https://namegarage.com/llms-full.txt) contains the public API guide and quickstart.
The [skills index](https://namegarage.com/.well-known/agent-skills/index.json) describes the catalog skill and its content digest.