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

# API Reference — Implementing Anti-Phishing Training Programs

## Agent Script

### Commands

| Command | Description |
|---|---|
| `node agent.js design-campaign --tier <1-4> --department <name> --size <n>` | Design simulation campaign |
| `node agent.js launch-campaign --name <n> --template-id <id> --group-id <id> --send-by-date <iso>` | Launch campaign config |
| `node agent.js campaign-status --campaign-id <id>` | Get campaign metrics |
| `node agent.js export-metrics --campaign-id <id> --format <json\|csv>` | Export campaign results |
| `node agent.js repeat-offenders --threshold <n> --window <days>d` | Find repeat clickers |
| `node agent.js assign-training --user-list <path> --module <name>` | Assign remedial training |

### Examples

```bash
# Design a tier-2 campaign for engineering
node agent.js design-campaign --tier 2 --department engineering --size 50

# Launch a named campaign
node agent.js launch-campaign --name "Q1-2026-Eng" --template-id 1 \
  --group-id 1 --send-by-date "2026-03-20T17:00:00Z"

# Check live campaign metrics
node agent.js campaign-status --campaign-id 1

# Export results as JSON
node agent.js export-metrics --campaign-id 1 --format json

# Find users who clicked in 2+ campaigns within 90 days
node agent.js repeat-offenders --threshold 2 --window 90d
```

## GoPhish API Endpoints

| Endpoint | Method | Purpose |
|---|---|---|
| `/api/campaigns/` | GET | List all campaigns |
| `/api/campaigns/` | POST | Create new campaign |
| `/api/campaigns/{id}` | GET | Campaign details and results |
| `/api/campaigns/{id}/results` | GET | Per-user results |
| `/api/templates/` | GET/POST | Manage email templates |
| `/api/groups/` | GET/POST | Manage target groups |
| `/api/smtp/` | GET/POST | Manage sending profiles |

## Key Metrics

| Metric | Formula | Target |
|---|---|---|
| Click Rate | Clicks / Delivered | < 5% |
| Report Rate | Reports / Delivered | > 60% |
| Time-to-Report | Median(report_time - delivery_time) | < 5 min |
| Repeat Offender Rate | Multi-clickers / Total users | < 2% |
