Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/samkit511/SAW---Security-Analyst-Workspace/llms.txt

Use this file to discover all available pages before exploring further.

POST /assistant/request is the unified orchestration interface for SAW. It accepts three distinct request types — log triage, incident follow-up, and task management — and routes each through the appropriate agent workflow. Use this endpoint when you need fine-grained control over the request type, user context, or session state that /ingest-log does not expose.

​
Authentication

Include your API key in the x-api-key request header. The default key for local development is demo. 
x-api-key: <your-api-key>

​
Request

Headers
​
x-api-key
string
required
API key for authentication. Requests without a valid key return 401 unauthorized.
Body
​
request_type
string
required
Determines which agent workflow to execute. Must be one of:
  • "log_triage" — analyze and classify a security log
  • "incident_followup" — add context or notes to an existing incident
  • "task_command" — create, complete, or list analyst tasks
​
payload
object
required
Request-type-specific data. See the examples below for the expected shape of each type.
​
user_id
string
default:"demo"
Identifier of the user or system submitting the request. Stored on the incident record and used for session scoping.
​
session_id
string
Optional session identifier for grouping related requests. When provided, the coordinator agent can maintain context across multiple calls in the same session.

​
Examples by request type

​
log_triage

Submits a raw or structured log for the full four-agent triage pipeline. The payload field accepts the same structured fields as /ingest-log. 
curl -X POST https://your-saw-host/assistant/request \
  -H "x-api-key: demo" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "log_triage",
    "user_id": "analyst-01",
    "payload": {
      "ip": "10.0.0.4",
      "method": "GET",
      "path": "/<script>alert(1)</script>",
      "source": "waf_edge_node"
    }
  }'

​
incident_followup

Adds a follow-up message to an existing incident. The RiskAgent re-evaluates whether further action is needed based on the message, and a task may be created. 
curl -X POST https://your-saw-host/assistant/request \
  -H "x-api-key: demo" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "incident_followup",
    "user_id": "analyst-01",
    "payload": {
      "incident_id": "inc_7f8e9d0c1b2a",
      "message": "Confirmed malicious source. Please escalate and block the IP range."
    }
  }'

​
task_command

Manages analyst tasks directly through the agent pipeline. Supports "create", "complete", and "list" actions. 
curl -X POST https://your-saw-host/assistant/request \
  -H "x-api-key: demo" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "task_command",
    "user_id": "analyst-01",
    "payload": {
      "action": "create",
      "title": "Block 10.0.0.4 at perimeter firewall",
      "description": "Confirmed XSS probe from this IP. Block at edge and verify no lateral movement.",
      "incident_id": "inc_7f8e9d0c1b2a",
      "priority": "HIGH"
    }
  }'
Payload fields for task_command
​
payload.action
string
Task operation to perform: "create", "complete", or "list".
​
payload.title
string
Task title. Required when action is "create".
​
payload.description
string
Detailed task description. Required when action is "create".
​
payload.incident_id
string
Links the task to a specific incident. Optional for "create" and "list".
​
payload.priority
string
default:"MEDIUM"
Task priority. Accepted values: "LOW", "MEDIUM", "HIGH".

​
Response

On success the server returns 200 with the full decorated agent result. 
{
  "system_name": "Multi-Agent Security Operations Assistant",
  "request_id": "req_9c8d7e6f5a4b",
  "incident_id": "inc_3b2a1c0d9e8f",
  "request_type": "log_triage",
  "summary": "XSS detected (Risk: 1.17) -> Decision: OBSERVE -> Analyst task created for 10.0.0.4.",
  "agent_summary": [
    "DetectionAgent identified XSS using deterministic with deterministic proof.",
    "RiskAgent kept deterministic authority and selected OBSERVE.",
    "MitigationAgent created 1 follow-up task(s).",
    "AuditAgent persisted the incident workspace, task state, and agent collaboration trail."
  ],
  "workflow_status": "COMPLETED",
  "agent_results": {
    "DetectionAgent": { "status": "COMPLETED", "step": "detect", "message": "Analyzed log and classified threat as XSS." },
    "RiskAgent": { "status": "COMPLETED", "step": "assess", "message": "Evaluated risk and produced decision OBSERVE." },
    "MitigationAgent": { "status": "COMPLETED", "step": "act", "message": "Created analyst investigation task for observed incident." },
    "AuditAgent": { "status": "COMPLETED", "step": "record", "message": "Persisted incident workspace, tasks, actions, and agent runs." }
  },
  "trace": {
    "authoritative_source": "deterministic_agents_with_adk_low_confidence_review",
    "stage_3b_adk_agent_review": {
      "status": "SKIPPED",
      "adk_status": "skipped",
      "influenced_outcome": false
    }
  },
  "meta": {
    "trace_id": "req_9c8d7e6f5a4b",
    "schema_version": "2.0.0",
    "mode": "HYBRID",
    "timestamp": 1748124900.456,
    "system_metrics": { "latency_ms": 68, "pipeline_success": true },
    "feature_flags": { "adk_advisory": true, "escalation": true }
  }
}
​
request_id
string
required
Unique request identifier prefixed with req_.
​
incident_id
string
required
Identifier of the incident record associated with this request. For incident_followup and task_command types, this is the incident ID passed in the payload.
​
workflow_status
string
required
"COMPLETED" if all agents ran without error. "DEGRADED" if an agent failure was caught mid-pipeline.
​
agent_summary
string[]
required
Narrative summary list, one entry per agent that executed.
​
agent_results
object
Per-agent outcome objects keyed by agent name. Each entry contains status, step, message, and output.
​
trace
object
Full execution trace with stages for input normalization, log analysis, threat detection, risk assessment, ADK review, mitigation, and agent orchestration metadata.
​
meta
object
Decorator metadata. See GET /latest for the full field list.

​
Error codes

StatusCodeDescription
400invalid_request_typeThe request_type is not "log_triage", "incident_followup", or "task_command".
401unauthorizedThe x-api-key header is missing or incorrect.
413payload_too_largeThe request body exceeds ASA_MAX_REQUEST_BYTES (default: 16 384 bytes).
422invalid_assistant_payloadThe request body is valid JSON but fails AssistantRequest schema validation.
429rate_limitedThis IP has exceeded 12 requests within the 60-second window. The response includes retry_after_seconds.
503overloadedThe server has reached ASA_MAX_INFLIGHT (default: 8) concurrent requests. Retry after 1 second.

Build docs developers (and LLMs) love

Get started for freeTalk to us