# Domain Availability API

> **For AI agents & automation.** This is a public, unauthenticated JSON endpoint.
> No API key, no CSRF token, no cookies — just a simple GET request.

Public endpoint for checking domain name availability on [pageforge.eu](https://pageforge.eu).

## Endpoint

```
GET /api/public/domain-check
```

## Query Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `domain`  | **Yes**  | Domain name or base keyword to check. Accepts a full domain (`example.com`) or just the base name (`example`). |
| `tlds`    | No       | Comma-separated list of TLDs to check. Defaults to `com,net,org,io,dev`. |

## Response

```json
{
  "success": true,
  "query": "example.com",
  "base": "example",
  "results": [
    {
      "domain": "example.com",
      "available": false,
      "price": 0,
      "renew_price": 0,
      "currency": "USD",
      "is_premium": false,
      "purchase_type": "registration"
    },
    {
      "domain": "example.net",
      "available": true,
      "price": 12.99,
      "renew_price": 12.99,
      "currency": "USD",
      "is_premium": false,
      "purchase_type": "registration"
    }
  ]
}
```

### Result Fields

| Field           | Type    | Description |
|-----------------|---------|-------------|
| `domain`        | string  | Fully qualified domain name. |
| `available`     | boolean | `true` if the domain can be registered. |
| `price`         | number  | Registration price in USD (0 if unavailable). |
| `renew_price`   | number  | Annual renewal price in USD. |
| `currency`      | string  | Always `"USD"`. |
| `is_premium`    | boolean | Whether this is a premium-priced domain. |
| `purchase_type` | string  | `"registration"` for standard domains. |

## Examples

### Check a specific domain

```bash
curl "https://pageforge.eu/api/public/domain-check?domain=mydreamsite.com"
```

### Check a base name across default TLDs

```bash
curl "https://pageforge.eu/api/public/domain-check?domain=mydreamsite"
```

### Check custom TLDs

```bash
curl "https://pageforge.eu/api/public/domain-check?domain=mydreamsite&tlds=com,ai,co,shop"
```

### Python

```python
import requests

resp = requests.get(
    "https://pageforge.eu/api/public/domain-check",
    params={"domain": "mydreamsite", "tlds": "com,net,io"},
)
data = resp.json()

for r in data["results"]:
    status = "AVAILABLE" if r["available"] else "taken"
    print(f"{r['domain']:30s} {status:10s} ${r['price']}")
```

### JavaScript (fetch)

```javascript
const res = await fetch(
  "https://pageforge.eu/api/public/domain-check?domain=mydreamsite&tlds=com,net,io"
);
const data = await res.json();

data.results.forEach((r) => {
  console.log(`${r.domain} — ${r.available ? "AVAILABLE" : "taken"} — $${r.price}`);
});
```

## Error Responses

| Status | Body | Reason |
|--------|------|--------|
| 400    | `{"success": false, "error": "Missing required query parameter: domain"}` | No `domain` param supplied. |
| 400    | `{"success": false, "error": "Invalid domain name"}` | Domain name is empty after sanitisation. |
| 502    | `{"success": false, "error": "Domain availability lookup failed"}` | Upstream registrar API error. |

## Notes

- Prices are in **USD** and reflect the registrar's base price.
- No authentication or CSRF token is needed — this is a fully public endpoint.
- Results are fetched in real-time from the registrar; response time is typically 1-3 seconds.