API reference

A2A protocol

Inter-agent communication uses JSON-RPC 2.0 over WebSocket (ACP / Agent Communication Protocol). Each agent listens on a dedicated port. The orchestrator dispatches tasks to specialists via ACP HandoffTool, which wraps JSON-RPC 2.0 requests with routing metadata.

Request format

{
  "jsonrpc": "2.0",
  "method": "analyze_threat",
  "params": {
    "alert_id": "ALRT-2026-05821",
    "iocs": [{"type": "ip", "value": "45.33.32.156"}]
  },
  "id": "req-001"
}

Response format

{
  "jsonrpc": "2.0",
  "result": {
    "severity": "high",
    "confidence": 0.89,
    "mitre_techniques": ["T1566.001"],
    "iocs": [{"type": "domain", "value": "evil.example.com"}]
  },
  "id": "req-001"
}

Error format

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": "req-001"
}

REST endpoints

Auth

Method	Path	Description	Permission
GET	/api/v1/auth/providers	List configured auth providers	Public
POST	/api/v1/auth/token	Obtain JWT access token	Public
GET	/api/v1/auth/oidc/login	Initiate OIDC login flow	Public
GET	/api/v1/auth/oidc/callback	OIDC callback handler	Public
GET	/api/v1/auth/saml/login	Initiate SAML login	Public
POST	/api/v1/auth/saml/acs	SAML assertion consumer	Public
POST	/api/v1/auth/logout	Invalidate session	Authenticated
GET	/api/v1/auth/api-keys	List API keys	Authenticated
POST	/api/v1/auth/api-keys	Create API key	Authenticated
DELETE	/api/v1/auth/api-keys/{key_id}	Revoke API key	Authenticated

Users

Method	Path	Description	Permission
GET	/api/v1/users/me	Current user profile	Authenticated
GET	/api/v1/users	List users	Admin
POST	/api/v1/users	Create user	Admin
DELETE	/api/v1/users/{username}	Delete user	Admin

Alerts

Method	Path	Description	Permission
GET	/api/v1/alerts	List alerts	alerts:read
POST	/api/v1/alerts	Create alert	alerts:write
GET	/api/v1/alerts/{alert_id}	Get alert detail	alerts:read
PATCH	/api/v1/alerts/{alert_id}	Update alert	alerts:write
POST	/api/v1/alerts/{alert_id}/acknowledge	Acknowledge alert	alerts:write
POST	/api/v1/alerts/{alert_id}/promote	Promote alert to case	alerts:write
POST	/api/v1/alerts/{alert_id}/case-link	Link alert to existing case	alerts:write

Cases

Method	Path	Description	Permission
GET	/api/v1/cases	List cases	cases:read
POST	/api/v1/cases	Create case	cases:write
GET	/api/v1/cases/{case_id}	Get case detail	cases:read
PATCH	/api/v1/cases/{case_id}	Update case	cases:write
DELETE	/api/v1/cases/{case_id}	Delete case	cases:write
GET	/api/v1/cases/{case_id}/observables	List observables	cases:read
POST	/api/v1/cases/{case_id}/observables	Add observable	cases:write
GET	/api/v1/cases/{case_id}/evidence	List evidence	cases:read
POST	/api/v1/cases/{case_id}/evidence	Add evidence	cases:write
GET	/api/v1/cases/{case_id}/evidence/{evidence_id}/custody	Custody chain	cases:read
GET	/api/v1/cases/{case_id}/evidence/{evidence_id}/ledger	Evidence ledger	cases:read
GET	/api/v1/cases/{case_id}/comments	List comments	cases:read
POST	/api/v1/cases/{case_id}/comments	Add comment	cases:write
GET	/api/v1/cases/{case_id}/tasks	List tasks	cases:read
POST	/api/v1/cases/{case_id}/tasks	Create task	cases:write
PATCH	/api/v1/cases/{case_id}/tasks/{task_id}	Update task	cases:write

SIEM / Detection

Method	Path	Description	Permission
GET	/api/v1/siem/logs	Search SIEM logs	siem:read
POST	/api/v1/siem/logs/ingest	Ingest log entry	siem:write
GET	/api/v1/siem/hunts	List hunt queries	siem:read
POST	/api/v1/siem/hunts	Create hunt query	siem:write
PATCH	/api/v1/siem/hunts/{hunt_id}	Update hunt query	siem:write
POST	/api/v1/siem/hunts/{hunt_id}/run	Run hunt query	siem:write
GET	/api/v1/detections/rules	List detection rules	siem:read
POST	/api/v1/detections/rules	Create detection rule	siem:write
PATCH	/api/v1/detections/rules/{rule_id}	Update detection rule	siem:write
POST	/api/v1/detections/rules/{rule_id}/run	Run detection rule	siem:write
GET	/api/v1/detections/rules/{rule_id}/runs	List rule runs	siem:read
GET	/api/v1/detections/metrics	Detection metrics	siem:read
GET	/api/v1/detections/rules/{rule_id}/suppressions	List suppressions	siem:read
POST	/api/v1/detections/rules/{rule_id}/suppressions	Create suppression	siem:write
GET	/api/v1/detections/rules/{rule_id}/feedback	List feedback	siem:read
POST	/api/v1/detections/rules/{rule_id}/feedback	Submit feedback	siem:write
POST	/api/v1/siem/logs/{log_id}/promote	Promote log to rule	siem:write
GET	/api/v1/siem/sources	List log sources	siem:read
GET	/api/v1/siem/stats	SIEM statistics	siem:read

EDR

Method	Path	Description	Permission
GET	/api/v1/edr/endpoints	List endpoints	edr:read
GET	/api/v1/edr/endpoints/{endpoint_id}	Endpoint detail	edr:read
POST	/api/v1/edr/endpoints/{endpoint_id}/isolate	Isolate endpoint	edr:write
POST	/api/v1/edr/endpoints/{endpoint_id}/unisolate	Release endpoint	edr:write
POST	/api/v1/edr/endpoints/{endpoint_id}/scan	Scan endpoint	edr:write
GET	/api/v1/edr/stats	EDR statistics	edr:read

SOAR / Playbooks

Method	Path	Description	Permission
GET	/api/v1/playbooks	List playbooks	playbooks:read
GET	/api/v1/soar/playbooks	List SOAR playbooks	soar:read
POST	/api/v1/soar/playbooks	Create SOAR playbook	soar:write
GET	/api/v1/soar/playbooks/{playbook_id}	Playbook detail	soar:read
POST	/api/v1/soar/playbooks/{playbook_id}/toggle	Toggle playbook	soar:write
POST	/api/v1/soar/playbooks/{playbook_id}/execute	Execute playbook	soar:write
GET	/api/v1/soar/executions	List executions	soar:read
GET	/api/v1/soar/rules	List automation rules	soar:read
POST	/api/v1/soar/rules	Create automation rule	soar:write
POST	/api/v1/soar/rules/{rule_id}/toggle	Toggle rule	soar:write
DELETE	/api/v1/soar/rules/{rule_id}	Delete rule	soar:write

Investigations

Method	Path	Description	Permission
GET	/api/v1/investigations	List investigations	investigations:read
GET	/api/v1/investigations/{investigation_id}	Investigation detail	investigations:read
POST	/api/v1/agents/investigate	Dispatch investigation	investigations:write
POST	/api/v1/orchestrator/dispatch	Orchestrator dispatch	investigations:write
GET	/api/v1/orchestrator/history	Dispatch history	investigations:read

Network

Method	Path	Description	Permission
GET	/api/v1/network-attacks	List network attacks	network:read
GET	/api/v1/network-attacks/{attack_id}	Attack detail	network:read
POST	/api/v1/network-attacks/{attack_id}/case	Promote to case	network:write
POST	/api/v1/network-attacks/{attack_id}/dispatch	Dispatch response	network:write
GET	/api/v1/network-telemetry/status	Telemetry status	network:read
POST	/api/v1/network-telemetry/ingest	Ingest telemetry	network:write
GET	/api/v1/settings/network-telemetry	Telemetry config	network:read
PUT	/api/v1/settings/network-telemetry	Update telemetry config	network:write
GET	/api/v1/settings/network-telemetry/history	Config history	network:read
POST	/api/v1/settings/network-telemetry/history/{history_id}/rollback	Rollback config	network:write
GET	/api/v1/network-telemetry/coverage	Attack coverage map	network:read
GET	/api/v1/network-security/findings	Network findings	network:read
POST	/api/v1/network-security/analyze	Analyse network data	network:write
GET	/api/v1/network-security/status	Network security status	network:read

Agent Fleet

Method	Path	Description	Permission
GET	/api/v1/agents/{agent_id}/tools	List agent tools	agents:read
GET	/api/v1/agents/{agent_id}/tool-calls	List agent tool calls	agents:read
GET	/api/v1/mcp/health	MCP server health	agents:read
GET	/api/v1/inference/status	Inference backend status	agents:read

Chat

Method	Path	Description	Permission
POST	/api/v1/chat/completions	Chat completion	chat:write
POST	/api/v1/chat/stream	Stream chat response (SSE)	chat:read
GET	/api/v1/chat/sessions	List chat sessions	chat:read
POST	/api/v1/chat/sessions	Create chat session	chat:write
GET	/api/v1/chat/sessions/{session_id}	Get chat session	chat:read
DELETE	/api/v1/chat/sessions/{session_id}	Delete chat session	chat:write

Both chat endpoints are rate limited per user (HTTP 429, AURORA-4290, with Retry-After when exceeded). User input is neutralized and any pasted or grounding data is fenced as untrusted before it reaches the model, and responses are scrubbed for secrets and system-prompt leakage. The streaming endpoint emits a report_generated event (or report_error on a malformed request) when the model returns a %%REPORT_REQUEST%% marker. See AI chat adversarial defense.

System

Method	Path	Description	Permission
GET	/api/v1/settings/runtime	Runtime configuration	system:read
PATCH	/api/v1/settings/runtime	Update runtime config	system:write
GET	/metrics	Prometheus metrics	Authenticated

WebSocket

Method	Path	Description	Permission
WS	/api/v1/ws/alerts	Real-time alert stream	Authenticated
WS	/api/v1/ws/agent-thoughts	Agent reasoning stream	Authenticated
WS	/api/v1/ws/investigation-receipts	Investigation result stream	Authenticated
WS	/api/v1/ws/agents/{agent_id}/tool-calls	Agent tool call stream	Authenticated
WS	/api/v1/ws/approvals	Human approval notifications	Authenticated

Error codes

All errors follow a consistent envelope. The code field uses the AURORA-XXXX taxonomy, where the first three digits mirror the HTTP status code.

Code	HTTP Status	Message
AURORA-4010	401	Authentication required
AURORA-4011	401	Token expired
AURORA-4012	401	Invalid credentials
AURORA-4030	403	Insufficient permissions
AURORA-4031	403	Action denied by guardrail policy
AURORA-4040	404	Resource not found
AURORA-4041	404	Case not found
AURORA-4042	404	Alert not found
AURORA-4043	404	Agent not found
AURORA-4080	408	Human approval timed out
AURORA-4090	409	Resource conflict
AURORA-4091	409	Duplicate alert
AURORA-4220	422	Validation error
AURORA-4221	422	Playbook validation failed
AURORA-4222	422	Sigma rule validation failed
AURORA-4290	429	Rate limit exceeded
AURORA-5000	500	Internal server error
AURORA-5030	503	Service temporarily unavailable
AURORA-5031	503	LLM inference service unavailable
AURORA-5032	503	ClickHouse service unavailable

Error response envelope

{
  "error": {
    "code": "AURORA-4041",
    "message": "Case not found",
    "detail": null,
    "timestamp": "2026-06-14T12:00:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

API versioning headers

Every response includes these headers:

Header	Value	Description
X-API-Version	1.0	Current API version
X-Request-ID	uuid	Unique request identifier for tracing
X-AuroraSOC-Mode	dry_run | monitor | active	System operation mode

Deprecated routes return additional headers:

Header	Example	Description
Deprecation	true	Indicates the route is deprecated
Sunset	2026-12-31T00:00:00Z	ISO 8601 date when the route will be removed

Clients should monitor the Deprecation header and migrate before the Sunset date. The X-API-Version header allows clients to gate feature availability checks without inspecting the response body.