Getting Started

DomainsGPT's REST API allows developers to easily integrate GPT-powered domain name generation into their applications.

The API supports any programming language or framework that can send HTTP requests.

ℹ️

We are currently beta testing this API with select partners. If you would like to be considered for early access, please apply here.

API Basics

Our API is exposed as an HTTP/1 and HTTP/2 service over SSL. All endpoints live under the URL https://api.oneword.domains and then generally follow the REST architecture.

Authentication

DomainsGPT's API uses a token-based authentication system. You can find your API token in your DomainsGPT Dashboard.

Content Type

All requests must be encoded as JSON with the Content-Type: application/json header. If not otherwise specified, responses from the Vercel API, including errors, are encoded exclusively as JSON as well.

Rate Limits

The DomainsGPT API is rate limited to 1000 requests per minute per token. If you exceed this limit, you will receive a 429 Too Many Requests response.

Quick Start

For normal RESTful APIs with JSON data, first you need to create a fetcher function, which is just a wrapper of the native fetch:

fetch-request

await fetch("https://api.oneword.domains/gpt/generate", {
    "method": "POST",
    "headers": {
        "Authorization": "Bearer <TOKEN>",
        "Content-Type": "application/json"
    },
    "body": JSON.stringify({
        // Request parameters
    })
})

Example

Here's a simple example of how to use the DomainsGPT API to generate brandable domains in your React application:

import { useRef, useState } from "react";

export default function Generator() {
  const bottomRef = useRef(null);
  const [domains, setDomains] = useState([]);
  const [generating, setGenerating] = useState(false);

  const generateDomain = async () => {
    setDomains([]);
    setGenerating(true);
    const response = await fetch("https://api.oneword.domains/gpt/generate", {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        type: "portmanteau",
        word: "open",
        position: "prefix"
      })
    });
    
    // Handle rate limits
    if (!response.ok) {
      alert("You've reached your usage limit. Enter an API key to continue.");
      setGenerating(false);
      return;
    }

    // This data is a ReadableStream
    const data = response.body;
    if (!data) {
      return;
    }

    const reader = data.getReader();
    const decoder = new TextDecoder();
    let done = false;
    let tempState = "";

    while (!done) {
      const { value, done: doneReading } = await reader.read();
      done = doneReading;
      let chunkValue = decoder.decode(value);

      if (tempState) {
        chunkValue = tempState + chunkValue;
        tempState = "";
      }

      // match json string and extract it from the chunk
      const match = chunkValue.match(/{(.*?)}/);
      if (match) {
        tempState = chunkValue.replace(match[0], "");
        chunkValue = match[0];
      }

      try {
        const { domain, available } = JSON.parse(chunkValue);
        setDomains((prev) => [...prev, { domain, available }]);
        scrollTo({
          top:
            bottomRef.current.getBoundingClientRect().top +
            window.pageYOffset -
            (window.innerHeight - 50),
          behavior: "smooth"
        });
      } catch (e) {
        tempState = chunkValue;
      }
    }
    setGenerating(false);
  };

  return (
    <div className="p-5">
      <h1 className="text-2xl font-bold">DomainsGPT Demo</h1>
      <button
        onClick={generateDomain}
        disabled={generating}
        className={
          "my-2 rounded-md border border-black bg-black px-3 py-1 font-medium text-white transition-all hover:bg-white hover:text-black" +
          (generating
            ? "cursor-not-allowed border-gray-200 bg-gray-100 text-gray-300"
            : "")
        }
      >
        {generating ? "Generating..." : "Generate Domains"}
      </button>
      <ul className="my-2 grid grid-cols-2 gap-3">
        {domains.map(({ domain, available }, index) => {
          return (
            <li
              key={index}
              className="flex items-center justify-between rounded-md border border-gray-200 p-2 shadow-md"
            >
              <p className="font-medium">{domain}</p>
              {available ? (
                <svg
                  xmlns="http://www.w3.org/2000/svg"
                  width="24"
                  height="24"
                  viewBox="0 0 24 24"
                  fill="none"
                  stroke="#22C55E"
                  strokeWidth="2"
                  strokeLinecap="round"
                  strokeLinejoin="round"
                >
                  <polyline points="20 6 9 17 4 12"></polyline>
                </svg>
              ) : (
                <svg
                  xmlns="http://www.w3.org/2000/svg"
                  width="24"
                  height="24"
                  viewBox="0 0 24 24"
                  fill="none"
                  stroke="#DC2626"
                  strokeWidth="2"
                  strokeLinecap="round"
                  strokeLinejoin="round"
                >
                  <line x1="18" x2="6" y1="6" y2="18"></line>
                  <line x1="6" x2="18" y1="6" y2="18"></line>
                </svg>
              )}
            </li>
          );
        })}
      </ul>
      <div ref={bottomRef} />
    </div>
  );
}

Open Sandbox

DomainsGPT API