# AgentDomainService.com

> Domain availability checking designed for AI agents.

## Quick Start

Check a specific domain:
  GET https://agentdomainservice.com/lookup/example.com

The page returns structured data at the TOP of the HTML body for easy parsing.

## How to Parse the Response

### Option 1: Read the first 2 lines (fastest)

The first lines of the page body are:

```
VERDICT: AVAILABLE
FQDN=example.com | AVAILABLE=true | PRICE_USD=12.99 | PREMIUM=false | CHECKED_AT=2025-01-15T10:30:00Z | SOURCE=name.com
```

### Option 2: Extract JSON from `#ads-result` or `#ads-result-pre`

```html
<script type="application/json" id="ads-result">{"fqdn":"example.com","available":true,...}</script>
<pre id="ads-result-pre" style="display:none">{"fqdn":"example.com","available":true,...}</pre>
```

### Option 3: Use ?format=txt (ultimate failsafe)

```
GET /lookup/example.com?format=txt
```

Returns:
```
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
```

### Option 4: Use ?format=json

```
GET /lookup/example.com?format=json
```

Returns the canonical JSON object.

## Routes

| Route | Purpose |
|-------|---------|
| /lookup/{domain} | Check a single domain (e.g., /lookup/example.com) |
| /lookup/{domain}?format=txt | Plain text key=value (best for agents) |
| /lookup/{domain}?format=json | Pure JSON |
| /explore/{name} | Check a name across 8 TLDs (e.g., /explore/coolstartup) |
| /api/v1/domains/search | Find available domains with filters (see below) |
| /api/v1/domains/categories | List all categories with domain counts |
| /ideas | Browse curated domain ideas by category |
| /llms.txt | This file |

## Domain Search API (Recommended for Agents)

Find available domains filtered by category and price:

```
GET /api/v1/domains/search?category=ai-agent-tools&max_price=15
```

### Query Parameters

| Param | Description | Example |
|-------|-------------|---------|
| category | Filter by category slug | `ai-agent-tools` |
| max_price | Maximum price in USD | `15` (= $15 or less) |
| min_price | Minimum price in USD | `5` |
| tlds | Comma-separated TLDs | `com,io,dev` |
| sort | Sort order | `price_asc`, `price_desc`, `newest` |
| limit | Results (1-100, default 20) | `50` |

### Example Requests

Find cheap AI domains:
```
GET /api/v1/domains/search?category=ai-agent-tools&max_price=20&sort=price_asc
```

Find any .com under $15:
```
GET /api/v1/domains/search?tlds=com&max_price=15
```

Find premium startup domains:
```
GET /api/v1/domains/search?category=startup-ideas&min_price=50
```

### Response Format

```json
{
  "count": 15,
  "filters": {
    "category": "ai-agent-tools",
    "max_price": 20,
    "tlds": null,
    "sort": "price_asc"
  },
  "domains": [
    {
      "domain": "agentflow.dev",
      "name": "agentflow",
      "tld": "dev",
      "price": 12.99,
      "price_formatted": "$12.99",
      "premium": false,
      "categories": ["ai-agent-tools", "automation-tools"]
    }
  ]
}
```

### Available Categories

Get the full list with domain counts (categories are dynamic):
```
GET /api/v1/domains/categories
```

Returns all categories that have available domains, sorted by count.
Use this endpoint to discover valid category slugs for filtering.

## Canonical JSON Schema

```json
{
  "fqdn": "coolstartup.com",
  "available": false,
  "status": "registered",
  "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
  }
}
```

## Status Values

- `available` - Domain can be registered (`available=true`)
- `registered` - Domain is already taken (`available=false`)
- `unknown` - Could not determine (`available=false`)

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

## Suggestions

Add `?context={search terms}` to get relevant alternatives:

```
GET /lookup/stripe.com?context=payment+processing+api
```

Suggestions are also auto-included when the domain is taken.

## Tips for AI Agents

1. **Use /api/v1/domains/search for discovery** - find available domains by category and price
2. **Use /lookup/{domain}?format=txt for specific checks** - cleanest, most reliable
3. **Check `available` boolean** - true means you can register it
4. **Use max_price to stay in budget** - e.g., `?max_price=20` for under $20
5. **Results are cached** - reduces redundant lookups

## Recommended Workflows

### Finding domains in a budget (NEW - Recommended)

1. User wants a domain for their "AI agent startup" under $20
2. Search: `/api/v1/domains/search?category=ai-agent-tools&max_price=20`
3. Get list of available domains with pricing
4. Present options to user

### Checking a specific domain

1. User asks for a domain for their "AI writing assistant"
2. Check: `/lookup/aiwriter.com?format=txt`
3. If taken, add context: `/lookup/aiwriter.com?format=txt&context=AI+writing+assistant`
4. Parse suggestions from response
5. Present available options with pricing

### Exploring a name across TLDs

1. User likes the name "coolstartup"
2. Explore: `/explore/coolstartup` or `/api/v1/explore/coolstartup`
3. See availability across .com, .io, .dev, .ai, .app, .co, .net, .org

## Rate Limits

- No authentication required
- Reasonable use expected
- Server-side caching enabled

## Contact

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