# RobotDomainSearch

> RobotDomainSearch is a domain availability API and toolkit for developers and AI agents. Check domain availability across 511 TLDs, get registration links, and look up ENS names programmatically.

RobotDomainSearch is designed for agent integration. All endpoints return JSON. No authentication required. Rate limited to 60 requests/minute per IP.

## Quick Start

Base URL: https://api.robotdomainsearch.com

Check domain availability:
```
GET https://api.robotdomainsearch.com/check?name=example&tld=com
```

Check multiple TLDs:
```
GET https://api.robotdomainsearch.com/check?name=example&tld=com,net,io,ai
```

Check by category:
```
GET https://api.robotdomainsearch.com/check?name=example&category=technology
```

Response (bulk):
```json
{
  "name": "example",
  "results": [
    {
      "domain": "example.com",
      "tld": "com",
      "available": false,
      "status": ["active"],
      "premium": false,
      "source": "rdap",
      "checkedAt": "2025-02-10T12:00:00Z",
      "responseMs": 180
    }
  ],
  "checked": 4,
  "available": 2,
  "unavailable": 1,
  "errors": 1,
  "totalMs": 250,
  "timestamp": "2025-02-10T12:00:00Z"
}
```

## API Documentation

- [API Overview](/docs/api/index.md): Complete API reference
- [Check Availability](/docs/api/availability.md): GET /check - Check domain availability (supports bulk TLD and category)
- [List TLDs](/docs/api/tlds.md): GET /tlds - List 511 supported TLDs across 15 categories
- [Register](/docs/api/register.md): GET /register - Get registration links
- [Health Check](/docs/api/health.md): GET /health - API status and version
- [Rate Limits](/docs/rate-limits.md): Usage limits and quotas
- [Error Codes](/docs/api/errors.md): Error response reference

## ENS API (Ethereum Name Service)

Separate service for .eth name lookups.

Base URL: https://ens.robotdomainsearch.com

- [ENS Availability](/docs/api/ens-availability.md): GET /check - Check ENS name availability + pricing
- [ENS Metadata](/docs/api/ens-metadata.md): GET /metadata - Get ENS metadata (address, avatar, social links)
- [ENS Health](/docs/api/ens-health.md): GET /health - ENS service health

## Aftermarket API

Check if a domain is listed for sale on aftermarket marketplaces (Sedo, Dynadot). Aggregates real-time data from multiple providers in parallel.

Base URL: https://api.robotdomainsearch.com

Endpoint:
```
GET https://api.robotdomainsearch.com/v1/aftermarket/{domain}
```

Parameters:
- `sources` (query, optional): Comma-separated list of sources (e.g., "sedo,dynadot")
- `timeout` (query, optional): Per-source timeout in ms (default 5000, max 15000)
- `currency` (query, optional): Preferred currency (default "USD")

Example request:
```
GET https://api.robotdomainsearch.com/v1/aftermarket/premium.com
```

Example response:
```json
{
  "domain": "premium.com",
  "listed": true,
  "summary": {
    "totalSources": 2,
    "sourcesChecked": 2,
    "listedCount": 2,
    "lowestPrice": { "amount": 2500.00, "currency": "USD", "source": "dynadot" }
  },
  "listings": [
    {
      "source": "sedo",
      "platform": "Sedo",
      "status": "listed",
      "saleType": "buyNow",
      "price": { "amount": 2700.00, "currency": "USD" },
      "url": "https://sedo.com/search/details/?domain=premium.com",
      "affiliateUrl": "https://sedo.com/search/details/?domain=premium.com&campaignId=330835"
    }
  ],
  "errors": [],
  "meta": { "totalMs": 455, "cacheHit": false, "cacheTTL": 900 }
}
```

Response fields:
- domain: queried domain (lowercased)
- listed: true if listed on any source
- summary: aggregated overview (totalSources, listedCount, lowestPrice, hasAuction, hasMakeOffer)
- listings[]: per-source listing details (source, platform, status, saleType, price, url, affiliateUrl)
- errors[]: per-source errors with code, message, retryable flag
- meta: totalMs, cacheHit, cacheTTL, affiliateDisclosure

Error codes: not_configured, timeout, rate_limited, auth_error, unavailable
HTTP status: 200 (success/partial), 400 (bad domain), 405 (wrong method), 501 (no sources), 503 (all failed)

Current sources: sedo, dynadot. Coming soon: afternic, dan.com, atom.com, squadhelp.

- [Aftermarket API Reference](/docs/api/aftermarket.md): Full endpoint documentation

## MCP Server

RobotDomainSearch provides an MCP server for AI agent integration:

```
npm install -g @robotdomainsearch/mcp
```

Tools: check_domain, bulk_check, list_tlds, get_registration_link

- [MCP Setup](/mcp/): Install and configure the RobotDomainSearch MCP server

## Endpoints (Main API)

| Endpoint | Method | Description |
|----------|--------|-------------|
| /check | GET | Check domain availability (params: name, tld, category) |
| /tlds | GET | List supported TLDs (params: type, category) |
| /register | GET | Get registration links (params: domain, registrar) |
| /v1/aftermarket/{domain} | GET | Check aftermarket listings (params: sources, timeout, currency) |
| /health | GET | API health check |

## Endpoints (ENS API)

| Endpoint | Method | Description |
|----------|--------|-------------|
| /check | GET | Check ENS name availability (params: name) |
| /metadata | GET | Get ENS metadata and records (params: name) |
| /health | GET | ENS service health |

## Supported TLDs

511 TLDs across 15 categories: top20, business, country, creative, education, finance, food, health, realestate, shopping, social, sports, technology, travel, web.

Top 20: com, net, org, io, ai, co, dev, app, xyz, me, tech, info, biz, online, site, store, cloud, shop, digital, world

## Supported Registrars

- Porkbun (slug: porkbun) - includes estimated pricing
- Namecheap (slug: namecheap)
- GoDaddy (slug: godaddy)

## Quick Reference

- Aftermarket: GET /v1/aftermarket/{domain} — check if listed for sale across marketplaces
- Main API Base URL: https://api.robotdomainsearch.com
- ENS API Base URL: https://ens.robotdomainsearch.com
- Auth: None required
- Format: JSON
- Rate Limit: 60/min per IP
- Max TLDs per request: 20

## Response Fields

/check returns:
- name: domain name checked
- results[]: array of check results
- results[].domain, tld, available, status[], premium, source, checkedAt, responseMs
- Bulk only: checked, available, unavailable, errors
- totalMs: total check time
- timestamp: response timestamp

/tlds returns:
- total: number of TLDs
- categories[]: array of {name, label, description, count, tlds[]}
- all[]: sorted list of all TLD strings (default response)
- tlds[]: array of {tld, type, rdapServer, categories[], enabled} (type filter)

/register returns:
- domain: requested domain
- registrars[]: array of {name, slug, url, estimatedPrice?}
- timestamp: response timestamp

ENS /check returns:
- name: full ENS name (with .eth)
- available: boolean
- owner, resolver: Ethereum addresses (if taken)
- registrationPrice: {wei, eth, usdEstimate} (if available)
- responseMs, source, checkedAt

ENS /metadata returns:
- name, owner, resolver, address
- records: {avatar, url, description, twitter, github, email, contenthash}
- responseMs, source, checkedAt

## OpenAPI Specification

Full OpenAPI 3.0 spec available at: https://robotdomainsearch.com/openapi.yaml