Documentation sections
Developer platform
DomainListener Developer Platform
Build domain workflows with personal API keys, anonymous WHOIS lookup, public monitor status, and a remote MCP server.
Authentication
Use a scoped bearer key.
Create personal keys in Settings and select only the scopes an integration needs. Keys are shown once, so store them in a server-side environment variable. Public WHOIS and monitor-status endpoints do not require a key.
First request
Verify your key with a read.
Start with the credential-free, read-only sandbox to verify JSON parsing. Then create a free account, give a personal key domains:read, and list tracked domains. Successful v1 responses use a data envelope.
curl https://domainlistener.com/api/v1/sandboxcurl --request GET https://domainlistener.com/api/v1/domains \
--header "Authorization: Bearer $DOMAINLISTENER_API_KEY"Workspace API
Tenant-scoped v1 resources
The base URL is https://domainlistener.com/api/v1. All operations are bound to the API key's owner and scopes.
| Resource | Read | Write | Scopes |
|---|---|---|---|
| Domains | GET /api/v1/domains | POST /api/v1/domains | domains:read, domains:write |
| Domain groups | GET /api/v1/groups | POST /api/v1/groups | groups:read, groups:write |
| Monitors | GET /api/v1/monitors | POST /api/v1/monitors | monitors:read, monitors:write |
| Research queue | GET /api/v1/research-queue | POST /api/v1/research-queue | research-queue:read, research-queue:write |
curl --request POST https://domainlistener.com/api/v1/domains \
--header "Authorization: Bearer $DOMAINLISTENER_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"example.com"}'Public endpoints
Lookup and status, without an API key.
These endpoints are public by design. They expose no workspace management operations.
WHOIS lookup
Inspect a public registry record.
Pass one fully qualified domain name using the required domain parameter. The response includes availability, dates, registrar, nameservers, status values, and DNSSEC data.
curl "https://domainlistener.com/api/whois?domain=example.com"Rate limit: 10 requests per minute per IP by default. Inspect RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset.
400 invalid domain · 422 unavailable TLD data · 429 rate limit · 503 temporary service failure
Public monitor status
Read a monitor's public health data.
A monitor owner must enable public status and configure a slug. The response provides isUp, last check time, active incidents, uptime summaries, response-time series, and recent checks. Unknown or private slugs return 404.
curl "https://domainlistener.com/api/status/your-public-monitor-slug"Code examples
Use your service runtime.
const response = await fetch("https://domainlistener.com/api/v1/domains", {
headers: {
Authorization: `Bearer ${process.env.DOMAINLISTENER_API_KEY}`,
},
});
if (!response.ok) throw new Error(await response.text());
const { data } = await response.json();import os
import requests
response = requests.get(
"https://domainlistener.com/api/v1/domains",
headers={"Authorization": f"Bearer {os.environ['DOMAINLISTENER_API_KEY']}"},
timeout=15,
)
response.raise_for_status()
domains = response.json()["data"]MCP
Connect a remote MCP client.
Use the stateless Streamable HTTP server at https://www.domainlistener.com/api/mcp. MCP 2026-07-28 is recommended, with limited stateless POST compatibility for 2025-11-25 clients. Claude discovers OAuth automatically; authenticate in your client and approve the scopes it requests.
{
"mcpServers": {
"domainlistener": {
"type": "http",
"url": "https://www.domainlistener.com/api/mcp"
}
}
}Direct request
Send headers and a JSON-RPC body.
Mcp-Method must match the body's method. For tools/call, Mcp-Name must match params.name; it names the tool, not the DomainListener server.
curl --request POST "https://www.domainlistener.com/api/mcp" \
--header "Authorization: Bearer $DOMAINLISTENER_ACCESS_TOKEN" \
--header "MCP-Protocol-Version: 2026-07-28" \
--header "Mcp-Method: tools/call" \
--header "Mcp-Name: search_premium_domains" \
--header "Content-Type: application/json" \
--header "Accept: application/json,text/event-stream" \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_premium_domains",
"arguments": { "concept": "cloud", "page_size": 5 },
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}'Tool surface
Tools follow the granted scopes.
| Tool | Purpose | Access |
|---|---|---|
| search_premium_domains | Search active premium listings by concept and TLD. | Authenticated |
| get_premium_domain | Read one active premium listing and its canonical URL. | Authenticated |
| check_domain_availability | Check RDAP or WHOIS data with optional registrar pricing. | Authenticated |
| domains_list | List tracked domains in the current workspace. | domains:read |
| generate_domain_names | Generate domain ideas from a concept or saved search. | domains:read |
| valuate_domain | Run an AI-assisted domain valuation. | domains:read |
| check_trademark_conflicts | Run a non-authoritative trademark heuristic. | domains:read |
| groups_list | List domain groups. | groups:read |
| monitors_list | List uptime monitors. | monitors:read |
| research_queue_list | List research queue entries. | research-queue:read |
Parse error -32700: the POST body is empty or malformed JSON. Headers do not synthesize the JSON-RPC request. A header value that disagrees with the body returns a separate header-mismatch error.
Workspace lists use page and page_size. Name generation and valuation consume AI credits and require client confirmation. Public OAuth clients use PKCE, so desktop clients need no client secret. Personal API keys remain available for advanced automation, with reads limited to 120 requests per minute.