# ip.thc.org API Documentation

Base URL: `https://ip.thc.org`

Search billions of indexed domains via free Reverse DNS, Subdomain Finder, and CNAME Lookup APIs. No registration required.

## About IP.THC.ORG

IP.THC.ORG provides access to the world's largest Internet domain database — **6 billion+ indexed domains** — maintained by The Hacker's Choice (hackerschoice). It answers three reverse questions that ordinary DNS tools cannot:

1. **Reverse DNS (rDNS)** — which domains resolve to a given IP address or CIDR range?
2. **Subdomain finder** — which subdomains exist under a given apex domain?
3. **CNAME lookup (reverse)** — which domains have a CNAME record pointing to a given target?

It is **free forever**, requires **no registration or API key**, and is designed to be used directly from the command line with `curl` as well as from a web browser. Typical users include security researchers, penetration testers, bug-bounty hunters, network administrators, and developers building reconnaissance or asset-discovery tooling.

## Frequently asked questions

**Is IP.THC.ORG free?** Yes — completely free with no registration or API key, and it will always remain free.

**How big is the database?** It indexes 6 billion+ domains, the largest free Internet domain database available.

**How do I do a reverse DNS lookup?** `curl https://ip.thc.org/1.1.1.1` — returns every domain known to resolve to that IP with ASN, organization, and location.

**How do I find subdomains of a domain?** `curl https://ip.thc.org/sb/thc.org` — returns known subdomains of the apex domain.

**How do I find domains pointing to a CNAME?** `curl https://ip.thc.org/cn/github.io` — returns every domain whose CNAME points to the target. This is valuable for mapping SaaS tenants and detecting subdomain-takeover risk.

**Is there a JSON API?** Yes — `POST https://ip.thc.org/api/v1/lookup`. See the full reference below.

**Can I download data in bulk?** Yes — CSV downloads of up to 50,000 records per request via the `/api/v1/download` endpoints.

---

## Rate Limiting

- **Default**: 250 tokens burst, 0.5 tokens/sec refill (per IP)
- **Response headers** on every request:
  - `x-ratelimit-limit` — Burst limit (tokens)
  - `x-ratelimit-rate` — Fill rate (requests/sec)
  - `x-ratelimit-remaining` — Available tokens
  - `x-is-cached` — `true` if response came from cache
- **429 Too Many Requests** when limit exceeded
- Bulk download endpoints consume **3 events** per request vs **1** for lookups

---

## Simple Text Endpoints

### Reverse DNS Lookup by IP

```bash
curl https://ip.thc.org/1.1.1.1?nocolor=1&l=50
```

| Param | Type | Default | Description |
|---|---|---|---|
| `f` | string | — | Apex domain filter (e.g., `?f=google.com`) |
| `l`, `limit` | int | 100 | Max results (max: 200) |
| `nocolor` | bool | false | Disable ANSI colors (`1` or `true`) |
| `raw` | bool | false | Skip punycode parsing (`1` or `true`) |
| `p`, `page_state` | string | — | Pagination token for next page |
| `noheader` | bool | false | Hide result header (`1` or `true`) |

**Response**: `text/plain` with ASN, organization, city, country, GPS, and domain list.

### Self IP Lookup

```bash
curl https://ip.thc.org/me?nocolor=1
```

Returns rDNS lookup for the requester's own IP. Same params/response as above.

### Force RDNS (no auto-detection)

```bash
curl https://ip.thc.org/i/1.1.1.1?nocolor=1
```

Forces reverse DNS even if the path looks like a domain name.

### Subdomain Lookup

```bash
curl https://ip.thc.org/sb/wikipedia.org?nocolor=1&l=50
```

Prefixes: `/s/`, `/sb/`, `/sd/`, `/sub/`, `/subs/` — all equivalent.

| Param | Type | Default | Description |
|---|---|---|---|
| `l`, `limit` | int | 100 | Max results (max: 200) |
| `nocolor` | bool | false | Disable ANSI colors |
| `raw` | bool | false | Skip punycode parsing |
| `p`, `page_state` | string | — | Pagination token |

**Response**: `text/plain` with subdomain list.

### CNAME Lookup

```bash
curl https://ip.thc.org/cn/github.io?nocolor=1&l=50
```

Prefixes: `/c/`, `/cn/`, `/cname/` — all equivalent.

| Param | Type | Default | Description |
|---|---|---|---|
| `l`, `limit` | int | 100 | Max results (max: 200) |
| `nocolor` | bool | false | Disable ANSI colors |
| `raw` | bool | false | Skip punycode parsing |
| `p`, `page_state` | string | — | Pagination token |

**Response**: `text/plain` with domains pointing to the target.

---

## JSON REST API

### Reverse DNS Lookup (JSON)

```bash
curl -X POST https://ip.thc.org/api/v1/lookup \
  -H "Content-Type: application/json" \
  -d '{"ip_address":"8.8.8.0/24","limit":10}'
```

**Request body**:

| Field | Type | Required | Description |
|---|---|---|---|
| `ip_address` | string | Yes | IP address or CIDR block (`/8`, `/16`, `/24`) |
| `api_key` | string | No | Reserved (not enforced) |
| `apex_domain` | string | No | Filter by apex domain |
| `tld` | string[] | No | Filter by TLDs (e.g., `["com", "de"]`) |
| `page_state` | string | No | Pagination token |
| `limit` | int | No | Max results (max: 200) |

**Response** (`application/json`):

```json
{
  "comment": "",
  "processed_ip_address": "8.8.8.8",
  "matching_records": 42,
  "domains": [
    {
      "apex_domain": "google.com",
      "domain": "www.google.com",
      "country": "US",
      "city": "Mountain View",
      "asn": "15169",
      "tld": "com",
      "organization": "Google LLC",
      "ip_address": "142.250.185.1"
    }
  ],
  "next_page_state": "eyJwYWdlIjoxfQ=="
}
```

### CNAME Lookup (JSON)

```bash
curl -X POST https://ip.thc.org/api/v1/lookup/cnames \
  -H "Content-Type: application/json" \
  -d '{"target_domain":"google.com","limit":10}'
```

**Request body**:

| Field | Type | Required | Description |
|---|---|---|---|
| `target_domain` | string | Yes | Domain to find CNAMEs for |
| `apex_domain` | string | No | Filter by apex domain |
| `page_state` | string | No | Pagination token |
| `limit` | int | No | Max results (max: 200) |

**Response** (`application/json`):

```json
{
  "comment": "",
  "processed_target_domain": "google.com",
  "matching_records": 156,
  "domains": ["cdn.google.com", "www.google.com"],
  "next_page_state": "eyJwYWdlIjoxfQ=="
}
```

### Subdomain Lookup (JSON)

```bash
curl -X POST https://ip.thc.org/api/v1/lookup/subdomains \
  -H "Content-Type: application/json" \
  -d '{"domain":"thc.org","limit":10}'
```

**Request body**:

| Field | Type | Required | Description |
|---|---|---|---|
| `domain` | string | Yes | Apex domain to find subdomains of |
| `page_state` | string | No | Pagination token |
| `limit` | int | No | Max results (max: 200) |

**Response** (`application/json`):

```json
{
  "comment": "",
  "processed_domain": "thc.org",
  "matching_records": 42,
  "domains": [
    {"domain": "mail.thc.org", "last_seen_on": "2026-06-10"},
    {"domain": "www.thc.org", "last_seen_on": "2026-06-12"}
  ],
  "next_page_state": "eyJwYWdlIjoxfQ=="
}
```

---

## CSV Bulk Downloads

Per-query CSV exports return up to 50,000 records per request. For offline analysis of the
**entire dataset**, full snapshot downloads are also offered in **CSV and Parquet** format —
see https://ip.thc.org/docs/bulk-data-access. Bulk download requests consume 3 rate-limit
tokens versus 1 for a standard lookup.

### RDNS Download

```bash
curl 'https://ip.thc.org/api/v1/download?ip_address=8.8.8.8&limit=500&hide_header=true' -o results.csv
```

| Param | Type | Default | Description |
|---|---|---|---|
| `ip_address` | string | — | IP or CIDR block |
| `limit` | int | 1000 | Max results (max: 50,000) |
| `hide_header` | bool | false | Hide CSV column headers |
| `apex_domain` | string | — | Filter by apex domain |
| `tld` | string[] | — | Filter by TLDs |

### Subdomain Download

```bash
curl 'https://ip.thc.org/api/v1/subdomains/download?domain=thc.org&limit=500' -o results.csv
```

| Param | Type | Default | Description |
|---|---|---|---|
| `domain` | string | — | Apex domain |
| `limit` | int | 1000 | Max results (max: 50,000) |
| `hide_header` | bool | false | Hide CSV column headers |

### CNAME Download

```bash
curl 'https://ip.thc.org/api/v1/cnames/download?target_domain=google.com&limit=500' -o results.csv
```

| Param | Type | Default | Description |
|---|---|---|---|
| `target_domain` | string | — | Target domain |
| `limit` | int | 1000 | Max results (max: 50,000) |
| `hide_header` | bool | false | Hide CSV column headers |

---

## Support & Donations

**ip.thc.org will always remain free.** We run this service out of passion for the community and open research. Maintaining and making this data available takes a non-trivial amount of time, energy, and server costs.

If you benefit from this tool, please consider helping us keep it running:

- **BTC**: `bc1qdp6mdje5f9x8ar8jg3uv425d4r2v5cmdygkknz`
- **ETH**: `0xb59fB528BFee42caba4A607AFD13444FB38d0820`
- **XMR**: `85RDZJfdGWX3BzUESZSBNtNicHeTJo3UseYH2Pk6XeW61hFF3JWSax9LkvHZPCYg8pHJfQxCEHfgsFXFWrFNiUVMGzFv9cx`

You can also contribute by:
- Sharing any DNS/Domain/IP database you might have
- Spreading the word about this tool
- Contacting us at [Telegram](https://t.me/thcorg) for bulk access or partnership inquiries

Every bit of support helps keep this service free and running for everyone.