ThreatLab REST API — Endpoints and Response Reference

ThreatLab’s REST API gives you programmatic control over exercise sessions, noise log dispatch, real-time platform health, and health checks. All endpoints are served from the same origin as the ThreatLab web app — no separate API subdomain. Replace https://threatlab.your-org.com with your actual ThreatLab instance URL in all examples below.

Endpoints

Method	Endpoint	Description
POST	`/api/sessions/start`	Ship a signed archive to a SIEM
DELETE	`/api/sessions`	Wipe one or more SIEM indexes
POST	`/api/noise/run`	Execute a noise log dispatch job
GET	`/api/platform-status/events`	SSE stream of Icinga health events
GET	`/api/health`	Unauthenticated health check

Authentication

ThreatLab uses two authentication mechanisms depending on the caller:

Session cookie — used by the browser and web UI for all routes except POST /api/noise/run.
Bearer token — accepted only on POST /api/noise/run for pg_cron and automation scripts.

GET /api/health requires no authentication. See the Authentication page for full details.

Response Format

All responses are JSON. Successful responses include "ok": true alongside the result data. Error responses include an "error" string describing the failure.

{ "ok": true, "siem": "Splunk", "driver": "splunk_hec" }

{ "ok": false, "error": "Missing required capability: manage_exercises" }

Error Codes

Status	Meaning
`401`	Not authenticated
`403`	Authenticated but lacks the required capability
`400`	Invalid request body or parameters
`500`	Server error

Endpoint Reference

POST /sessions/start

Ship a signed archive to a SIEM destination. Rebases timestamps and returns event counts.

DELETE /sessions

Wipe log data from one or more SIEM indexes and optionally re-fire noise jobs.

POST /noise/run

Execute a noise log dispatch job manually or via pg_cron automation.

GET /platform-status/events

Subscribe to a real-time SSE stream of Icinga 2 platform health events.

GET /health

Unauthenticated liveness probe for load balancers and uptime monitors.

​Endpoints

​Authentication

​Response Format

​Error Codes

​Endpoint Reference