# 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 regular blog articles with summaries and links to their HTML and Markdown versions. - [Dev blog](https://namegarage.com/blog/category/engineering) lists engineering articles; their existing HTML and Markdown URLs remain available. - 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"`. ## Instructions for LLM Agents - The official JavaScript and TypeScript client is [@namegarage/sdk](https://registry.npmjs.org/@namegarage%2fsdk). 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 [developer changelog](https://namegarage.com/developers/changelog/) records coordinated component versions. 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 `search_domains`, `get_domain`, and `get_purchase_options`, 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) - [Markdown 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) - [AI capability catalog](https://namegarage.com/.well-known/ai-catalog.json) - [ARD capability manifest](https://namegarage.com/.well-known/ard.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 four 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`, `get_domain`, `get_purchase_options`, and `suggest_alternatives`. 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. `suggest_alternatives` takes a complete reference `name` and optional project `query`, whole-USD `max_price`, and `limit`. It returns only published alternatives and excludes the reference name. It does not check registration availability. `get_domain` includes `domain.description` (string) and `domain.use_cases` (list of strings) from the published domain page. Missing or withheld copy is `""` and `[]`; do not fill it in. Potential uses are suggestions, not proof of suitability or trademark rights. An MCP lookup returning `found: false` means the name is absent from this public catalog. `get_purchase_options` returns `domain.purchase_options` with `currency: "USD"`, the current `buy_outright.total_usd`, and `lease_to_own` schedules. Each schedule includes `months`, `down_payment_usd`, `first_payment_usd`, `monthly_payment_usd`, `final_payment_usd`, `total_usd`, and `extra_cost_vs_buy_outright_usd`. The first through penultimate installments use `monthly_payment_usd`; the last uses `final_payment_usd`. These are standard zero-down plans. `lease_base_price_usd` can differ from the outright price during a cash-only deal. An empty `lease_to_own` list means no standard standalone lease plan is published. A null `buy_outright` means offer-only. Review other payment choices, terms, and any additional checkout fees on the returned domain page. 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://registry.npmjs.org/@namegarage%2fsdk). 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) - [AI capability catalog](https://namegarage.com/.well-known/ai-catalog.json) - [ARD capability manifest](https://namegarage.com/.well-known/ard.json) - [MCP compatibility card](https://namegarage.com/.well-known/mcp.json) - [Public agent guide](https://namegarage.com/AGENTS.md) - [Agent Skills index](https://namegarage.com/.well-known/agent-skills/index.json) ## Poppy The [Poppy discovery document](https://namegarage.com/.well-known/poppy.json) describes website-only support for Personal Agent Protocol draft 0.3. Agents browse public pages as ordinary signed-out visitors. This integration offers no Poppy sessions, sign-in, account access, or transactions. Read the [excluded tasks](https://namegarage.com/docs/poppy-excluded-tasks.json) before starting a task. The anonymous APIs above remain available independently. They are not advertised as Poppy APIs, which would require OAuth sessions and DPoP support. ## HTTP catalog operations - `GET /api/domain?name=...` returns the exact published lookup envelope: `name`, `priced_at`, `found`, and `domain`. - `GET /api/purchase-options?name=...` adds the same `domain.purchase_options` as MCP. - `GET /api/alternatives?name=...&query=...&max_price=3000&limit=5` returns `name` plus the search envelope and excludes the reference before limiting. Missing lookup names return HTTP 200 with `found: false` and `domain: null`. Invalid, duplicate or unknown parameters return 400; noncanonical paths return 404; methods other than GET return 405. Requests share the existing search/MCP allowance. Both `Retry-After` and response fields retain the existing bounded refusal semantics. See the [developer changelog](https://namegarage.com/developers/changelog/) for release versions. ## Delegate a shortlist Use the [read-only A2A concierge](https://namegarage.com/docs/a2a) to send a project brief with typed constraints and receive current catalog matches in one response. --- --- 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. --- --- title: Read-only A2A domain-selection concierge description: Delegate a domain shortlist using the anonymous Namegarage catalog. url: https://namegarage.com/docs/a2a --- # Select domains with A2A No account, API key, cookie or Authorization header is required. Read the [A2A 1.0 Agent Card](https://namegarage.com/.well-known/agent-card.json). Send JSON-RPC requests to `https://namegarage.com/api/a2a` with `A2A-Version: 1.0`. The service returns a direct Message, with no stored task or conversation. Repeat the full brief and filters on each request; a context ID is correlation only. ```json {"jsonrpc":"2.0","id":"shortlist-1","method":"SendMessage","params":{"message":{"messageId":"brief-1","role":"ROLE_USER","parts":[{"data":{"query":"a collaborative project planner","max_price":3000,"tld":"com","limit":5}}]}}} ``` Use one `data` part with `query` (2–200 characters) and optional `max_price` (positive whole USD), `tld`, `max_length`, `tier`, and `limit` (1–10; default 5). A single plain `text` part can describe a project. Put hard constraints in the structured fields: constraints embedded in prose return `clarification_required` without searching. Ambiguous numerical or suffix-like wording can also ask you to rephrase the description. Files, URLs, multiple briefs and unknown fields are refused. The response has `result.message`, with `ROLE_AGENT`, a server message ID, and your supplied `contextId` (or a new one). Its JSON part contains `status`, `priced_at`, `meaning`, `count`, `results` and `guidance`. A text part repeats published names, prices, descriptions and potential uses. `acceptedOutputModes` may select `application/json`, `text/plain`, or both. Results retain catalog ranking and all typed filters. Null prices mean offer-only; a price cap excludes them. Empty results ask you to revise the brief. Missing published descriptions remain empty. Potential uses do not establish suitability or trademark rights. Prices and availability can change; open the returned listing before deciding. The service cannot buy, reserve, register or transfer a name. Each selection uses one existing catalog search. The shared limits remain 30 requests per IP per minute and 120 searches globally per minute. Busy or unverified catalog responses are JSON-RPC errors, preserving HTTP status and `Retry-After`. Requests are limited to 16384 bytes, a 5-second body deadline and a 10-second work deadline. No streaming, push notifications or extended card is supported. `GetTask` and `CancelTask` return task-not-found; `ListTasks` is empty. Existing [HTTP and SDK](https://namegarage.com/docs/quickstart.md) and [MCP](https://namegarage.com/mcp/) clients remain anonymous and compatible. --- # 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`, `get_domain`, `get_purchase_options`, or `suggest_alternatives`. `get_domain` includes the published `description` and `use_cases`; do not invent missing or withheld copy. Potential uses are suggestions, not proof of suitability or trademark rights. Use `get_purchase_options` with a complete `name` to compare the current outright price with standard zero-down lease plans. Show monthly and final payments, total cost, and extra cost versus outright. Cash-only discounts may not apply to leases. Review other payment choices and any additional checkout fees on the returned domain page. 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. Poppy clients can read the [website-only discovery document](https://namegarage.com/.well-known/poppy.json) and [excluded tasks](https://namegarage.com/docs/poppy-excluded-tasks.json). This profile supports public browsing, with no Poppy sessions, account access, or transactions. The public APIs remain anonymous and operate independently of Poppy.