API Documentation

Integrate AI-powered domain search into your applications with our REST API.

Quick Start

1. Get your API key from the API Keys dashboard

2. Make requests to our API endpoints using your API key

Example Request

curl -X POST https://www.domainfindr.app/api/v1/domains/search \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query": "my startup name"}'

Authentication

All API requests require authentication using your API key. Include it in the request header:

Authorization Header

Authorization: Bearer dfk_your_api_key_here

Alternatively, you can use the X-API-Key header:

X-API-Key Header

X-API-Key: dfk_your_api_key_here

Rate Limits

Plan	Requests/Month	Requests/Minute	API Keys
Free	100	10	2
Pro	1,000	60	10

Rate limit information is included in response headers:

Rate Limit Headers

X-RateLimit-Remaining: 59
X-RateLimit-Limit: 60
X-RateLimit-Reset: 1699123456789
X-Usage-Used: 150
X-Usage-Limit: 1000

Endpoints

POST/api/v1/domains/search

Search for available domain names based on a brand name or project description. Uses AI to generate creative variations and checks availability in real-time.

Request Body

{
  "query": "string (required)",      // Brand name or project description
  "preferences": {                   // Optional preferences
    "domainStyle": "short" | "descriptive" | "brandable" | "all",
    "extensions": "startup" | "traditional" | "tech" | "all"
  }
}

Response

{
  "success": true,
  "data": {
    "query": "my startup",
    "domains": [
      {
        "domain": "mystartup.io",
        "available": true,
        "price": 39,
        "currency": "USD"
      },
      {
        "domain": "getmystartup.com",
        "available": true,
        "price": 12,
        "currency": "USD"
      }
    ],
    "totalFound": 15,
    "summary": "Top Picks\n  ✓ mystartup.io ($39/yr)\n..."
  }
}

Example

curl -X POST https://www.domainfindr.app/api/v1/domains/search \
  -H "Authorization: Bearer dfk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cloud storage app",
    "preferences": {
      "domainStyle": "brandable",
      "extensions": "startup"
    }
  }'

GET/api/v1/keys/me

Get information about the currently used API key including usage limits and statistics.

Response

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "clx...",
      "name": "My Application",
      "keyPrefix": "dfk_abc1...",
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsedAt": "2024-01-20T14:22:00Z"
    },
    "plan": "pro",
    "limits": {
      "requestsPerMonth": 1000,
      "requestsPerMinute": 60
    },
    "usage": {
      "monthly": {
        "used": 150,
        "limit": 1000,
        "remaining": 850,
        "resetDate": "2024-02-01T00:00:00Z"
      }
    },
    "stats": {
      "totalRequests": 1250,
      "successfulRequests": 1230,
      "failedRequests": 20,
      "avgResponseTime": 2500,
      "last24Hours": 45,
      "last7Days": 320,
      "last30Days": 1250
    }
  }
}

Error Handling

All errors return a consistent JSON structure:

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}

Error Codes

HTTP Status	Code	Description
400	BAD_REQUEST	Invalid request body or parameters
401	UNAUTHORIZED	Missing or invalid API key
429	RATE_LIMITED	Rate limit or quota exceeded
500	INTERNAL_ERROR	Server error
504	TIMEOUT	Search timed out

Code Examples

JavaScript / TypeScript

const response = await fetch('https://www.domainfindr.app/api/v1/domains/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'my startup name',
    preferences: {
      domainStyle: 'brandable',
      extensions: 'startup',
    },
  }),
});

const data = await response.json();
console.log(data.data.domains);

Python

import requests

response = requests.post(
    'https://www.domainfindr.app/api/v1/domains/search',
    headers={
        'Authorization': 'Bearer <YOUR_API_KEY>',
        'Content-Type': 'application/json',
    },
    json={
        'query': 'my startup name',
        'preferences': {
            'domainStyle': 'brandable',
            'extensions': 'startup',
        },
    },
)

data = response.json()
print(data['data']['domains'])

Need Help?

Have questions about the API or need assistance? We're here to help.

Contact Support Manage API Keys