Search Subnames

Search for subnames by name pattern or owner address.

Endpoint

GET /api/subnames/{parent}/search

Authentication

None required — This is a public read endpoint.

Parameters

Parameter	Type	Location	Required	Description
parent	string	path	✅	Parent ENS name (e.g., aboutme.eth)
q	string	query	❌*	Name search query (partial match)
owner	string	query	❌*	Owner address to filter by

info

At least one of q or owner is required.

Response

{
  "parent": "aboutme.eth",
  "query": "ali",
  "owner": null,
  "count": 3,
  "results": [
    {
      "name": "alice",
      "fullName": "alice.aboutme.eth",
      "owner": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
      "created_at": "2024-02-09T18:30:00.000Z",
      "expires_at": "2025-02-09T18:30:00.000Z",
      "links": {
        "profile": "https://alice.aboutme.eth.limo",
        "ens_app": "https://app.ens.domains/alice.aboutme.eth"
      }
    },
    {
      "name": "alicia",
      "fullName": "alicia.aboutme.eth",
      "owner": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
      "created_at": "2024-02-08T12:00:00.000Z",
      "expires_at": "2025-02-08T12:00:00.000Z",
      "links": {
        "profile": "https://alicia.aboutme.eth.limo",
        "ens_app": "https://app.ens.domains/alicia.aboutme.eth"
      }
    }
  ],
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Examples

cURL

# Search by name pattern
curl "https://api.web3identity.com/api/subnames/aboutme.eth/search?q=ali"

# Search by owner address
curl "https://api.web3identity.com/api/subnames/aboutme.eth/search?owner=0x701B4937e6c943789ffA74CC8601813b2D87B454"

JavaScript

// Search by name
async function searchSubnames(parent, query) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/search?q=${encodeURIComponent(query)}`
  );
  return response.json();
}

// Search by owner
async function searchByOwner(parent, owner) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/search?owner=${owner}`
  );
  return response.json();
}

// Find names containing "crypto"
const results = await searchSubnames('aboutme.eth', 'crypto');
console.log(`Found ${results.count} matching names`);

Python

import requests

def search_subnames(parent: str, query: str = None, owner: str = None):
    params = {}
    if query:
        params['q'] = query
    if owner:
        params['owner'] = owner
    
    response = requests.get(
        f"https://api.web3identity.com/api/subnames/{parent}/search",
        params=params
    )
    return response.json()

# Search by name pattern
results = search_subnames("aboutme.eth", query="dev")
print(f"Found {results['count']} names containing 'dev'")

Search Behavior

Search Type	Behavior	Example
Name (q)	Partial match (LIKE %query%)	q=ali matches "alice", "alicia", "malik"
Owner (owner)	Exact match (case-insensitive)	Returns all names owned by address

Limits

• Maximum 50 results per search
• Results ordered by creation date (newest first)

Error Responses

Status	Code	Description
400	BAD_REQUEST	Must provide either q or owner parameter
429	RATE_LIMITED	Rate limit exceeded
500	SEARCH_ERROR	Internal server error

Related Endpoints

• Check Availability — Check if specific name is available
• By Owner — Get all names for an owner
• List All — Browse all subnames