Skip to main content

​
Update Alert Status

Change the status of an alert during investigation.

​
Endpoint

PATCH /api/alerts/{id}

​
Authentication

Requires JWT token with Analyst or Admin role.
API keys cannot update alerts (read-only by default).

​
Path Parameters

ParameterTypeDescription
idstringAlert UUID

​
Request Body

{
  "status": "acknowledged",
  "comment": "Investigating - appears to be brute force attempt"
}

​
Fields

FieldTypeRequiredDescription
statusstringYesNew status
commentstringNoOptional comment

​
Status Values

StatusMeaning
newReset to unreviewed
acknowledgedMark as under investigation
resolvedMark investigation complete
false_positiveMark as false positive

​
Example Request

curl -X PATCH \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: abc123..." \
  -d '{
    "status": "acknowledged",
    "comment": "Investigating brute force attempt from internal IP"
  }' \
  https://chad.example.com/api/alerts/alert-abc-123

​
Response

{
  "id": "alert-abc-123",
  "status": "acknowledged",
  "acknowledged_at": "2024-01-15T15:00:00Z",
  "acknowledged_by": "analyst@example.com",
  "comment_added": true
}

​
Status Transitions

new → acknowledged → resolved
                  → false_positive

Any status can return to new

​
Bulk Update

Update multiple alerts: 
POST /api/alerts/bulk/status
Content-Type: application/json

{
  "ids": ["alert-abc-123", "alert-def-456"],
  "status": "resolved",
  "comment": "Bulk resolved - confirmed false positives"
}
Response: 
{
  "updated": 2,
  "failed": []
}

​
Add Comment Only

Add a comment without changing status: 
POST /api/alerts/{id}/comments
Content-Type: application/json

{
  "text": "Additional investigation notes..."
}
Response: 
{
  "id": "comment-xyz",
  "alert_id": "alert-abc-123",
  "user": "analyst@example.com",
  "text": "Additional investigation notes...",
  "created_at": "2024-01-15T15:30:00Z"
}

​
Error Responses

​
404 Not Found

{
  "detail": "Alert not found"
}

​
400 Bad Request

{
  "detail": "Invalid status value"
}

​
403 Forbidden

{
  "detail": "Not enough permissions"
}

​
Code Examples

​
Python

import requests

# Update single alert
response = requests.patch(
    f"{BASE_URL}/api/alerts/alert-abc-123",
    headers={
        "Authorization": f"Bearer {JWT_TOKEN}",
        "X-CSRF-Token": csrf_token
    },
    json={
        "status": "resolved",
        "comment": "Confirmed as authorized penetration test"
    }
)

if response.ok:
    result = response.json()
    print(f"Alert {result['id']} resolved")

# Bulk update
response = requests.post(
    f"{BASE_URL}/api/alerts/bulk/status",
    headers={
        "Authorization": f"Bearer {JWT_TOKEN}",
        "X-CSRF-Token": csrf_token
    },
    json={
        "ids": ["alert-1", "alert-2", "alert-3"],
        "status": "false_positive",
        "comment": "Known service account activity"
    }
)

result = response.json()
print(f"Updated {result['updated']} alerts")

​
JavaScript

// Update alert status
const response = await fetch(
  'https://chad.example.com/api/alerts/alert-abc-123',
  {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
      'X-CSRF-Token': csrfToken
    },
    body: JSON.stringify({
      status: 'acknowledged',
      comment: 'Starting investigation'
    })
  }
);

const result = await response.json();
console.log(`Status: ${result.status}`);

// Add comment
const commentResponse = await fetch(
  'https://chad.example.com/api/alerts/alert-abc-123/comments',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
      'X-CSRF-Token': csrfToken
    },
    body: JSON.stringify({
      text: 'Found related activity on 3 other hosts'
    })
  }
);