Update Alert Notes API

Add or update notes for a specific alert to document observations, investigations, or remediation steps.

Overview

Adds or updates notes for a specific alert. Notes allow analysts to document observations, investigations, or remediation steps related to an alert. Supports auditing for traceability.

Note: Authorization Required: Include a valid Bearer Token in the Authorization header.

Endpoint Details

POST /api/utm-alerts/notes

Method: POST
Content-Type: application/json
Authentication: Bearer Token required
Query Parameter: alertId (required)

Parameters

Query Parameters

paramstringrequired

UUID of the alert to update with notes

Request Body

The request body should contain the notes as a plain JSON string.

paramstring

Text notes for the alert. Can be empty to clear existing notes.

Request & Response Examples

curl -X POST "https://demo.utmstack.com/api/utm-alerts/notes?alertId=c1c4e32c-dd9f-4a15-98c4-0dac2af40740" 
  -H "Authorization: Bearer <your_access_token>" 
  -H "Content-Type: application/json" 
  -d '"Investigated alert, determined as false positive after analyzing network traffic patterns."'

{
  "message": "Notes updated successfully"
}

Additional Code Examples

import axios from "axios";

const updateAlertNotes = async (alertId, notes) => {
  const token = "<your_access_token>";
  
  try {
    const response = await axios.post(
      `https://demo.utmstack.com/api/utm-alerts/notes?alertId=${alertId}`,
      notes,
      {
        headers: { 
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json"
        }
      }
    );
    
    console.log("Notes updated successfully:", response.data);
    return response.data;
  } catch (error) {
    console.error("Error updating notes:", error.response?.data || error.message);
  }
};

// Usage examples
await updateAlertNotes("c1c4e32c-dd9f-4a15-98c4-0dac2af40740", 
  "Alert investigated - confirmed as legitimate security event. Escalating to security team.");

await updateAlertNotes("d2f5e12a-b5a4-4bcd-91d0-2a8f5b6d9e1f", 
  "False positive - internal system maintenance activity.");

Response Details

Successful Response

Success

    {
      "message": "Notes updated successfully"
    }

Empty Notes

    {
      "message": "Notes cleared successfully"
    }

Status Codes

200OK

Notes updated successfully

400Bad Request

Invalid alert ID format or malformed request body

401Unauthorized

Missing or invalid Bearer token

404Not Found

Alert not found with the specified ID

500Internal Server Error

Internal server error while updating notes

Common Use Cases

Investigation Notes

// Document investigation findings
await updateAlertNotes("alert-123", 
  "Investigation Summary:\n" +
  "- Analyzed source IP: 192.168.1.100\n" +
  "- Reviewed firewall logs for the past 24 hours\n" +  
  "- Contacted user for verification\n" +
  "- Determined as legitimate access from approved device\n" +
  "- No further action required"
);

False Positive Documentation

# Document false positive reasoning
update_alert_notes("alert-456", 
    "FALSE POSITIVE: Alert triggered by scheduled backup process. "
    "Backup runs daily at 2 AM. Added exception rule to prevent future alerts."
)

Escalation Notes

// Document escalation
const escalationNote = 
  "ESCALATED TO SECURITY TEAM:\n" +
  "- High severity alert confirmed as potential breach\n" +
  "- Initial response completed at " + new Date().toISOString() + "\n" +
  "- Assigned to: security-team@company.com\n" +
  "- Next steps: Full forensic investigation required";

await updateAlertNotes("alert-789", escalationNote);

Clear Notes

# Clear existing notes
update_alert_notes("alert-101", "")

Best Practices

[Unknown component: details]

Advanced Examples

Structured Investigation Notes

const createInvestigationNote = (alertId, findings) => {
  const timestamp = new Date().toISOString();
  const analyst = "john.doe@company.com";
  
  const structuredNote = 
    "=== INVESTIGATION REPORT ===\n" +
    `Timestamp: ${timestamp}\n` +
    `Analyst: ${analyst}\n` +
    `Alert ID: ${alertId}\n\n` +
    "INITIAL ASSESSMENT:\n" +
    `${findings.assessment}\n\n` +
    "INVESTIGATION STEPS:\n" +
    findings.steps.map((step, index) => `${index + 1}. ${step}`).join('\n') + "\n\n" +
    "EVIDENCE:\n" +
    `${findings.evidence}\n\n` +
    "CONCLUSION:\n" +
    `${findings.conclusion}\n\n` +
    "NEXT ACTIONS:\n" +
    `${findings.nextActions}\n` +
    "=== END REPORT ===";
  
  return updateAlertNotes(alertId, structuredNote);
};

// Usage
await createInvestigationNote("alert-123", {
  assessment: "Medium severity - suspicious login from new location",
  steps: [
    "Verified user identity through secondary channels",
    "Checked login history for similar patterns", 
    "Analyzed geolocation data",
    "Contacted user directly via phone"
  ],
  evidence: "User confirmed legitimate travel to new location. Phone verification successful.",
  conclusion: "Legitimate user activity - false positive",
  nextActions: "Add travel notification to user profile. No further investigation needed."
});

Security Considerations

⚠️ Warning: Security Notes:

All note changes are audited for compliance
Notes are stored in plain text - avoid sensitive data
Users need proper permissions to update alert notes
Alert ID must be a valid UUID that exists in the system

OpenAPI Specification

post:
  summary: "Add or update notes for an alert"
  tags:
    - Alert Management
  security:
    - bearerAuth: []
  parameters:
    - name: alertId
      in: query
      required: true
      schema:
        type: string
        format: uuid
      description: "UUID of the alert to update"
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: string
          description: "Notes content as a JSON string"
  responses:
    '200':
      description: "Notes updated successfully"
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Notes updated successfully"
    '400':
      description: "Invalid alert ID or request format"
    '401':
      description: "Unauthorized"
    '404':
      description: "Alert not found"
    '500':
      description: "Internal server error"