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.

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

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 only /additional/*. It does not authenticate /query, /sources, or /dnsbrute.

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.