Skip to main content

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

​
alertId
string
required
UUID of the alert to update with notes

​
Request Body

The request body should contain the notes as a plain JSON string.
​
notes
string
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
  • Empty Notes
{
  "message": "Notes updated successfully"
}

​
Status Codes

​
200
OK
Notes updated successfully
​
400
Bad Request
Invalid alert ID format or malformed request body
​
401
Unauthorized
Missing or invalid Bearer token
​
404
Not Found
Alert not found with the specified ID
​
500
Internal 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: [email protected]\n" +
  "- Next steps: Full forensic investigation required";

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

​
Clear Notes

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

​
Best Practices

Structured Documentation:
  • Include timestamp and analyst name
  • Describe investigation steps taken
  • Document evidence found or lack thereof
  • Specify next actions or resolution
  • Use clear, professional language
Best Practices:
  • Clearly mark as “FALSE POSITIVE”
  • Explain the root cause
  • Document prevention measures taken
  • Reference any rules or exceptions added
  • Include confidence level in assessment
Recommended Flow:
  1. Initial triage notes with priority assessment
  2. Investigation progress updates
  3. Evidence collection documentation
  4. Final resolution and lessons learned
  5. Handoff notes if escalating to other teams

​
Advanced Examples

​
Structured Investigation Notes

const createInvestigationNote = (alertId, findings) => {
  const timestamp = new Date().toISOString();
  const analyst = "[email protected]";
  
  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

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"