# REST API

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

## Start the service

```bash
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:

```bash
uv run restfulHarvest --rate-limit 10/minute
```

Open:

- Swagger UI: [http://127.0.0.1:5000/docs](http://127.0.0.1:5000/docs)
- ReDoc: [http://127.0.0.1:5000/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:

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

Run a passive query:

```bash
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:

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

Send that value in `X-API-Key`:

```bash
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.