Skip to main content
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

MethodEndpointDescription
POST/api/sessions/startShip a signed archive to a SIEM
DELETE/api/sessionsWipe one or more SIEM indexes
POST/api/noise/runExecute a noise log dispatch job
GET/api/platform-status/eventsSSE stream of Icinga health events
GET/api/healthUnauthenticated 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

StatusMeaning
401Not authenticated
403Authenticated but lacks the required capability
400Invalid request body or parameters
500Server 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.