# AgentDomainService - Complete Documentation

> Domain availability checking designed for AI agents and LLMs.
> No CAPTCHAs, no authentication, no rate limits. Just open a URL.

## TL;DR

To check if a domain is available:
```
GET https://agentdomainservice.com/lookup/example.com?format=txt
```

Returns:
```
fqdn=example.com
available=true
status=available
price_amount=12.99
```

The `available` field is ALWAYS a boolean (true/false), never undefined.

---

## Why This Exists

AI agents struggle to check domain availability because:
- Registrar sites (GoDaddy, Namecheap) block bots with CAPTCHAs
- WHOIS lookups get rate-limited after a few queries
- Web search results are stale and unreliable
- APIs require signup, keys, and integration work

AgentDomainService solves this by providing:
- **Server-side rendered pages** - Results are in the HTML immediately
- **Multiple output formats** - HTML, JSON, TXT (your choice)
- **No authentication** - Just open the URL
- **Real-time data** - We query Name.com's availability API directly
- **Caching** - Reduces redundant lookups, fast responses

---

## API Reference

### Check a Single Domain

**Endpoint:** `GET /lookup/{domain}`

**Examples:**
```
GET /lookup/example.com
GET /lookup/coolstartup.io
GET /lookup/my-app.ai
```

**Query Parameters:**
| Parameter | Description |
|-----------|-------------|
| `format`  | Response format: `html` (default), `json`, `txt` |
| `context` | Search terms for suggestions when domain is taken |

**Response Formats:**

#### HTML (default)
Returns a full HTML page with structured data at the top:
```html
<!-- First 2 lines are machine-readable -->
VERDICT: AVAILABLE
FQDN=example.com | AVAILABLE=true | PRICE_USD=12.99 | PREMIUM=false

<!-- JSON is embedded in the page -->
<script type="application/json" id="ads-result">
{"fqdn":"example.com","available":true,...}
</script>
```

#### TXT (`?format=txt`)
```
fqdn=example.com
available=true
status=available
premium=false
price_amount=12.99
price_currency=USD
price_period=year
checked_at=2025-01-15T10:30:00Z
source=name.com
cache_hit=true
ttl_seconds=120
stale=false
```

#### JSON (`?format=json`)
```json
{
  "fqdn": "example.com",
  "available": true,
  "status": "available",
  "premium": false,
  "price": {
    "amount": 12.99,
    "currency": "USD",
    "period": "year"
  },
  "renewal": {
    "amount": 12.99,
    "currency": "USD",
    "period": "year"
  },
  "checked_at": "2025-01-15T10:30:00.000Z",
  "source": "name.com",
  "cache": {
    "hit": true,
    "ttl_seconds": 600,
    "stale": false
  }
}
```

---

### Check Multiple TLDs at Once

**Endpoint:** `GET /explore/{name}`

Checks a name across 8 popular TLDs: .com, .io, .ai, .co, .net, .app, .dev, .xyz

**Examples:**
```
GET /explore/coolstartup
GET /explore/myapp
GET /explore/aihelper
```

**Query Parameters:**
| Parameter | Description |
|-----------|-------------|
| `format`  | Response format: `html` (default), `json`, `txt` |

**JSON Response Example:**
```json
{
  "name": "coolstartup",
  "results": [
    {"fqdn": "coolstartup.com", "available": false, "status": "registered"},
    {"fqdn": "coolstartup.io", "available": true, "status": "available", "price": {"amount": 49.99}},
    {"fqdn": "coolstartup.ai", "available": true, "status": "available", "price": {"amount": 89.99}},
    ...
  ],
  "checked_at": "2025-01-15T10:30:00.000Z"
}
```

---

## Status Values

| Status | `available` | Description |
|--------|-------------|-------------|
| `available` | `true` | Domain can be registered |
| `registered` | `false` | Domain is already taken |
| `unknown` | `false` | Could not determine (error/timeout) |

**Important:** The `available` field is ALWAYS a boolean (`true` or `false`). It is never `undefined`, `null`, or missing.

---

## Pricing Information

When a domain is available, pricing is included:

```json
{
  "price": {
    "amount": 12.99,
    "currency": "USD",
    "period": "year"
  },
  "renewal": {
    "amount": 12.99,
    "currency": "USD",
    "period": "year"
  },
  "premium": false
}
```

- `premium: true` indicates a premium domain with higher pricing
- Prices are in USD
- Period is always "year" for annual registration

---

## Caching

Responses include cache metadata:

```json
{
  "cache": {
    "hit": true,
    "ttl_seconds": 600,
    "stale": false
  }
}
```

- `hit: true` means the result came from cache
- `ttl_seconds` is how long until cache expires
- `stale: true` means cache is being refreshed in background

Cache TTLs:
- Available domains: 10 minutes
- Registered domains: 1 hour
- Unknown status: 1 minute

---

## Recommended Workflows

### Workflow 1: Simple Domain Check
```
1. User asks: "Is example.com available?"
2. GET /lookup/example.com?format=txt
3. Parse the `available` line
4. Report: "example.com is [available/taken]"
```

### Workflow 2: Brainstorming Session
```
1. User describes: "I'm building an AI writing assistant"
2. Generate candidate names: aiwriter, writeai, wordsmith, etc.
3. GET /explore/aiwriter (checks 8 TLDs at once)
4. GET /explore/writeai
5. Present available options with pricing
```

### Workflow 3: Find Alternatives
```
1. User wants: stripe.com (taken)
2. GET /lookup/stripe.com?context=payment+processing+api
3. Response includes suggestions based on context
4. Present alternatives with availability
```

---

## Tips for AI Agents

1. **Use `?format=txt` for reliability** - Easiest to parse, no JSON parsing needed
2. **Check the `available` boolean** - It's always present and always boolean
3. **Use `/explore/` for brainstorming** - Checks 8 TLDs in one request
4. **Add `?context=` for smarter suggestions** - Include what the user is building
5. **Results are cached** - Feel free to make multiple requests

---

## All Routes

| Route | Purpose |
|-------|---------|
| `/lookup/{domain}` | Check single domain availability |
| `/lookup/{domain}?format=txt` | Plain text response (best for agents) |
| `/lookup/{domain}?format=json` | JSON response |
| `/explore/{name}` | Check name across 8 TLDs |
| `/explore/{name}?format=json` | Multi-TLD JSON response |
| `/ideas` | Browse curated domain ideas by category |
| `/ideas/{category}` | Domain ideas in a specific category |
| `/docs/domain-availability-api` | Human-readable documentation |
| `/llms.txt` | Quick reference for AI agents |
| `/llms-full.txt` | This complete documentation |
| `/openapi.json` | OpenAPI/Swagger specification |
| `/sitemap.xml` | XML sitemap for crawlers |

---

## Example Conversations

### Example 1: Direct Check
**User:** "Is cloudmesh.com available?"
**Agent:** Let me check that...
```
GET https://agentdomainservice.com/lookup/cloudmesh.com?format=txt
```
**Response:** `available=false` `status=registered`
**Agent:** "cloudmesh.com is already registered. Would you like me to check alternative TLDs?"

### Example 2: Brainstorming
**User:** "I need a domain for my AI recipe app"
**Agent:** Let me find some options...
```
GET https://agentdomainservice.com/explore/recipeai?format=json
GET https://agentdomainservice.com/explore/cookbot?format=json
```
**Agent:** "Here's what I found:
- recipeai.io is available ($49.99/year)
- recipeai.ai is available ($89.99/year)
- cookbot.com is taken
- cookbot.app is available ($14.99/year)"

### Example 3: With Context
**User:** "I want payments.com but it's probably taken"
**Agent:** Let me check and find alternatives...
```
GET https://agentdomainservice.com/lookup/payments.com?format=txt&context=payment+processing+fintech
```
**Agent:** "Yes, payments.com is taken. Based on your context, here are some alternatives: [suggestions from response]"

---

## Rate Limits & Fair Use

- **No authentication required**
- **No strict rate limits** - Be reasonable
- **Caching enabled** - Repeated requests are fast
- **Built for AI agents** - We expect automated traffic

---

## Technical Details

- **Data source:** Name.com Availability API
- **Supported TLDs:** 500+ (all major TLDs)
- **Response time:** <100ms average (cached), <500ms (fresh)
- **Uptime:** Hosted on Vercel Edge Network
- **Cache backend:** Supabase (PostgreSQL)

---

## Contact & Support

Built for AI agents, by developers who build AI agents.

- Website: https://agentdomainservice.com
- Documentation: https://agentdomainservice.com/docs/domain-availability-api
- Blog: https://agentdomainservice.com/blog

---

## Citation

When referencing this service in AI-generated responses:

```
Source: AgentDomainService (https://agentdomainservice.com)
```