HumbleWorth API Documentation

Note: The HumbleWorth API is currently in beta and subject to change. We're continuously working on improving the API and its features. As we refine our services, please be aware that the API's endpoints, response formats, and functionality might be updated. We encourage you to check back regularly for the latest information and updates. Thank you for your understanding and for helping us improve the HumbleWorth API.

Overview

The HumbleWorth API provides a streamlined, AI-powered solution for obtaining accurate domain valuations. This document details the process for submitting domain names to our API and interpreting the valuation data returned.

API Endpoint

• URL: https://valuation.humbleworth.com/api/valuation
• Method: POST
• Content-Type: application/json
• Rate Limit: 60 requests per minute (1 per second average), with a maximum of 20 domains per request.

Request Format

Submit your valuation requests as a JSON object with a domains key, containing an array of up to 20 domain names.

Example Request

{
  "domains": ["example.com", "example.net"]
}

Response Format

The API returns a JSON object with an array of valuations for the submitted domains. Each valuation object includes the domain name and estimated values across three market contexts: auction, marketplace, and brokerage.

Valuation Contexts Explained

• Auction: Estimated value if the domain were sold in a competitive auction setting.
• Marketplace: Estimated value for direct sales on domain marketplaces.
• Brokerage: Estimated value if sold through a domain brokerage service, typically reflecting a premium due to brokerage expertise and negotiation.

Successful Response

{
  "valuations": [
    {
      "domain": "example.com",
      "auction": 1000,
      "marketplace": 500,
      "brokerage": 250
    },
    {
      "domain": "example.net",
      "auction": 800,
      "marketplace": 400,
      "brokerage": 200
    }
  ]
}

Error Response

For invalid submissions (e.g., invalid domains or exceeding the 20-domain limit), the API returns an error message.

{
  "error": "Please provide at most 20 domains at a time"
}

Code Example

Below is an example demonstrating how to submit a valuation request and process the API response in a web application.

async function fetchValuations(domains) {
    try {
        const response = await fetch('https://valuation.humbleworth.com/api/valuation', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ domains })
        });
        if (!response.ok) {
            console.error('Error fetching valuations:', response.statusText);
            return;
        }
        const { valuations } = await response.json();
        console.log(valuations);
        return valuations;
    } catch (error) {
        console.error('Error:', error);
    }
}

// Example usage
fetchValuations(['example.com', 'example.net']).then(valuations => {
    if (valuations) {
        valuations.forEach(valuation => {
            console.log(`${valuation.domain}: Auction ${valuation.auction}, Marketplace ${valuation.marketplace}, Brokerage ${valuation.brokerage}`);
        });
    }
});

Rate Limit

To ensure fair usage and optimal performance, the API enforces a rate limit of one request per second per user. Requests exceeding this limit will be throttled or denied.

Limitations

• Domain names must be sanitized and valid prior to submission.
• Requests are limited to 20 domains at a time to ensure efficient processing.

For further assistance or inquiries, please contact hello@humbleworth.com.