API Documentation

Public endpoints for developers to integrate with EZDomains.

Featured Sites

`GET /api/featured`

Get a list of featured Handshake sites for the gateway homepage.

Example

GET /api/featured

Response

[
  {
    "name": "australia",
    "url": "https://australia.hns.best",
    "description": "Country community hub.",
    "color_class": "text-emerald-400"
  },
  ...
]

Looking for AI Agent integration? Check out our AI Skill Definition.

Raffles

`GET /api/raffles/public`

Get public list of recent winners and upcoming raffles.

`GET /api/tld/<tld_id>/raffles`

Get raffles for a specific TLD (Requires Auth).

`POST /api/tld/<tld_id>/raffles`

Create a new raffle (Requires Auth).

Body Parameters

title: Raffle title
prize: Prize description
draw_at: ISO8601 Date String
claim_requirement: 'none', 'wallet_address', 'email', 'custom'
claim_prompt: Custom question text (optional)

Domain Search

`GET /api/search`

Check if a domain (SLD) is available or registered.

Parameters

term (required): The full domain to search (e.g., test.ez).

Example

GET /api/search?term=test.ez

Whois Lookup

`GET /api/whois/<domain>`

Get registration details for a specific domain.

Example

GET /api/whois/cool.ez

Recent Sales / Registrations

`GET /api/sales`

Get a feed of recent domain registrations across all managed TLDs.

Parameters

limit (optional): Number of results to return (default: 10).

Example

GET /api/sales?limit=5

Response

[
  {
    "currency": "HNS",
    "domain": "cool.ez",
    "price": null,
    "timestamp": "2024-01-10T08:00:00",
    "tld": "ez"
  }
]

Zone Data

`GET /api/zones/<tld>/domains`

Get the full list of registered domains for a specific TLD.

Example

GET /api/zones/ez/domains

Premium Domains

`GET /api/premium-domains`

Get a curated list of premium domains available for purchase.

Example

GET /api/premium-domains

Response

{
  "domains": [
    {
      "domain": "also.ez",
      "price": "19.99",
      "currency": "USD",
      "registrar": "porkbun",
      "status": "active"
    }
  ],
  "unavailable": []
}

TLD Configuration

`GET /api/my-tlds`

Get TLDs managed by the currently authenticated user (Owned or Team Member).

Authentication

Requires Authorization: Bearer <token> header.

Response

[
  {
    "id": 1,
    "name": ".ez",
    "role": "owner",
    "is_commercial": true,
    "registrars": [...]
  }
]

`GET /api/tlds`

Get a list of configured TLDs and their registrars.

Parameters

is_commercial (optional): Set to true to fetch only commercial/public sales TLDs.
mine (optional): Set to true to fetch only TLDs managed by the authenticated user (Requires Bearer token).

Example

GET /api/tlds?is_commercial=true

Response

[
  {
    "name": ".ez",
    "is_commercial": true,
    "registrars": [
      {
        "name": "Namecheap",
        "urlTemplate": "https://www.namecheap.com/..."
      },
      {
        "name": "Porkbun",
        "urlTemplate": "https://porkbun.com/tld/ez"
      }
    ]
  }
]