REST API Reference

Base URL & Authentication

All API requests are made to your HailBytes SAT instance over HTTPS:

https://<your-sat-host>:3333/api/...

Every authenticated endpoint requires an API key, retrievable from Settings → API Key in the dashboard. Pass it as a Bearer token:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Public Endpoints (No Auth)

Campaigns

GET    /api/campaigns/                              # List campaigns
POST   /api/campaigns/                              # Create & launch
GET    /api/campaigns/summary                       # Tile summary
GET    /api/campaigns/{id}                          # Get one
DELETE /api/campaigns/{id}                          # Delete
GET    /api/campaigns/{id}/results                  # Per-target results
GET    /api/campaigns/{id}/outcomes                 # Outcome breakdown
GET    /api/campaigns/{id}/summary                  # Aggregated stats
GET    /api/campaigns/{id}/events                   # Raw event timeline
GET    /api/campaigns/{id}/complete                 # Mark complete
POST   /api/campaigns/{id}/clicker-group            # Build group from clickers
POST   /api/campaigns/{id}/submit-review            # Send for approval (4-eyes)
POST   /api/campaigns/{id}/approve
POST   /api/campaigns/{id}/reject
GET    /api/recurring_campaigns/                    # Scheduled / recurring
GET    /api/recurring_campaigns/{id}

See the first-campaign tutorial for a full create-and-launch example.

Templates, Landing Pages, Groups

GET    /api/templates/         POST /api/templates/
GET    /api/templates/{id}     PUT  /api/templates/{id}     DELETE /api/templates/{id}

GET    /api/pages/             POST /api/pages/
GET    /api/pages/{id}         PUT  /api/pages/{id}         DELETE /api/pages/{id}

GET    /api/groups/            POST /api/groups/
GET    /api/groups/summary     GET  /api/groups/{id}/summary
GET    /api/groups/{id}        PUT  /api/groups/{id}        DELETE /api/groups/{id}

POST   /api/import/group       # Bulk-import targets (CSV body)
POST   /api/import/email       # Import an .eml file as a template
POST   /api/import/site        # Clone a remote site into a landing page
POST   /api/import/azure-ad    # Pull a group from Azure AD / Entra ID

Sending Profiles & Mail Server

GET    /api/smtp/                                   # List sending profiles
POST   /api/smtp/                                   # Create
POST   /api/smtp/test                               # Validate config
GET    /api/smtp/{id}                               # Get one
PUT    /api/smtp/{id}                               # Update
DELETE /api/smtp/{id}                               # Delete
POST   /api/util/send_test_email                    # Send a one-off test

# Built-in mail server (admin)
GET    /api/mailserver/status
GET    /api/mailserver/config       PUT /api/mailserver/config
POST   /api/mailserver/control                      # start / stop / restart
GET    /api/mailserver/logs
POST   /api/mailserver/create-profile               # Auto-create a sending profile

# Inbound IMAP (phish reporting)
GET    /api/imap/                   PUT /api/imap/
POST   /api/imap/validate

Training Modules, Tracks & Certificates

GET    /api/training_modules/                       POST   /api/training_modules/
GET    /api/training_modules/{id}                   PUT    /api/training_modules/{id}     DELETE ...
GET    /api/training_modules/{id}/question_stats

GET    /api/training/stats                          # Training Dashboard summary
GET    /api/training/tracks/                        POST   /api/training/tracks/
GET    /api/training/tracks/stats
GET    /api/training/tracks/{id}                    PUT    /api/training/tracks/{id}      DELETE ...
GET    /api/training/tracks/{id}/modules

GET    /api/training/completions/
POST   /api/training/completions/{id}/certificate   # Issue a PDF certificate
GET    /api/training/completions/{id}/responses

GET    /api/training/certificates/
GET    /api/training/certificates/{id}
GET    /api/training/certificates/{id}/download     # Returns PDF

Risk Scoring & Auto-Enroll

GET    /api/training/risk/top                       # Top repeat clickers
GET    /api/training/risk/export.csv                # CSV download
GET    /api/targets/{id}/risk                       # Per-target risk score
GET    /api/risk/repeat-offenders
POST   /api/risk/recompute                          # Force a recalculation
GET    /api/risk/auto_enroll                        POST /api/risk/auto_enroll
GET    /api/risk/auto_enroll/{id}                   PUT  /api/risk/auto_enroll/{id}    DELETE ...
POST   /api/risk/auto_enroll/run                    # Manual trigger

# Remedial training assignment rules
GET    /api/remedial_training/rules/                POST /api/remedial_training/rules/
GET    /api/remedial_training/rules/{id}            PUT  ...                            DELETE ...
GET    /api/remedial_training/assignments/

Phish Triage Queue

GET    /api/triage                                  # List user-reported phishes
GET    /api/triage/accuracy                         # Reporter accuracy stats
GET    /api/triage/{id}                             # Get one report
PUT    /api/triage/{id}                             # Classify / annotate
DELETE /api/triage/{id}

Reports & Analytics (Admin)

GET    /api/reports/executive                       # Branded executive report (PDF/JSON)
GET    /api/reports/trends                          # 12w / 26w threat-trend
GET    /api/reports/cohorts                         # Cohort analysis
GET    /api/reports/time_to_click                   # Time-to-click distribution
GET    /api/reports/templates                       # Template effectiveness
GET    /api/reports/repeat_clickers                 # Repeat-clicker watchlist
GET    /api/reports/training_vs_click               # Training-vs-click scatter

Webhooks & Integrations

GET    /api/webhooks/                               POST /api/webhooks/
GET    /api/webhooks/{id}                           PUT  /api/webhooks/{id}      DELETE ...
POST   /api/webhooks/{id}/validate
GET    /api/webhooks/{id}/deliveries
POST   /api/webhooks/{id}/deliveries/{delivery_id}/replay

GET    /api/webhook_deliveries/dead                 # Dead-letter queue
POST   /api/webhook_deliveries/{id}/revive

# SIEM / SOAR
GET / PUT /api/integrations/splunk      POST /api/integrations/splunk/test
GET / PUT /api/integrations/sentinel    POST /api/integrations/sentinel/test

Users, Roles & Organizations (Admin)

GET    /api/users/                                  POST /api/users/
GET    /api/users/{id}                              PUT  /api/users/{id}        DELETE ...
POST   /api/users/{id}/invite
POST   /api/users/{id}/api_key/reset
GET    /api/users/{id}/export                       # Per-user data export

GET    /api/roles/                                  PUT  /api/roles/

GET    /api/organizations/                          POST /api/organizations/
GET    /api/organizations/{id}                      PUT  /api/organizations/{id}    DELETE ...
GET    /api/organizations/{id}/members              POST /api/organizations/{id}/members
GET    /api/organizations/{id}/members/{user_id}    PUT  ...                        DELETE ...

Auth: SSO, SAML, MFA

# OIDC SSO providers
GET / POST /api/sso/                                # List / create
GET / PUT  /api/sso/{provider}                      # Get / update one
DELETE     /api/sso/{provider}

# SAML
GET / PUT /api/saml/config

# Browser-side SAML/SSO endpoints (not under /api/)
GET    /sso/login/{provider}        GET /sso/callback/{provider}
GET    /sso/saml/metadata           POST /sso/saml/acs        GET /sso/saml/login

# MFA / TOTP
GET    /api/mfa/status
POST   /api/mfa/setup
POST   /api/mfa/verify-setup
POST   /api/mfa/verify
POST   /api/mfa/disable
POST   /api/mfa/regenerate-backup-codes

SCIM 2.0 Provisioning

SCIM endpoints sit under /scim/v2/ (not /api/) and accept the standard SCIM application/scim+json content type.

GET    /scim/v2/ServiceProviderConfig
GET    /scim/v2/Schemas
GET    /scim/v2/ResourceTypes
GET    /scim/v2/Users                               POST /scim/v2/Users
GET    /scim/v2/Users/{id}                          PUT  /scim/v2/Users/{id}    PATCH ...   DELETE ...

Branding (White-Label)

GET    /api/branding                                PUT /api/branding
POST   /api/branding/reset
PUT    /api/branding/logo                           PUT /api/branding/favicon
GET    /api/branding/logo/view                      GET /api/branding/favicon/view  # Public

AI Settings & Generation

GET / PUT /api/ai/settings
POST      /api/ai/test
POST      /api/ai/generate-summary                  # Campaign / report summary
GET       /api/ai/summary/{id}                      # Cached summary
GET       /api/ai/models
POST      /api/ai/generate-template                 # AI-authored phishing template

Compliance

GET    /api/compliance/frameworks                   # Supported frameworks
GET    /api/compliance/coverage                     # Per-control coverage map
GET    /api/compliance/evidence                     # Evidence bundle (admin)

Audit, Privacy, Anonymization

GET    /api/audit                                   # Search audit logs
GET    /api/audit/export                            # CSV / JSON export
GET    /api/audit/stats
GET / PUT /api/audit/retention                      # Retention policy
POST   /api/audit/cleanup

GET / PUT /api/privacy                              # Data-handling settings
POST   /api/anonymization/run                       # Bulk-anonymize old PII

Certificates & Server Control

GET    /api/certificates/                           POST /api/certificates/
POST   /api/certificates/check-port                 # Verify port 80 reachability
GET    /api/certificates/{id}                       PUT  /api/certificates/{id}     DELETE ...
POST   /api/certificates/{id}/generate              # ACME issue
POST   /api/certificates/{id}/renew
POST   /api/certificates/reset

POST   /api/server/restart
GET    /api/server/status

GET / PUT /api/security                             # Security policy

Tutorial / Onboarding

POST   /api/tutorial/complete                       # Mark in-app tour complete
POST   /api/tutorial/reset                          # Replay the tour

Test Data (Demo / QA)

GET    /api/testdata/options
POST   /api/testdata/generate                       # Seed deterministic dataset
GET    /api/testdata/status
POST   /api/testdata/cleanup
POST   /api/testdata/demo_campaign

MCP Endpoint

The MCP server is mounted at /api/mcp/ and uses Streamable HTTP. See the MCP reference for the full tool catalog and client setup.

Errors

Errors are returned as JSON:

{
  "message": "Human-readable error description",
  "success": false,
  "data": null
}

Live Spec

Every running instance serves an OpenAPI spec at /api/docs/openapi.yaml and an interactive Swagger UI at /api/docs. Generate clients with openapi-generator-cli against that file.

Next Steps