# Subdomains by Jsmon — Full API Reference

> Subdomain lookup API with 5.4 billion+ subdomains. One GET request returns every subdomain observed for a root domain. Updated daily, average response under 100ms.

Base URL: https://subdomains.jsmon.sh
Operator: Jsmon Inc. (Delaware, USA) — https://jsmon.sh
Support: support@jsmon.sh
Last updated: 2026-10-10

---

## 1. Overview

Subdomains by Jsmon is a passive subdomain enumeration API. It does not scan or probe targets; it returns subdomains already observed in public sources:

- Certificate transparency logs
- DNS records
- Web crawling
- Other OSINT sources

Database size: 5.4 billion+ subdomains as of October 2026 (3.5B at launch in September 2026). The database is updated daily, and most new subdomains appear within 24–48 hours of showing up in public sources. Average response time is under 100ms.

There are two ways to query:

1. API key — sign up at https://subdomains.jsmon.sh/signup (free tier available)
2. Machine Payments Protocol (MPP) — pay per query with no account, built for AI agents

---

## 2. Authentication

### API key

Send your key in the `Api-Key` header:

```
Api-Key: YOUR_API_KEY
```

Get a free key at https://subdomains.jsmon.sh/signup. Manage keys in the dashboard.

### MPP (pay per query)

Call `/api/mpp/domain/{domain}` without credentials. The server answers `402 Payment Required` with an MPP challenge in the `WWW-Authenticate` header. Pay the challenge (Tempo stablecoins or Stripe Shared Payment Tokens), then repeat the request with the credential in the `Authorization: Payment ...` header. The domain is checked before payment, so unknown domains return `404` and are not charged.

---

## 3. Endpoints

### GET /api/domain/{domain}

Returns subdomains for a root domain. Requires an API key.

Path parameters:

- `domain` (required) — root domain, e.g. `example.com`. Case-insensitive.

Query parameters:

- `page` (optional) — page number for paginated JSON results. Increment until a page returns no subdomains.
- `mode` (optional) — set to `txt` to receive every subdomain as plain text, one per line, in a single response with no pagination. Available on Pro and Max. Counts as one query.

JSON response (200):

```json
{
  "domain": "tesla.com",
  "total": 4521,
  "page": 1,
  "per_page": 100,
  "total_pages": 46,
  "subdomains": [
    "api.tesla.com",
    "mail.tesla.com",
    "vpn.tesla.com"
  ]
}
```

Fields:

- `domain` — the queried root domain
- `total` — total number of known subdomains for the domain
- `page` — current page number
- `per_page` — results per page
- `total_pages` — total number of pages
- `subdomains` — array of fully qualified subdomains (FQDNs, not prefixes)

Plain-text response (200, `mode=txt`):

```
api.tesla.com
mail.tesla.com
vpn.tesla.com
```

Errors:

- `400` — invalid domain format
- `401` — missing or invalid API key
- `403` — plan restriction: feature not available (e.g. `mode=txt` on Free), email not verified, or query quota exceeded
- `404` — no subdomains known for this domain
- `429` — rate limited (Free plan: one request per 10 seconds)
- `500` — internal error

### GET /api/mpp/domain/{domain}

Pay-per-query endpoint for agents. $0.50 per lookup. Returns up to 10,000 subdomains, sorted alphabetically.

Query parameters:

- `mode` (optional) — `txt` for plain text, one subdomain per line. The total is returned in the `X-Total-Count` header.

JSON response (200):

```json
{
  "domain": "example.com",
  "total": 1547,
  "returned": 1547,
  "is_truncated": false,
  "subdomains": ["a.example.com", "b.example.com"]
}
```

Fields:

- `domain` — the looked-up domain, lowercased
- `total` — total known subdomains
- `returned` — subdomains in this response (max 10,000)
- `is_truncated` — `true` when `total` exceeds `returned`
- `subdomains` — FQDNs, sorted alphabetically

Responses: `200` (with `Payment-Receipt` header), `400` invalid domain, `402` payment required, `404` no known subdomains (not charged), `500` internal error.

---

## 4. Code examples

### curl

```bash
# JSON
curl -s 'https://subdomains.jsmon.sh/api/domain/example.com' -H 'Api-Key: YOUR_API_KEY' | jq

# Every subdomain as plain text, piped into httpx (Pro/Max)
curl -s 'https://subdomains.jsmon.sh/api/domain/example.com?mode=txt' -H 'Api-Key: YOUR_API_KEY' | httpx -silent
```

### Python

```python
import requests

r = requests.get(
    "https://subdomains.jsmon.sh/api/domain/example.com",
    headers={"Api-Key": "YOUR_API_KEY"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
print(data["total"])
for sub in data["subdomains"]:
    print(sub)
```

### Node.js

```javascript
const res = await fetch("https://subdomains.jsmon.sh/api/domain/example.com", {
  headers: { "Api-Key": "YOUR_API_KEY" },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { total, subdomains } = await res.json();
console.log(total, subdomains.length);
```

### Go

```go
req, _ := http.NewRequest("GET", "https://subdomains.jsmon.sh/api/domain/example.com", nil)
req.Header.Set("Api-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var out struct {
    Domain     string   `json:"domain"`
    Total      int      `json:"total"`
    Subdomains []string `json:"subdomains"`
}
json.NewDecoder(resp.Body).Decode(&out)
fmt.Println(out.Total)
```

### Rust

```rust
let client = reqwest::Client::new();
let body: serde_json::Value = client
    .get("https://subdomains.jsmon.sh/api/domain/example.com")
    .header("Api-Key", "YOUR_API_KEY")
    .send()
    .await?
    .json()
    .await?;
println!("{}", body["total"]);
```

---

## 5. Pagination

JSON results from `/api/domain/{domain}` are paginated. Request `page=1`, `page=2`, ... until a page returns an empty `subdomains` array. To skip pagination entirely, use `?mode=txt` (Pro and Max): every subdomain in one response, one query consumed.

---

## 6. Pricing and limits

| Plan | Price | Queries | Results per query | Notes |
|---|---|---|---|---|
| Free | $0 | 3 per day | 100 | Community support |
| Pro | $20/month | 5,000 per month | 10,000 | `mode=txt`, priority support |
| Max | $100/month | 50,000 per month | 10,000 | `mode=txt`, priority support |
| Enterprise | Custom | Unlimited | Unlimited | Full database exports, SLA, commercial data licence |
| MPP | $0.50 per query | Pay as you go | 10,000 | No account, for AI agents |

Enterprise is designed for ASM vendors, MSSPs, bug bounty and pentest platforms, and security teams that need the full dataset. Contact support@jsmon.sh.

---

## 7. Common use cases

1. Bug bounty and penetration-testing recon
2. Attack surface discovery and asset inventory
3. Subdomain takeover detection
4. Monitoring for newly created subdomains
5. Security automation and CI/CD pipelines (httpx, nuclei, Amass, custom tooling)
6. Threat intelligence and brand monitoring

---

## 8. Related product

Jsmon EASM platform (https://jsmon.sh): AI-powered external attack surface management — JavaScript monitoring, secret detection, API endpoint discovery, cloud asset discovery, vulnerability scanning, subdomain takeover detection, and continuous monitoring.

---

## 9. Support and legal

- Support: support@jsmon.sh
- Terms: https://jsmon.sh/terms
- Privacy: https://jsmon.sh/privacy
- Operator: Jsmon Inc., Delaware, USA

---

## 10. Discovery files

- https://subdomains.jsmon.sh/llms.txt
- https://subdomains.jsmon.sh/llms-full.txt
- https://subdomains.jsmon.sh/openapi.json
- https://subdomains.jsmon.sh/.well-known/ai-plugin.json
- https://subdomains.jsmon.sh/.well-known/mpp.json
- https://subdomains.jsmon.sh/.well-known/security.txt
- https://subdomains.jsmon.sh/sitemap.xml
- https://subdomains.jsmon.sh/changelog