# Domain Lookup: full reference

> Domain Lookup (https://domainlookup.dev) is a free domain research service by Beta Limited. It checks domain availability straight from the registry, suggests names across TLDs, and returns WHOIS/RDAP registration data, domain age, DNS records and SSL certificates. It is one service with three front doors: a web app, a public JSON HTTP API and a remote MCP server for AI assistants. There is no paid plan. The HTTP API and MCP tool calls require a free API key (instant, no account, no password, email optional); the search box on the website works without one. Fair-use rate limits apply.

Contents: Overview · Data sources · MCP setup · MCP tools · HTTP API · API keys · Limits · Errors

## Overview

- Web app: https://domainlookup.dev/ (search a domain like `example.com`, or a bare name like `acme` to check it across TLDs; results are linkable as `/?q=<query>`).
- HTTP API base URL: https://domainlookup.dev/api
- MCP endpoint: https://domainlookup.dev/mcp (Streamable HTTP, stateless JSON-RPC 2.0 over POST).
- Authentication: a free API key is required for `/api/*` lookups and MCP `tools/call`. Send it as `Authorization: Bearer dlk_...`, `X-Api-Key: dlk_...`, or `?key=dlk_...` in the URL (for MCP connectors that cannot send headers). Get one at https://domainlookup.dev/#api-key or with `POST /api/keys`.
- The website's own search box works without a key (30 searches per minute per IP).
- All data is fetched live at request time.

## Data sources

How an availability check works:

1. The input is normalized (URLs, Unicode/IDN and subdomains are accepted) and reduced to its registrable domain with the Public Suffix List, ICANN section (`shop.example.co.uk` → `example.co.uk`). Names under TLDs that do not exist are rejected with HTTP 400.
2. The registry's RDAP server is looked up in the IANA RDAP bootstrap file (https://data.iana.org/rdap/dns.json) and asked directly. A record means registered; no record means the registry has no registration.
3. For TLDs without RDAP, or when RDAP fails, the registry's own port-43 WHOIS server is asked instead.
4. DNS (Cloudflare DNS-over-HTTPS) is the cross-check. A DNS delegation proves the name is registered (or registry-reserved). DNS alone never proves a name is free.

Accuracy guarantee: Domain Lookup never answers `available` without an authoritative answer from the registry (RDAP or WHOIS). If the registry does not answer and DNS shows no delegation, the status is `unknown`. Every answer carries `source`. Premium or registry-reserved names can have no registration record and still be refused at checkout; the registrar has the final word on price and eligibility.

Other data:

- Registration data (WHOIS): parsed from registry RDAP JSON (RFC 9083), or from port-43 WHOIS text for registries without RDAP (fewer fields: registrar, dates, status, nameservers). Most registries redact registrant details.
- DNS records: Cloudflare DNS-over-HTTPS.
- SSL certificates: crt.sh (Certificate Transparency log search). It can take several seconds and sometimes times out.

## MCP setup

Server URL: https://domainlookup.dev/mcp. `initialize` and `tools/list` work without a key so clients can connect; `tools/call` needs a free API key and otherwise returns a tool error pointing to https://domainlookup.dev/#api-key. Replace `dlk_your_key` below with your key.

### Claude Code

```
claude mcp add --transport http domainlookup https://domainlookup.dev/mcp --header "Authorization: Bearer dlk_your_key"
```

### Claude Desktop and claude.ai

Settings → Connectors → Add custom connector. Custom connectors cannot send headers, so put the key in the URL:

```
https://domainlookup.dev/mcp?key=dlk_your_key
```

### ChatGPT

Add a custom MCP connector (available with developer mode) with no authentication and this URL:

```
https://domainlookup.dev/mcp?key=dlk_your_key
```

### Cursor

`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "domainlookup": {
      "url": "https://domainlookup.dev/mcp",
      "headers": { "Authorization": "Bearer dlk_your_key" }
    }
  }
}
```

### Codex

Codex reads the key from an environment variable:

```
export DOMAINLOOKUP_API_KEY="dlk_your_key"
```

`~/.codex/config.toml`:

```toml
[mcp_servers.domainlookup]
url = "https://domainlookup.dev/mcp"
bearer_token_env_var = "DOMAINLOOKUP_API_KEY"
```

### VS Code

`.vscode/mcp.json`:

```json
{
  "servers": {
    "domainlookup": {
      "type": "http",
      "url": "https://domainlookup.dev/mcp",
      "headers": { "Authorization": "Bearer dlk_your_key" }
    }
  }
}
```

### Other clients (raw HTTP)

Any client that speaks MCP over Streamable HTTP works. The server is stateless: every request is a JSON-RPC POST, `GET /mcp` answers 405.

```
curl -s https://domainlookup.dev/mcp \
  -H "Authorization: Bearer dlk_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_domain_availability","arguments":{"domain":"example.com"}}}'
```

Supported methods: `initialize`, `ping`, `tools/list`, `tools/call`. JSON-RPC batches are not supported (one request per POST). Tool results are returned as one text content item containing the JSON object described under HTTP API.

## MCP tools

All seven tools are read-only (`readOnlyHint: true`) and query public, third-party data (`openWorldHint: true`).

| Tool | Arguments | Returns |
| --- | --- | --- |
| `check_domain_availability` | `domain` (string, required) | Availability |
| `bulk_check_availability` | `domains` (string[], required, max 10) | Availability[] |
| `suggest_domains` | `name` (string, required; a full domain uses its first label), `tlds` (string[], optional, max 10) | Availability[] |
| `whois_lookup` | `domain` (string, required) | Whois |
| `domain_age` | `domain` (string, required) | `{domain, registered, days, years, expiresInDays, expires}` |
| `dns_lookup` | `domain` (string, required), `record_type` (one of A, AAAA, CNAME, MX, NS, TXT, SOA, CAA; optional, default all) | DnsResult |
| `ssl_certificates` | `domain` (string, required), `limit` (number, optional, default 20, max 100) | CertificatesResult |

Example prompts: "Is facebook.dev available?", "Which TLDs are free for 'netflix'?", "When does example.com expire?", "Show the MX records of example.com", "Which subdomains appear in example.com's certificates?"

## HTTP API

Base URL: https://domainlookup.dev. Every response is JSON with `"ok": true` plus the fields below, or `{"ok": false, "error": "..."}`. CORS is allowed from any origin. Every lookup route requires an API key (see API keys); the examples below use `dlk_your_key`.

### GET /api/availability?domain={domain}

Is a domain available to register?

```
curl "https://domainlookup.dev/api/availability?domain=example.com" \
  -H "Authorization: Bearer dlk_your_key"
```

```json
{ "ok": true, "domain": "example.com", "status": "registered", "available": false, "source": "rdap" }
```

```json
{
  "ok": true,
  "domain": "facebook.com",
  "status": "registered",
  "available": false,
  "source": "rdap"
}
```

Availability fields:

- `domain`: the registrable domain that was checked.
- `status`: `available` | `registered` | `unknown`.
- `available`: `true`, `false`, or `null` when unknown.
- `source`: `rdap` | `whois` | `dns` | `null`. `available` only ever comes with `rdap` or `whois`.
- `note` (optional): explanation, e.g. subdomain reduction, DNS cross-check result, or why the answer is unknown.

### POST /api/availability/bulk

Body: `{"domains": ["a.com", "b.io"]}` with at most 10 domains. A bad entry is reported on its own row (status `unknown` with a `note`) instead of failing the batch.

```
curl -X POST "https://domainlookup.dev/api/availability/bulk" \
  -H "Authorization: Bearer dlk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["facebook.com", "netflix.io"]}'
```

```json
{ "ok": true, "results": [ { "domain": "facebook.com", "status": "registered", "available": false, "source": "rdap" }, { "domain": "netflix.io", "status": "registered", "available": false, "source": "whois" } ] }
```

(Values in examples are illustrative.)

### GET /api/suggest?name={name}&tlds={comma-separated}

Checks one name across TLDs. Default TLDs: com, net, org, io, co, ai, dev, app, xyz, me. At most 10 TLDs per call.

```
curl "https://domainlookup.dev/api/suggest?name=netflix&tlds=com,io,dev,ai" \
  -H "Authorization: Bearer dlk_your_key"
```

Response: `{"ok": true, "results": Availability[]}`.

### GET /api/whois?domain={domain}

Registration data from the registry.

```
curl "https://domainlookup.dev/api/whois?domain=example.com" \
  -H "Authorization: Bearer dlk_your_key"
```

```json
{
  "ok": true,
  "domain": "example.com",
  "source": "rdap",
  "rdapServer": "rdap.verisign.com",
  "handle": "2336799_DOMAIN_COM-VRSN",
  "status": ["client delete prohibited", "client transfer prohibited", "client update prohibited"],
  "registered": "1995-08-14T04:00:00Z",
  "expires": "2026-08-13T04:00:00Z",
  "lastChanged": "2025-08-14T07:01:39Z",
  "registrar": { "name": "RESERVED-Internet Assigned Numbers Authority", "ianaId": "376", "url": null, "abuseEmail": null, "abusePhone": null },
  "registrant": null,
  "nameservers": ["a.iana-servers.net", "b.iana-servers.net"],
  "dnssec": true,
  "age": { "registered": "1995-08-14T04:00:00Z", "days": 11363, "years": 31.1, "expiresInDays": 324 }
}
```

(Values are illustrative.) Fields: `source` is `rdap` or `whois` (port-43 WHOIS records have fewer fields); `rdapServer` is the host of the registry server that answered; dates are ISO 8601 or `null`; `registrant` is usually `null` because registries redact it. A domain with no registration returns HTTP 502 with an error saying it is not registered.

### GET /api/dns?domain={domain}&type={type}

DNS records via Cloudflare DNS-over-HTTPS. `type` is one of A, AAAA, CNAME, MX, NS, TXT, SOA, CAA; omit it for all types.

```
curl "https://domainlookup.dev/api/dns?domain=example.com&type=MX" \
  -H "Authorization: Bearer dlk_your_key"
```

```json
{ "ok": true, "domain": "example.com", "status": "NOERROR", "records": { "MX": [ { "name": "example.com", "type": "MX", "ttl": 3600, "data": "0 ." } ] } }
```

`status` is the DNS RCODE name (NOERROR, NXDOMAIN, SERVFAIL, ...). `records` maps each requested type to a list of `{name, type, ttl, data}`.

### GET /api/certificates?domain={domain}&limit={n}

Certificates from Certificate Transparency logs (crt.sh), newest first, plus every hostname seen on them. `limit` defaults to 20, max 100. crt.sh can be slow.

```
curl "https://domainlookup.dev/api/certificates?domain=example.com&limit=10" \
  -H "Authorization: Bearer dlk_your_key"
```

```json
{
  "ok": true,
  "domain": "example.com",
  "total": 42,
  "certificates": [
    { "id": 1234567890, "issuer": "DigiCert Inc", "commonName": "www.example.com", "names": ["example.com", "www.example.com"], "notBefore": "2026-01-15T00:00:00Z", "notAfter": "2027-01-15T23:59:59Z", "serial": "0a1b2c...", "expired": false }
  ],
  "hostnames": ["example.com", "www.example.com"]
}
```

(Values are illustrative.)

### POST /api/keys

Creates a free API key. No key is needed for this call. Body: `{}` or `{"email": "you@example.com"}`; the email is optional and only used to reach you about the service.

```
curl -X POST "https://domainlookup.dev/api/keys" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json
{ "ok": true, "key": "dlk_...", "prefix": "dlk_ab12", "createdAt": "2026-09-23T12:00:00Z", "perMinute": 300 }
```

The full key is returned once. Only a SHA-256 hash is stored, so it cannot be shown again; keep a copy (the website also saves it in your browser). Errors: `{"ok": false, "error": "..."}` with HTTP 400 (invalid input) or 429 (too many keys from this IP).

### POST /mcp

MCP JSON-RPC endpoint; see MCP setup and MCP tools.

## API keys

- Required for `/api/*` lookups and MCP `tools/call`. Free and instant: no account, no password.
- Keys look like `dlk_` followed by 32 characters.
- Send one as `Authorization: Bearer dlk_...`, `X-Api-Key: dlk_...`, or `?key=dlk_...` (for MCP connectors such as Claude and ChatGPT custom connectors that cannot send headers).
- Create one in the web app (https://domainlookup.dev/#api-key) or with `POST /api/keys`.
- Without a valid key the API answers HTTP 401: `{"ok": false, "error": "API key required. Get a free key at https://domainlookup.dev/#api-key", "code": "key_required"}`.

## Limits

Domain Lookup is free. Fair-use rate limits apply:

- With an API key: 300 requests per minute per key (HTTP API and MCP).
- Website search box without a key: 30 searches per minute per IP address.
- API key creation: 5 keys per IP address per day.
- Bulk and suggest calls: at most 10 domains per call.

Over a limit the API answers HTTP 429 with `Retry-After: 60`.

## Errors

- 400: invalid input (bad domain, unknown TLD, missing parameter, too many domains).
- 401: missing or invalid API key (`"code": "key_required"` when missing).
- 429: rate limited; wait for `Retry-After` seconds.
- 502: an upstream source failed or has no record (e.g. WHOIS for an unregistered name, crt.sh timeout).
- 500: internal error.

## About

Domain Lookup is built and run by Beta Limited. Contact and support: support@beta.limited (lost keys, revoking a key, bugs, higher limits). © 2026 Beta Limited.