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.

The task management endpoints give you direct REST access to the SAW task store. You can list all tasks (optionally filtered by incident or status), create a new task with a title, description, priority, and owner, and mark any open task as completed. Tasks are also created automatically by the agent pipeline — for example, when MitigationAgent responds to a detected threat with an OBSERVE decision — so these endpoints let you query and act on tasks that originate from either source.

​
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>

​
GET /tasks

Returns the list of tasks stored in SAW. You can narrow the results by incident ID, by status, or by both at once. Headers
​
x-api-key
string
required
API key for authentication. Requests without a valid key return 401 unauthorized.
Query parameters
​
incident_id
string
Filter tasks to those linked to a specific incident. When omitted, tasks from all incidents are returned.
​
status
string
Filter tasks by status. Accepted values: "OPEN" or "COMPLETED". When omitted, tasks with any status are returned.
Examples All tasks: 
curl https://your-saw-host/tasks \
  -H "x-api-key: demo"
Tasks for a specific incident that are still open: 
curl "https://your-saw-host/tasks?incident_id=inc_7f8e9d0c1b2a&status=OPEN" \
  -H "x-api-key: demo"
Response 
{
  "tasks": [
    {
      "id": "task_abc123def456",
      "incident_id": "inc_7f8e9d0c1b2a",
      "title": "Block 10.0.0.4 at perimeter firewall",
      "description": "Confirmed XSS probe from this IP. Block at edge and verify no lateral movement.",
      "status": "OPEN",
      "priority": "HIGH",
      "owner": "analyst",
      "source_agent": "MitigationAgent",
      "created_at": 1748124800.123,
      "updated_at": 1748124800.123,
      "completed_at": null
    }
  ]
}
​
tasks
object[]
required
Array of task objects. Empty array when no tasks match the query.

​
POST /tasks

Creates a new task in SAW. The task is written to the database immediately and returned in the response body. Headers
​
x-api-key
string
required
API key for authentication. Requests without a valid key return 401 unauthorized.
Body
​
title
string
required
Short summary of the action to be taken (e.g., "Block 10.0.0.4 at perimeter firewall").
​
description
string
required
Full details of what the analyst needs to do.
​
incident_id
string
Links this task to an existing incident. When omitted, the task is created without an incident association.
​
priority
string
default:"MEDIUM"
Task urgency level. Accepted values: "LOW", "MEDIUM", "HIGH".
​
owner
string
default:"analyst"
The analyst or team responsible for completing the task.
Example 
curl -X POST https://your-saw-host/tasks \
  -H "x-api-key: demo" \
  -H "Content-Type: application/json" \
  -d '{
    "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",
    "owner": "analyst"
  }'
Response The server returns the created task object directly (not wrapped in a tasks array). 
{
  "id": "task_abc123def456",
  "incident_id": "inc_7f8e9d0c1b2a",
  "title": "Block 10.0.0.4 at perimeter firewall",
  "description": "Confirmed XSS probe from this IP. Block at edge and verify no lateral movement.",
  "status": "OPEN",
  "priority": "HIGH",
  "owner": "analyst",
  "source_agent": "TaskAPI",
  "created_at": 1748124800.123,
  "updated_at": 1748124800.123,
  "completed_at": null
}
​
id
string
required
Unique task identifier prefixed with task_.
​
incident_id
string
The incident this task is linked to, or null when none was provided.
​
title
string
required
The title you submitted.
​
description
string
required
The description you submitted.
​
status
string
required
Always "OPEN" on a newly created task.
​
priority
string
required
The priority you submitted, or "MEDIUM" if you did not provide one.
​
owner
string
required
The owner you submitted, or "analyst" if you did not provide one.
​
source_agent
string
required
Always "TaskAPI" for tasks created through this endpoint.
​
created_at
float
required
Unix timestamp (seconds) when the task was created.
​
updated_at
float
required
Unix timestamp (seconds) of the most recent update. Equal to created_at on a new task.
​
completed_at
float
Always null on a newly created task.

​
POST /tasks//complete

Marks a task as completed. The server sets status to "COMPLETED", records the current time in completed_at, and returns the updated task object. Headers
​
x-api-key
string
required
API key for authentication. Requests without a valid key return 401 unauthorized.
Path parameters
​
task_id
string
required
The id of the task to complete (e.g., "task_abc123def456"). Returns 404 task_not_found if this ID does not exist.
Example 
curl -X POST https://your-saw-host/tasks/task_abc123def456/complete \
  -H "x-api-key: demo"
Response 
{
  "id": "task_abc123def456",
  "incident_id": "inc_7f8e9d0c1b2a",
  "title": "Block 10.0.0.4 at perimeter firewall",
  "description": "Confirmed XSS probe from this IP. Block at edge and verify no lateral movement.",
  "status": "COMPLETED",
  "priority": "HIGH",
  "owner": "analyst",
  "source_agent": "MitigationAgent",
  "created_at": 1748124800.123,
  "updated_at": 1748125200.456,
  "completed_at": 1748125200.456
}
​
status
string
required
Always "COMPLETED" after a successful call to this endpoint.
​
completed_at
float
required
Unix timestamp (seconds) recorded at the moment you called this endpoint.
​
updated_at
float
required
Set to the same value as completed_at.

​
Error codes

StatusCodeDescription
401unauthorizedThe x-api-key header is missing or incorrect.
404task_not_foundThe task_id path parameter does not match any task in the database. Returned only by POST /tasks/{task_id}/complete.
413payload_too_largeThe request body exceeds ASA_MAX_REQUEST_BYTES (default: 16 384 bytes). Returned only by POST /tasks.
422invalid_task_payloadThe request body is valid JSON but fails TaskCreateRequest schema validation (e.g., missing required title or description). Returned only by POST /tasks.

Build docs developers (and LLMs) love

Get started for freeTalk to us