Cortex API
Plans, kill chains, overrides, fleet sweeps, reasoning chains, and Hive network endpoints.
Plans
- Method — Path — Description
- GET — /api/cortex/plans — List recent plans. Query: limit, status
- GET — /api/cortex/plans/active — Active and paused plans only
- GET — /api/cortex/plans/:id — Full plan with steps, overrides, AI explanation
- POST — /api/v1/cortex/plans/:id/approve — Approve a plan step (API key scope actions:write)
- POST — /api/v1/cortex/plans/:id/deny — Deny a plan step (API key scope actions:write)
- POST — /api/cortex/plans/:id/override — Dashboard, org admins only. Apply an override. Body: { action, stepId?, reason? }, where action is approve / approve_all / deny / pause / resume / cancel / redirect
- POST — /api/cortex/plans/:id/false-positive — Dashboard, org admins only. Mark the plan a false positive
An API key with alerts:read can read plans, the summary, context, kill chains and Hive status, and one with actions:write can approve or deny plan steps with POST /api/v1/cortex/plans/:id/approve or /deny. Routes marked dashboard, org admins only need a signed-in admin session; API keys get 403 there.
Analysis and sweeps
- Method — Path — Description
- POST — /api/cortex/analyze — Dashboard, org admins only. Trigger analysis for a server. Body: { serverId, windowHours } (default 1)
- POST — /api/cortex/sweep — Dashboard, org admins only. Trigger fleet-wide sweep. Body: { windowHours } (default 1)
Both need a signed-in org admin session in the dashboard; API keys cannot start analysis or sweeps.
Kill chains (MITRE ATT&CK)
- Method — Path — Description
- GET — /api/cortex/kill-chains — List active kill chains with MITRE stage tracking
- GET — /api/cortex/kill-chains/:serverId — Kill chain status for a specific server
- POST — /api/cortex/kill-chains/:chainId/resolve — Dashboard, org admins only. Resolve or contain a kill chain
A kill chain is opened when Cortex links several stages of an attack (MITRE ATT&CK tactics) on the same server. Each chain lists the stages seen, how long the attacker has been present, and a recommended next step. A chain, abridged:
{
"id": 42,
"serverId": "4f2a9c1e8b7d6a50",
"hostname": "api-prod",
"currentStage": "privilege_escalation",
"stageCount": 2,
"firstDetectedAt": 1792548912456,
"lastUpdatedAt": 1792551012456,
"dwellTimeMs": 2100000,
"tacticsObserved": ["initial_access", "privilege_escalation"],
"tacticsRemaining": ["defense_evasion", "credential_access", "..."],
"recommendedNextAction": "...",
"timeline": [
{ "ts": 1792548912456, "stage": "initial_access", "label": "...", "evidence": "...", "severity": "high" }
]
}
Summary and context
- Method — Path — Description
- GET — /api/cortex/summary — Org-level stats: activePlans, pendingApprovals, criticalToday
- GET — /api/cortex/context/:serverId — Raw context snapshot (health, network, process, threat and auth)
- GET — /api/cortex/reason/:serverId — Full reasoning chain
- GET — /api/cortex/calibration — Dashboard, org admins only. False-positive rate and confidence calibration stats
Threat sharing
- Method — Path — Description
- GET — /api/cortex/hive/status — Threat-sharing status: warnings inside your own fleet, plus shared indicators if your organization opted in
Warnings between your own servers are always on and stay inside your organization. Sharing between organizations is off unless you opt in (Fleet → Threat intel): organizations that opt in share attacker IP addresses and attack types with each other; your servers and data are never shared. Organizations that have not opted in neither share nor receive.
Cortex and webhooks
Cortex has no webhook events of its own. What it finds arrives as alert.* events (see API: Webhooks). Cortex plan steps waiting for approval are not sent as webhooks; poll /api/cortex/plans/active or /api/cortex/summary (pendingApprovals). Plans and kill chains are read with the endpoints above.
Tips
- Poll GET /api/cortex/summary to drive a SOC dashboard — it returns aggregated stats with a single request.
- To hear about multi-stage attacks, poll GET /api/cortex/kill-chains or subscribe a webhook to alert.critical.
- The reason/:serverId endpoint returns Cortex's full reasoning for a server — useful for audit reports and post-incident reviews.