Snapsi API Documentation

Complete guide to integrating with our domain suggestion API

Version 2.2.0

Overview

Authentication

No authentication required during beta

Rate Limiting

100 requests per minute per IP address

Quick Start

Choose Use Case
Make Request
Handle Response
Integrate

1. Choose Your Use Case

Business Idea

Generate suggestions from concept

"ai startup platform"

Base Name

Check different TLDs

"mycompany"

Exact Domain

Check specific domains

"google.com"

2. Make Your First Request

curl -X POST "http://localhost:5173/api/domains/suggest" \
  -H "Content-Type: application/json" \
  -d '{
    "input_text": "ai startup platform",
    "input_type": "idea",
    "field": "technology",
    "style": "brandable",
    "num_choices": 5
  }'

3. Example Response

{
  "domains": [
    {
      "domain": "aiplatformhub.com",
      "available": true,
      "price_first_year": 12.99,
      "price_annual": 14.99,
      "score": 8.5,
      "registrar": "name.com",
      "input_source": "ai_generated",
      "ranking_factors": {
        "word_quality": 6.5,
        "tld_score": 10.0,
        "length_score": 7.0
      }
    }
  ],
  "search_summary": {
    "available_domains_found": 8,
    "input_type": "idea"
  }
}

Main Endpoint

POST /api/domains/suggest

Main endpoint for domain suggestions with intelligent ranking

Request Parameters

ParameterTypeRequiredDescription
input_textstring✅Business idea, base name, or exact domain
input_typestring❌idea | exact_name | base_name
fieldstring❌Industry or field (optional)
stylestring❌brandable | short | keyword | creative | professional
domain_preferencestring❌.com | .io | .ai | any (default: .com)
provider_preferencestring❌name.com | porkbun | any (default: name.com)
max_pricenumber❌Maximum price per year (default: 50)
num_choicesnumber❌Number of results 1-20 (default: 5)

Response Format

{
  "domains": [
    {
      "domain": "string",
      "available": "boolean",
      "price_first_year": "number | null",
      "price_annual": "number | null",
      "registrar": "string",
      "deal_info": "string | null",
      "score": "number (0-10)",
      "input_source": "string",
      "ranking_factors": "object"
    }
  ],
  "request_id": "string",
  "timestamp": "string",
  "search_summary": "object"
}

Other Endpoints

GET /api/health

API status and configuration

Not rate limited
GET /api/rate-limit

Current rate limit status

Not rate limited
GET /api/pricing

Pricing and provider information

Not rate limited
GET /api/tlds

Available domain extensions

Not rate limited
GET /api/ranking

Ranking algorithm details

Not rate limited
POST /api/parse-input

Debug input parsing

Rate limited

Examples

Business Idea Generation

Generate AI suggestions based on business concept:

curl -X POST "http://localhost:5173/api/domains/suggest" \
  -H "Content-Type: application/json" \
  -d '{
    "input_text": "artificial intelligence customer service platform",
    "input_type": "idea",
    "field": "technology",
    "style": "brandable",
    "domain_preference": ".com",
    "max_price": 50,
    "num_choices": 5
  }'

Base Name Expansion

Check a base name with different TLDs:

curl -X POST "http://localhost:5173/api/domains/suggest" \
  -H "Content-Type: application/json" \
  -d '{
    "input_text": "mycompany",
    "input_type": "base_name",
    "domain_preference": "any",
    "num_choices": 10
  }'

Exact Domain Check

Check specific domain(s) for availability:

curl -X POST "http://localhost:5173/api/domains/suggest" \
  -H "Content-Type: application/json" \
  -d '{
    "input_text": "mycompany.com",
    "input_type": "exact_name",
    "additional_domains": ["mycompany.io", "mycompany.ai"],
    "num_choices": 10
  }'

Our Domain Ranking System

Score range: 0.0 to 10.0 (higher is better)

Ranking Factors

FactorWeightDescription
Source Bonus30%User-provided (8.0) > Base expansion (6.0) > AI generated (4.0)
Length Score20%Shorter domains score higher (≤5 chars = 8.0)
Word Quality25%Real words vs gibberish, pronounceability
TLD Quality15%.com (10.0) > .io (8.0) > .ai (7.5) > others
Memorability10%Easy to remember and type
Brandability10%Sounds like a professional brand
Keyword Relevance15%Relevance to original search terms
Price Factor5%Lower prices score higher

Quality Levels

Premium (8.0-10.0)
Exceptional domains
Strong (6.0-7.9)
Very good domains
Good (4.0-5.9)
Solid domains

Provider Information

Open Beta - Free to Use!
API is currently free during development phase
Providers
As of right now, the only providers are Name.com and Porkbun. Depending on demand, we may add more in the future.

Name.com Recommended

Rate Limit: 20 requests/sec, 3000/hour
Bulk Check: Up to 50 domains per call
Speed: Fast bulk checking
✅ Default choice - fast and reliable

Porkbun Limited

Rate Limit: 1 domain per 10 seconds
Bulk Check: 1 domain at a time
Speed: Very slow
⚠️ Only for individual domain checks

Supported TLDs

45+ domain extensions available:

.com.net.org.io.co.ai.app.dev.tech.online.site.store.shop.biz.info.me.cc.tv.xyz.cloud.digital.agency.studio.design.media +20 more

Error Handling

HTTP Status Codes

CodeDescriptionMeaning
200SuccessRequest completed successfully
400Bad RequestInvalid input parameters
422Validation ErrorRequest body validation failed
429Rate Limit ExceededToo many requests (100/minute)
500Internal Server ErrorAPI or provider error

Example Error Responses

// Rate limit exceeded (429)
{
  "detail": {
    "error": "Rate limit exceeded",
    "message": "Maximum 100 requests per minute allowed",
    "retry_after": 45
  }
}
// Validation error (422)
{
  "detail": [
    {
      "loc": ["body", "input_text"],
      "msg": "Input text cannot be empty",
      "type": "value_error"
    }
  ]
}

Best Practices

✅ Do

  • Use name.com provider for fastest results
  • Monitor rate limits with /api/rate-limit
  • Cache results to avoid repeat requests
  • Handle errors gracefully with try/catch
  • Use specific field/industry for better AI results

❌ Don't

  • Use porkbun for bulk domain checking
  • Exceed rate limits - implement backoff
  • Ignore error responses or status codes
  • Make requests without timeout handling
  • Request more domains than you need

Support & Resources

API Status

Check real-time API health

GET /api/health

Rate Limits

Monitor your usage

GET /api/rate-limit

Check Providers

Check all available providers

GET /api/test-providers

Quick Tips

For Startups: Use "brandable" style with your industry field for the best AI-generated suggestions that sound professional and memorable.
For Existing Businesses: Use "base_name" input type with your company name to check availability across different TLDs.
For Developers: The API auto-detects input type, but specifying it explicitly gives you more control over the search behavior.
For High Volume: Use name.com provider exclusively and implement client-side caching to minimize API calls.

© 2025 Snapsi API. All rights reserved. Made with ❤️ for developers who need great domains

API Status Rate Limits