---
title: "Name.ai API Docs — REST Endpoints and OpenAPI 3.1 Spec"
description: "Name.ai API documentation: the public REST endpoints for domain search and availability, WHOIS lookup, TLD registration pricing and requirements, and marketplace listings. OpenAPI 3.1 spec at name.ai/openapi.json. No API key required."
url: https://name.ai/developers/api
---

[Name.ai developer portal](https://name.ai/developers) / API

# Name.ai API docs

The Name.ai API is a public REST surface for domain search and availability, WHOIS lookup, TLD registration pricing and requirements, and marketplace listings. Every endpoint below works without an account or an API key. The machine-readable contract is an OpenAPI 3.1 document at [name.ai/openapi.json](https://name.ai/openapi.json).

## Endpoints

| Method | Path | What it returns |
| --- | --- | --- |
| POST | /api/domain/search | Check whether a domain is available, with alternate-TLD siblings for the same label. |
| POST | /api/tools/whois | WHOIS/RDAP registration details: registrar, registrant, dates, nameservers. |
| GET | /api/pricing/tld | Current USD price to register, renew, transfer or restore on a given TLD. |
| GET | /api/tlds/{tld}/metadata | Registration requirements for a TLD: term range, organization and nameserver rules. |
| GET | /api/market/listings | Browse aftermarket listings. Follow page.next\_cursor, or page by offset. |
| POST | /api/batch | Up to 20 of the reads above in one request. GET the same path for the catalogue. |
| POST | /api/domains/bulk/{op} | Apply one operation to up to 1,000 domains you own (signed-in). |

## Calling the Name.ai API

One request, no setup:

```
curl -s https://name.ai/api/pricing/tld?tld=ai

curl -s -X POST https://name.ai/api/domain/search \
  -H 'Content-Type: application/json' \
  -d '{"q":"example.ai"}'

# Several lookups, one round trip
curl -s -X POST https://name.ai/api/batch \
  -H 'Content-Type: application/json' \
  -d '{"operations":[
        {"id":"a","op":"search_domain","params":{"q":"acme.ai"}},
        {"id":"b","op":"tld_registration_price","params":{"tld":"ai","op":"register"}},
        {"id":"c","op":"whois_lookup","params":{"domain":"example.com"}}
      ]}'
```

## Conventions

-   **Versioning.** The unauthenticated endpoints are additive-only: fields get added, never removed or renamed, without a new path. Keyed partner endpoints are path-versioned under `/api/v1/`.
-   **Deprecations.** Announced with RFC 9745 `Deprecation` and RFC 8594 `Sunset` headers at least 90 days ahead.
-   **Rate limits.** Every public endpoint returns IETF `RateLimit-*` headers; a 429 carries `Retry-After`.
-   **Retries.** Send an `Idempotency-Key` header on POST.
-   **Errors.** One typed shape across the whole surface — see `components.schemas.Error` in the spec.
-   **Pagination.** Every list returns a `page` object. Follow `page.next_cursor` until it is null — a cursor names the row you stopped at, so a listing added or sold while you page cannot shift the window under you. Offset (`limit`, `offset`, `total`) still works, and `next_cursor` comes back on offset pages too, so you can switch mid-walk. A cursor is only valid for the filters and sort it was issued with; reusing it elsewhere is a `400 invalid_cursor`, never a quietly wrong page.
-   **Batching.** Pricing twelve extensions or checking forty names is one `POST /api/batch`, not forty round trips. Each operation is dispatched to the same handler its single-call equivalent uses and counted the same against the rate limit; one bad entry returns its own 400 without costing you the rest.

## Name.ai SDKs

Official, zero-dependency clients for the endpoints above. Both cover cursor paging and batching, and both work with no account.

```
npm install nameai-sdk     # JavaScript / TypeScript, Node >= 18
pip install nameai         # Python >= 3.9
```

```
import NameAI from 'nameai-sdk';

const nameai = new NameAI();
const { priceCents } = await nameai.tldPrice('ai', 'register');
for await (const listing of nameai.listAllListings({ tld: 'ai' })) {
  console.log(listing.domain);
}
```

Source for both: [github.com/namekart/nameai\_mcp](https://github.com/namekart/nameai_mcp) (`sdk/` and `sdk-python/`). They are hand-written rather than generated: six read endpoints do not need a generated transport layer, and a thin client is easier to read than the spec it came from.

## Related Name.ai developer resources

-   [OpenAPI 3.1 spec](https://name.ai/openapi.json) — the machine-readable contract for everything above.
-   [Name.ai MCP server](https://name.ai/developers/mcp) — the same capabilities as MCP tools, for agents.
-   [Name.ai API authentication](https://name.ai/developers/auth) — optional OAuth 2.1, unlocks real marketplace prices.
-   [/api/llms.txt](https://name.ai/api/llms.txt) — this page, scoped for an agent that wants only the API surface.

Name.ai API Docs — REST Endpoints and OpenAPI 3.1 Spec

---

Markdown representation of https://name.ai/developers/api. The same URL returns HTML to any client that asks for `text/html`. Site map for agents: https://name.ai/llms.txt