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 /ingest-log is the main entry point for feeding raw security events into SAW. You can send a structured JSON object with individual fields (IP address, HTTP method, path, payload) or post a plain-text log line directly. Either way, the server runs the full four-agent triage pipeline and returns a decorated result with the threat classification, decision, and any mitigation actions taken.

​
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.
​
x-event-id
string
Optional idempotency key for replay prevention. If a request with the same x-event-id arrives within 30 seconds of a prior request, the server returns 409 replay_detected without re-processing the log. You can also set this field inside the JSON body as event_id.
​
Content-Type
string
Set to application/json when sending structured log fields. Omit or use any other value to send a plain-text log body.
Body — structured JSON
​
ip
string
Source IP address of the event (e.g., "192.168.1.55").
​
method
string
HTTP method associated with the event (e.g., "POST"). Normalized to uppercase.
​
path
string
Request path associated with the event (e.g., "/api/login").
​
payload
string
Body or parameter string from the original request (e.g., "username=admin' OR 1=1--").
​
raw
string
A pre-formatted raw log string. When present, all other structured fields are ignored and this string is used as the triage input.
​
source
string
default:"assistant_api"
Label identifying the upstream system that submitted the log. Stored on the incident record for audit purposes.
​
event_id
string
Idempotency key for replay prevention. Equivalent to the x-event-id header; the body field takes precedence if both are provided.
Body — plain text If the request Content-Type is not application/json, the entire body is treated as a raw log string. The server sets source to "web_app_login_endpoint" automatically.

​
Examples

Structured JSON log 
curl -X POST https://your-saw-host/ingest-log \
  -H "x-api-key: demo" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.168.1.55",
    "method": "POST",
    "path": "/api/login",
    "payload": "username=admin'\''--&password=x",
    "source": "web_app_login_endpoint"
  }'
Plain text raw log 
curl -X POST https://your-saw-host/ingest-log \
  -H "x-api-key: demo" \
  -H "Content-Type: text/plain" \
  --data-raw "ip=203.0.113.42 method=GET path=/etc/passwd payload=../../../../etc/passwd"

​
Response

On success the server returns 200 with the decorated triage result. 
{
  "system_name": "Multi-Agent Security Operations Assistant",
  "request_id": "req_4a1b2c3d4e5f",
  "incident_id": "inc_7f8e9d0c1b2a",
  "request_type": "log_triage",
  "summary": "SQL Injection detected (Risk: 2.34) -> Decision: EXECUTE -> Mitigation applied to 192.168.1.55.",
  "agent_summary": [
    "DetectionAgent identified SQL Injection using deterministic with deterministic proof.",
    "RiskAgent kept deterministic authority and selected EXECUTE.",
    "MitigationAgent applied 2 control-plane action(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 SQL Injection." },
    "RiskAgent": { "status": "COMPLETED", "step": "assess", "message": "Evaluated risk and produced decision EXECUTE." }
  },
  "trace": {
    "stage_3b_adk_agent_review": {
      "status": "SKIPPED",
      "adk_status": "skipped",
      "adk_enabled": true,
      "influenced_outcome": false
    }
  },
  "meta": {
    "trace_id": "req_4a1b2c3d4e5f",
    "schema_version": "2.0.0",
    "mode": "HYBRID",
    "timestamp": 1748124800.123,
    "system_metrics": {
      "latency_ms": 42,
      "pipeline_success": true
    },
    "feature_flags": {
      "adk_advisory": true,
      "escalation": true
    }
  }
}
​
request_id
string
required
Unique identifier for this request, prefixed with req_. Use this for log correlation and support inquiries.
​
incident_id
string
required
Identifier of the incident record created in the SAW database for this event.
​
workflow_status
string
required
"COMPLETED" if all agents executed without errors. "DEGRADED" if one or more agents failed mid-pipeline; the trace.agent_orchestration.failures array contains details.
​
agent_summary
string[]
required
One sentence per agent in execution order, describing the action each agent took.
​
decision
string
The final triage decision: "EXECUTE" (mitigations applied), "OBSERVE" (analyst task created), or "IGNORE" (logged for reference only).
​
agent_results
object
Per-agent outcome objects keyed by agent name (DetectionAgent, RiskAgent, MitigationAgent, AuditAgent).
​
trace
object
Full multi-stage execution trace including threat detection, risk assessment, ADK review, and mitigation output.
​
meta
object
Decorator metadata including trace_id, schema_version, mode, timestamp, source_ip, model_info, feature_flags, system_metrics, and resilience fields.

​
Error codes

StatusCodeDescription
400empty_logThe request body resolved to an empty string after parsing.
400invalid_jsonThe Content-Type is application/json but the body is not valid JSON.
401unauthorizedThe x-api-key header is missing or incorrect.
409replay_detectedThe event_id (body or header) matches a request seen within the last 30 seconds.
413payload_too_largeThe request body exceeds ASA_MAX_REQUEST_BYTES (default: 16 384 bytes).
422invalid_json_schemaThe body is valid JSON but does not match the IngestLogRequest schema.
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