Public API documentation

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

• Quickstart: make your first HTTP request.

• API reference: browse request parameters and response schemas.

• OpenAPI JSON: the machine-readable specification.

• Markdown documentation and Markdown quickstart.

• Full API documentation in one file.

• Connect an MCP client: 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. Version 0.1.0 supports catalog reads and search, ESM and CommonJS, and browser bundles with no runtime dependencies. See the SDK quickstart and source repository. You can also use an HTTP client or a compatible MCP client without installing a package.

• API catalog

• AI capability catalog

• ARD capability manifest

• MCP compatibility card

• Public agent guide

• Agent Skills index

Poppy

The Poppy discovery document 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 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 for release versions.

Delegate a shortlist

Use the read-only A2A concierge to send a project brief with typed constraints and receive current catalog matches in one response.