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