# sub.md

> Passive subdomain intelligence API. 5B+ subdomains from Certificate Transparency, passive DNS, and X.509 data. No active scanning.

## How to use

One endpoint, plain-text output, built for curl and shell pipelines.

```
curl https://api.sub.md/v1/search?apex=example.com
```

Returns newline-delimited FQDNs. Status 200 with body, 404 if the apex has no indexed subdomains, 429 if rate limited (respect `Retry-After`).

Use Bearer tokens for higher limits:

```
curl -H "Authorization: Bearer submd_..." https://api.sub.md/v1/search?apex=example.com
```

Full reference, code samples, and a live "Try it" widget: <https://sub.md/docs/>.

## Endpoints

- [GET /v1/search](https://api.sub.md/v1/search?apex=example.com): list subdomains for an apex domain. Required query param `apex`. Full docs: <https://sub.md/docs/#endpoints>.
- [GET /healthz](https://api.sub.md/healthz): liveness, returns `ok`.
- [GET /readyz](https://api.sub.md/readyz): readiness, returns `ready`.

## Docs

- API reference: <https://sub.md/docs/>
- Bearer auth and token format: <https://sub.md/docs/#auth>
- Status codes (200, 304, 400, 401, 404, 429, 503): <https://sub.md/docs/#status>
- Headers cheat-sheet (X-Auth-Type, X-Cache, ETag, Retry-After): <https://sub.md/docs/#headers>
- Rate limits per tier: <https://sub.md/docs/#limits>
- Code samples in curl/Python/Go/Node/Rust/PowerShell: <https://sub.md/docs/#samples>

## Plans

- Community: free, 50 queries / day, 1 req/s, anonymous, no key required.
- Researcher: EUR 39 / 30 days, 5,000 queries / month, 5 req/s.
- Professional: EUR 149 / 30 days, 100,000 queries / month, 20 req/s.
- Architect: EUR 500 / 30 days, 2,000,000 queries / month, 100 req/s.
- Architect 3M / 6M: longer-term Architect at EUR 1337 / 2499.
- Firehose annual: EUR 5000 / 12 months, 100M queries / month, 1000 req/s, Fair-Use Policy applies.

## Rules for automated agents

- Respect rate limits and `Retry-After` headers.
- Do not loop the same apex back-to-back with no new information.
- Cache responses. Identical queries within 5 minutes are served from cache with an ETag.
- Use `Accept-Encoding: gzip` for large results.
- Identify yourself in the `User-Agent` header.

## Contact

- Early access: earlybird@sub.md
- Security: security@neosecurity.nl (see /.well-known/security.txt)
- Responsible disclosure: https://neosecurity.nl/vulnerability-disclosure-policy