<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Certificate Transparency Reconnaissance

## crt.sh

### Query by Domain
```bash
curl -s "https://crt.sh/?q=%.example.com&output=json" | jq -r '.[].name_value' | sort -u
```

### Query by Organization
```bash
curl -s "https://crt.sh/?q=%.&O=Example+Corp&output=json" | jq '.[].common_name'
```

### Exclude Expired
```bash
curl -s "https://crt.sh/?q=%25.example.com&output=json&exclude=expired"
```

### Search by SHA-256
```bash
curl -s "https://crt.sh/?q=FINGERPRINT_SHA256&output=json"
```

## Certspotter API

### List Issuances
```bash
curl -s "https://api.certspotter.com/v1/issuances?domain=example.com&include_subdomains=true&expand=dns_names"
```

### Authenticated Requests
```bash
curl -s -H "Authorization: Bearer $CERTSPOTTER_TOKEN" \
  "https://api.certspotter.com/v1/issuances?domain=example.com&after=CURSOR"
```

### Rate Limits
- Unauthenticated: 100 requests/hour
- Authenticated: 10,000 requests/hour

## Censys Certificates API

### Search Certificates
```bash
censys search "parsed.names: example.com" --index-type certs \
  -f parsed.names,parsed.subject.organization,parsed.validity.start
```

### REST API
```bash
curl -s -u "$CENSYS_ID:$CENSYS_SECRET" \
  "https://search.censys.io/api/v2/certificates/search" \
  -H "Content-Type: application/json" \
  -d '{"q":"parsed.names: example.com","per_page":100}'
```

## tlsx

### Bulk Certificate Grab
```bash
tlsx -l hosts.txt -san -cn -so -silent -json -o certs.json
```

### Single Host
```bash
echo "example.com:443" | tlsx -san -cn -so -json
```

### Certificate Chain
```bash
echo "example.com" | tlsx -chain -json
```

## OpenSSL CLI

### Inspect Certificate
```bash
echo | openssl s_client -connect example.com:443 2>/dev/null | openssl x509 -noout -text
```

### Extract SANs
```bash
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null \
  | openssl x509 -noout -ext subjectAltName
```

### Certificate Chain
```bash
echo | openssl s_client -showcerts -connect example.com:443 2>/dev/null
```

## Certstream

### Live Monitoring
```bash
certstream --full --json | jq 'select(.data.leaf_cert.all_domains[] | contains("example"))'
```

### Python Client
```python
import certstream

def callback(message, context):
    if message["message_type"] == "certificate_update":
        domains = message["data"]["leaf_cert"]["all_domains"]
        print(domains)

certstream.listen_for_events(callback, url="wss://certstream.calidog.io/")
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `CERTSPOTTER_TOKEN` | Certspotter API token |
| `CENSYS_API_ID` | Censys API ID |
| `CENSYS_API_SECRET` | Censys API secret |
