TLD-API.com

Endpoints

Single Lookup

curl https://tld-api.com/v1/domains/google.com

The default response is sparse: null leaves, empty arrays, and empty objects are removed. DNS enrichment is included when it finishes within the short lookup budget.

Projection

curl 'https://tld-api.com/v1/domains/google.com?fields=dates.expires,registrar.name'

fields is a comma-separated list of dotted paths. Use fields=all for the full normalized record with nulls preserved.

Field selectors are strict. Unknown paths or invalid syntax return bad_fields.

Bulk Lookup

curl -X POST https://tld-api.com/v1/domains \
  -H 'Content-Type: application/json' \
  -d '{"domains":["google.com","orania.co.za"],"fields":"registrar.name,dates.expires"}'

Request body:

• domains — array of 1-100 domain strings. Order is preserved.
• fields — optional strict selector string or all.

[
  {"input":"google.com","ok":true,"domain":"google.com","data":{...}},
  {"input":"bad.invalid","ok":false,"error":{
    "code":"not_found","message":"Domain not found","domain":"bad.invalid","tld":"invalid"
  }}
]

Query

Build queries visually at /query, or POST to /v1/query directly. The where clause is a small JSON DSL for filtering a resource by field value, list, range, or existence.

curl -X POST https://tld-api.com/v1/query \
  -H 'Content-Type: application/json' \
  -d '{"where":{"tld":"com","dates.expires":{"$lt":"2027-01-01"}},"fields":"domain,registrar.name,dates.expires"}'

The where DSL

• { "tld": "com" } — equals (shorthand).
• { "tld": ["com", "net"] } — in-list (array shorthand).
• { "dates.expires": { "$lt": "2027-01-01" } } — range: $gt, $ge, $lt, $le.
• { "registrar.name": { "$exists": true } } — null check.
• $and, $or, $not — logic, nestable. A bare array (or multiple keys in one object) is an implicit $and.

{
  "where": {
    "$and": [
      { "tld": ["com", "net"] },
      { "registrar.iana_id": "292" },
      { "dates.expires": { "$lt": "2027-01-01" } }
    ]
  },
  "fields": "domain,tld,registrar.name,dates.expires",
  "sort": [{ "field": "dates.expires", "dir": "asc" }],
  "limit": 50
}

The default resource is domains (registered records; filter state to reach the negative cache). Set resource to registrars or changes for those tables. Project only the fields you need — nested data is fetched lazily, so scalar-only queries stay cheap. See /v1/query/schema for every field and operator.

{
  "resource": "registrars",
  "where": { "is_vip": 1 },
  "fields": "iana_id,name,status,rdap_url,seen_count",
  "sort": [{ "field": "seen_count", "dir": "desc" }]
}

Fields

Errors

{"error":{"code":"invalid_domain","message":"Invalid domain","domain":"localhost"}}