# Bot Intelligence API

Centralized bot-blocking telemetry server for the InformatiQ Toolkit WordPress plugin.

## Quick start

```bash
cp .env.example .env
# Edit .env and set a strong API_TOKEN
docker compose up -d
```

Dashboard available at `http://your-server:3001/`

## API Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/submit` | Bearer token | Submit a batch of bot events (max 50) |
| GET | `/api/v1/stats` | — | Aggregated statistics (cached 30s) |
| GET | `/api/v1/stream` | — | SSE live event stream |
| GET | `/api/v1/health` | — | Health check |

## Submit payload

```json
{
  "site_hash": "sha256-of-home-url",
  "bots": [
    {
      "ip": "1.2.3.4",
      "bot_type": "malicious_bot",
      "action": "blocked",
      "reason": "Malicious bot detected",
      "user_agent": "BadBot/1.0",
      "request_uri": "/wp-login.php",
      "logged_at": "2026-01-01 12:00:00"
    }
  ]
}
```

`action` is one of: `blocked`, `rate_limited`

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3001` | Listen port |
| `DB_PATH` | `/data/bots.db` | SQLite database path |
| `API_TOKEN` | _(empty)_ | Bearer token (leave empty for open/dev mode) |