Get Subname Details

Retrieve basic details for a registered subname.

Endpoint

GET /api/subnames/{parent}/{name}

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)
name	string	path	✅	Subname label (e.g., alice)

Response

{
  "parent": "aboutme.eth",
  "name": "alice",
  "fullName": "alice.aboutme.eth",
  "owner": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
  "created_at": "2024-02-09T18:30:00.000Z",
  "expires_at": "2025-02-09T18:30:00.000Z",
  "records": {
    "description": "Web3 developer",
    "url": "https://alice.dev"
  },
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Examples

cURL

curl "https://api.web3identity.com/api/subnames/aboutme.eth/alice"

JavaScript

async function getSubnameDetails(parent, name) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/${name}`
  );
  
  if (!response.ok) {
    if (response.status === 404) {
      return null; // Not found
    }
    throw new Error(`API error: ${response.status}`);
  }
  
  return response.json();
}

// Get details
const details = await getSubnameDetails('aboutme.eth', 'alice');

if (details) {
  console.log(`Owner: ${details.owner}`);
  console.log(`Created: ${details.created_at}`);
  console.log(`Expires: ${details.expires_at}`);
} else {
  console.log('Subname not found');
}

Python

import requests

def get_subname_details(parent: str, name: str):
    response = requests.get(
        f"https://api.web3identity.com/api/subnames/{parent}/{name}"
    )
    
    if response.status_code == 404:
        return None
    
    response.raise_for_status()
    return response.json()

details = get_subname_details("aboutme.eth", "alice")
if details:
    print(f"Owner: {details['owner']}")

Differences from Profile Endpoint

Feature	Get Details	Get Profile
Basic info	✅	✅
Records	✅	✅
Links (profile, ENS)	❌	✅
QR codes	❌	✅
OG/Social data	❌	✅
Mint CTA	❌	✅

Use Get Details for basic lookups and ownership verification. Use Get Profile for rich display and sharing features.

Error Responses

Status	Code	Description
404	NOT_FOUND	Subname does not exist
429	RATE_LIMITED	Rate limit exceeded
500	SUBNAME_ERROR	Internal server error

Related Endpoints

• Get Profile — Full profile with links and QR
• Check Availability — Check if name is available
• Get Price — Get registration price