theHarvester/docs/wiki/Rest-API.md

REST API

restfulHarvest runs a FastAPI service for local automation and interactive Swagger/ReDoc documentation.

Start the service

uv run restfulHarvest

Defaults:

• host: 127.0.0.1
• port: 5000
• log level: info
• rate limit: 5/minute per client address

Use uv run restfulHarvest -h for current launcher options. For example:

uv run restfulHarvest --rate-limit 10/minute

Open:

• Swagger UI: http://127.0.0.1:5000/docs
• ReDoc: http://127.0.0.1:5000/redoc

Treat the runtime OpenAPI document as the exact request and response reference.

Core routes

Route	Purpose
GET /sources	List current discovery sources.
GET /query	Run selected discovery sources and return consolidated JSON.
GET /dnsbrute	Run active DNS brute force for an authorized domain.
GET /runs	List recent completed enumeration runs.
GET /runs/{run_id}	Retrieve one completed run and its normalized evidence.

List sources:

curl -s http://127.0.0.1:5000/sources | jq -r '.sources[]'

Run a passive query:

curl -sG http://127.0.0.1:5000/query \
  --data-urlencode 'domain=example.com' \
  --data-urlencode 'source=crtsh' \
  --data-urlencode 'source=certspotter' \
  | jq

The source parameter also accepts the same capability selectors as the CLI: subdomains, emails, ips, asns, urls, people, and breaches. Repeat source to combine capabilities with explicit source names. Selection is a union and does not filter fields returned by a selected source.

curl -sG http://127.0.0.1:5000/query \
  --data-urlencode 'domain=example.com' \
  --data-urlencode 'source=emails' \
  --data-urlencode 'source=certspotter' \
  | jq

A completed /query also retains its normalized terminal record in the local SQLite database. No JSON, XML, or JSONL report file is written unless filename is supplied.

HIBP verified-domain participates in all, emails, and breaches selections. When its provider key is configured, any selection that includes it also requires the operator API key:

curl -sG http://127.0.0.1:5000/query \
  -H "X-API-Key: $THEHARVESTER_API_KEY" \
  --data-urlencode "domain=$VERIFIED_DOMAIN" \
  --data-urlencode 'source=hibpverified' \
  | jq '{emails, breaches}'

Completed-run routes require the operator API key because retained evidence can contain sensitive results:

curl -s http://127.0.0.1:5000/runs \
  -H "X-API-Key: $THEHARVESTER_API_KEY" \
  | jq

Additional API routes

The following POST /additional/* routes provide optional breach, leak, security-score, and technology-stack lookups:

• /additional/breaches
• /additional/leaks
• /additional/security-score
• /additional/tech-stack
• /additional/all

Set a server key before startup:

export THEHARVESTER_API_KEY='replace-with-a-long-random-value'
uv run restfulHarvest

Send that value in X-API-Key:

curl -s http://127.0.0.1:5000/additional/tech-stack \
  -X POST \
  -H "X-API-Key: $THEHARVESTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com"}' \
  | jq

These routes may also require provider credentials in the request body or local configuration. Consult /docs for the current schema.

Security boundary

THEHARVESTER_API_KEY protects /additional/*, /runs*, and /query selections that include a configured hibpverified source. Other /query requests, /sources, and /dnsbrute remain unauthenticated.

Keep the default localhost binding. If you require remote access, add authentication, network allowlists, TLS, request logging, and an appropriate rate limit.

The supplied Docker Compose configuration binds host port 5000 on every interface unless you narrow the mapping.