Delete Subname

Delete a subname. Only the owner can delete their subname.

Endpoint

DELETE /api/subnames/{parent}/{name}

Authentication

Owner verification required — You must be the subname owner.

Parameters

Parameter	Type	Location	Required	Description
parent	string	path	✅	Parent ENS name (e.g., aboutme.eth)
name	string	path	✅	Subname label to delete (e.g., alice)

Response

{
  "success": true,
  "parent": "aboutme.eth",
  "name": "alice",
  "fullName": "alice.aboutme.eth",
  "deleted": true,
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Examples

cURL

# Delete with SIWE authentication
curl -X DELETE "https://api.web3identity.com/api/subnames/aboutme.eth/alice" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

async function deleteSubname(parent, name, token) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/${name}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Delete failed');
  }
  
  return response.json();
}

// Delete subname
const result = await deleteSubname('aboutme.eth', 'alice', siweToken);
console.log(`Deleted: ${result.fullName}`);

Important Notes

Deletion is Permanent

• All records associated with the subname are deleted
• The name becomes available for anyone to register
• This action cannot be undone
• Consider transferring instead of deleting if you want someone else to have it

When to Delete

Scenario	Recommendation
Want to release a name	✅ Delete
Give name to a friend	❌ Use Transfer instead
Rename yourself	✅ Delete old, register new
Name expired	Not needed (auto-deleted)

Error Responses

Status	Code	Description
401	UNAUTHORIZED	No authentication provided
403	NOT_OWNER	You don't own this subname
404	NOT_FOUND	Subname does not exist
429	RATE_LIMITED	Rate limit exceeded
500	SUBNAME_ERROR	Internal server error

Related Endpoints

• Transfer — Transfer instead of deleting
• Get Details — Check ownership before deleting
• Register — Register a new name after deleting