List TLDs

​

Returns a paginated list of TLDs in the order defined in the config file. By default, only enabled TLDs are returned. Every row also carries period_unit, min_period, and max_period so clients can bound their registration-term selector to the values the registry accepts.

Filters

  • status: enabled (default), disabled, or all
  • category: Comma-separated list of gtld, ngtld, cctld, stld
  • exclude: Comma-separated TLD names to omit from results (e.g., com,net)

Categories

Category Description
gtld Generic TLDs (.com, .net, .org)
ngtld New Generic TLDs post-2012 (.app, .dev, .xyz)
cctld Country Code TLDs (.io, .ai, .in)
stld Sponsored TLDs (.edu, .gov)

Registration term

period_unit is y or m. min_period and max_period are expressed in that unit. Most TLDs fall back to the defaults (y, 1, 10); ccTLDs whose registry enforces tighter bounds (e.g. .ai min=2, .au max=5, .de max=1) override here.

Error Codes
Code HTTP Description
tld.list.invalid_status 400 status is not enabled, disabled, or all
tld.list.invalid_category 400 a category value is not gtld, ngtld, cctld, or stld
Query Parameters
  • status
    Type: string

    Filter by status: enabled (default), disabled, all

  • category
    Type: string

    Filter by category (comma-separated): gtld, ngtld, cctld, stld

  • exclude
    Type: string

    Comma-separated TLD names to exclude (e.g., com,net)

  • limit
    Type: integer

    Items per page (default 100, max 500)

  • cursor
    Type: string

    Pagination cursor for next page

Responses
  • application/json
  • application/json
Request Example for get/tlds
curl 'https://api.nametrust.com/tlds?status=&category=&exclude=&limit=1&cursor='

{
  "object": "list",
  "items": [
    {
      "object": "tld",
      "name": "com",
      "category": "gtld",
      "period_unit": "y",
      "min_period": 1,
      "max_period": 10,
      "icann_fee": {
        "object": "money",
        "amount": 18,
        "currency": "USD"
      }
    }
  ],
  "pages": {
    "object": "cursor",
    "has_prev": true,
    "direction": "next",
    "cursor": "abc123",
    "next_cursor": "def456",
    "prev_cursor": "xyz789",
    "page": 2,
    "total_pages": 10,
    "total_items": 100,
    "limit": 20,
    "has_next": true
  }
}

Paginated list of TLDs