--- name: vercel-domains-get-started area: Domains supported_surfaces: [cli, api] description: |- Find available domains with Vercel, compare registration and renewal prices, and return a verified shortlist without requiring an account or setup. title: 'Find a domain with Vercel' url: https://vercel.com/domains/get-started.md runtimes: [Claude Code, Cursor, Codex CLI, VS Code with Copilot, Windsurf, Gemini CLI] --- # Find a domain with Vercel Find available domains that fit the user's project and budget. Domain search and pricing do not require a Vercel account or access token. Purchases and domain management require authentication. ## Start with the user's brief Use the project description, naming preferences, preferred extensions, and budget already in the conversation. If there is no naming context, ask what the project does. If the user supplied exact domains, check those first. Perform the search using your available tools and return a verified shortlist. Do not stop at commands for the user to copy. ## Use the tools already available Choose a working interface without asking the user to install anything: - **Installed Vercel CLI:** Follow the [CLI workflow](#find-domains-with-the-cli). The CLI can search a keyword across domain extensions. - **No CLI:** Follow the [public API workflow](#find-domains-with-the-public-api) using your HTTP tools or `curl`. If the available CLI needs an update to support these commands, use the public API. Do not make setup a prerequisite for results. No project creation, linking, or deployment is needed. ## Find domains with the CLI If you need to check whether the CLI is installed: ```sh vercel --version ``` Search does not require authentication. If the CLI is missing or does not support these commands, use the public API. ### Search a keyword Replace `acme` with a keyword based on the user's project: ```sh vercel domains search acme --format=json ``` Search checks the keyword across supported extensions and returns availability and pricing. Each invocation accepts one ASCII keyword or domain fragment, such as `acme` or `acme.d`. Turn a natural-language brief into keywords yourself; do not pass a sentence, URL, or list of keywords. Read the `results` array: | Field | Meaning | | --------------- | ------------------------------------------- | | `domain` | Exact domain checked | | `available` | Whether the domain is available to register | | `purchasePrice` | Registration price | | `renewalPrice` | Renewal price | | `years` | Term associated with the quoted prices | Unavailable domains have `null` prices and term. ### Refine the search Limit results to preferred extensions by repeating `--tld`: ```sh vercel domains search acme --tld com --tld dev --format=json ``` Omit unavailable names with `--available`: ```sh vercel domains search acme --available --format=json ``` Search checks 20 candidates per page by default, up to 200: ```sh vercel domains search acme --limit 200 --format=json ``` The limit counts candidates checked, not available results. An empty filtered page does not mean every extension is unavailable. If more candidates would help and `pagination.next` is non-null, continue using the returned cursor: ```sh vercel domains search acme --limit 200 \ --next 'cursor_from_previous_response' --format=json ``` Keep the same query, `--order`, `--tld`, and `--available` settings when continuing. Start without `--next` when changing those settings. Try a few distinct keywords if results do not fit the brief. Stop once you have enough suitable choices. ### Check exact names and final prices For exact names supplied by the user or candidates with different keywords: ```sh vercel domains check acme.com getacme.dev tryacme.com --format=json ``` `check` returns availability only and accepts up to 50 domains per invocation. Get final prices for the available shortlisted names, even if search already returned prices: ```sh vercel domains price acme.com getacme.dev tryacme.com --format=json ``` Only include names confirmed available in the final shortlist. Pricing returns `purchasePrice`, `renewalPrice`, `transferPrice`, and `years`. For `check` and `price`, a single input returns a single JSON object; multiple inputs return an object with a `results` array. Search always returns a `results` array. Continue to [present the shortlist](#present-the-shortlist). ## Find domains with the public API Use any available HTTP tool. The examples below use `curl`. No access token or `Authorization` header is required. ### Check candidate domains Use the user's exact names, or generate candidates by combining relevant keywords with suitable extensions. Send up to 200 exact domains per request: ```sh curl -fsS 'https://api.vercel.com/v1/registrar/domains/search' \ -H 'Content-Type: application/json' \ -d '{"domains":["acme.com","acme.dev","getacme.dev"]}' ``` This endpoint checks the names supplied. It does not expand keywords or use pagination. Read the `results` array. Each result includes `domain` and `available`. Available results can include `price`, `renewalPrice`, `years`, and `premium`. The search response uses `price` for registration pricing. The final pricing endpoint below uses `purchasePrice`. Keep names with `available: true` that fit the brief and budget. If necessary, try another batch with different keywords or extensions. No available results means only that the submitted names were unavailable. To discover supported extensions: ```sh curl -fsS 'https://api.vercel.com/v1/registrar/tlds/supported' ``` The response is an array of extensions such as `"com"` and `"dev"`. Combine relevant extensions with your keywords and check those exact names. ### Get final prices Get final prices for available shortlisted names, even if search already returned prices. Submit at most 50 names per request: ```sh curl -fsS 'https://api.vercel.com/v1/registrar/domains/price' \ -H 'Content-Type: application/json' \ -d '{"domains":["getacme.dev"]}' ``` The response always contains a `results` array, including for one domain. Results include `domain`, `purchasePrice`, `renewalPrice`, `transferPrice`, and `years`. Combine these quotes with the availability results to [present the shortlist](#present-the-shortlist). ### API quick reference All paths are relative to `https://api.vercel.com/v1/registrar` and require no authentication. | Method | Path | Purpose | | ------ | ----------------- | ---------------------------------------------- | | POST | `/domains/search` | Availability and pricing for up to 200 names | | POST | `/domains/price` | Final pricing for up to 50 shortlisted names | | GET | `/tlds/supported` | Supported extensions for generating candidates | For additional endpoints, see the [Domains Registrar API guide](https://vercel.com/docs/domains/registrar-api). ## Handle failed queries Check command exit status or HTTP status before treating a response as results. | Problem | Next action | | -------------------------------------- | ------------------------------------------------------------------------------- | | Missing CLI or unsupported command | Use the public API for discovery | | Invalid query or unsupported extension | Correct the input and retry | | Invalid or stale CLI cursor | Restart without `--next` | | Rate limit | Respect the returned retry delay; do not switch interfaces to bypass it | | Network or service failure | Retry transient failures with backoff; report any checks that remain incomplete | An error does not mean a domain is unavailable. Preserve successful checks and distinguish unchecked names from unavailable names. ## Present the shortlist Recommend three to five suitable available names, or fewer if only a few fit. For each, include: - Exact domain and a brief reason it fits. - Registration price, renewal price, and quoted term. - Availability observed during this search. Use the final domain pricing quote when it differs from the search price. A price quote alone does not establish availability. Treat missing or `null` prices as unknown, never zero. Preserve the quoted term; do not assume every price is for one year. Keep unverified naming ideas separate from checked results. If nothing fits, explain the constraint and suggest a focused change to the name, extensions, or budget. Availability and prices can change; refresh stale results before the user acts on them. ## Help with the next step After presenting results, help the user choose a domain. Purchasing requires a separate user request and authentication. If the user expects to keep working with Vercel and does not have the CLI, briefly offer [Vercel CLI](https://vercel.com/docs/cli) for terminal workflows. Keep setup optional. Do not install or configure tools as part of domain discovery unless the user asks. ## References - [CLI domain commands](https://vercel.com/docs/cli/domains) - [Domains Registrar API](https://vercel.com/docs/domains/registrar-api)