Skip to main content

​
Overview

This endpoint allows security analysts to convert selected alerts into a formal security incident. This is useful when multiple related alerts need to be investigated together or when an alert requires escalation to incident response procedures.
Authorization Required: Include a valid Bearer Token in the Authorization header.

​
Endpoint Details

POST /api/utm-alerts/convert-to-incident

Method: POST
Content-Type: application/json
Authentication: Bearer Token required
Response: Incident creation confirmation

​
Request Body

​
eventIds
array
required
Array of alert UUIDs to convert into an incident
​
incidentName
string
required
Descriptive name for the new incident
​
incidentId
integer
required
Unique identifier for the incident (must be unique in the system)
​
incidentSource
string
required
Source or origin description for the incident

​
JSON Schema

{
  "type": "object",
  "properties": {
    "eventIds": {
      "type": "array",
      "items": { 
        "type": "string", 
        "format": "uuid" 
      },
      "description": "Array of alert UUIDs to convert"
    },
    "incidentName": { 
      "type": "string",
      "description": "Descriptive name for the incident"
    },
    "incidentId": { 
      "type": "integer",
      "description": "Unique incident identifier"
    },
    "incidentSource": { 
      "type": "string",
      "description": "Source description for the incident"
    }
  },
  "required": ["eventIds", "incidentName", "incidentId", "incidentSource"]
}

​
Request & Response Examples

curl -X POST "https://demo.utmstack.com/api/utm-alerts/convert-to-incident" \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "eventIds": ["c1c4e32c-dd9f-4a15-98c4-0dac2af40740"],
    "incidentName": "Security Incident - Multiple Failed Logins",
    "incidentId": 1001,
    "incidentSource": "UTMStack Alert Investigation"
  }'

{
  "success": true,
  "incidentId": 1001,
  "message": "Incident created successfully",
  "alertsConverted": 1
}

​
Additional Code Examples

import axios from "axios";

const convertToIncident = async () => {
  const token = "<your_access_token>";
  
  const payload = {
    eventIds: ["c1c4e32c-dd9f-4a15-98c4-0dac2af40740"],
    incidentName: "Security Incident - Multiple Failed Logins",
    incidentId: 1001,
    incidentSource: "UTMStack Alert Investigation"
  };

  try {
    const response = await axios.post(
      "https://demo.utmstack.com/api/utm-alerts/convert-to-incident", 
      payload, 
      {
        headers: { 
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json"
        }
      }
    );
    
    console.log("Incident created:", response.data);
    return response;
  } catch (error) {
    console.error("Error converting to incident:", error.response?.data || error.message);
  }
};

​
Response Details

​
Successful Conversion

  • Success Response
  • Error Response
{
  "success": true,
  "incidentId": 1001,
  "message": "Incident created successfully",
  "alertsConverted": 1,
  "timestamp": "2024-10-16T10:30:00.000Z"
}

​
Status Codes

​
200
OK
Incident created successfully from the provided alerts
​
400
Bad Request
Invalid request payload, duplicate incident ID, or invalid alert IDs
​
401
Unauthorized
Missing or invalid Bearer token
​
404
Not Found
One or more alerts not found with the specified IDs
​
500
Internal Server Error
Internal server error during incident creation

​
Usage Examples

​
Single Alert to Incident

{
  "eventIds": ["c1c4e32c-dd9f-4a15-98c4-0dac2af40740"],
  "incidentName": "Brute Force Attack Investigation",
  "incidentId": 2001,
  "incidentSource": "SOC Team Escalation"
}

{
  "eventIds": [
    "c1c4e32c-dd9f-4a15-98c4-0dac2af40740",
    "d2f5e12a-b5a4-4bcd-91d0-2a8f5b6d9e1f",
    "7a12c4f3-894c-4e2a-9f1b-c7c7a0b84522"
  ],
  "incidentName": "Coordinated Attack Campaign",
  "incidentId": 2002,
  "incidentSource": "UTMStack Correlation Analysis"
}

​
Malware Investigation

{
  "eventIds": ["e3c7b8f9-456d-789e-012f-3456789abcde"],
  "incidentName": "Malware Detection and Response",
  "incidentId": 2003,
  "incidentSource": "Automated Threat Detection"
}

​
When to Convert to Incident

Convert when:
  • Alert requires extensive investigation
  • Multiple teams need to collaborate
  • Formal incident response procedures required
  • Compliance documentation needed
Convert when:
  • Alert severity requires management attention
  • Potential data breach or compromise
  • Customer-impacting security event
  • Regulatory reporting required

​
Best Practices

Use descriptive names:
  • Include attack type: “Brute Force Attack Investigation”
  • Reference affected systems: “Web Server Compromise - Server01”
  • Add timeline context: “Ransomware Incident - Oct 2024”
  • Be specific but concise
ID assignment strategy:
  • Use sequential numbering for easy tracking
  • Consider year/month prefixes: 202410001
  • Reserve ID ranges for different incident types
  • Ensure uniqueness across the organization
Provide clear sources:
  • “SOC Team Escalation” for manual escalations
  • “Automated Correlation Engine” for system-detected patterns
  • “Customer Report” for externally reported issues
  • Include analyst name for accountability

​
Integration with Incident Management

Platform Integration:
  • Converted incidents appear in the UTMStack incident management interface
  • Original alerts remain linked to the incident for reference
  • Incident timeline includes all alert details and timestamps
  • Case management workflow is automatically initiated
  • Notifications sent to configured incident response team members

​
Security Considerations

Security Notes:
  • Requires Bearer token authentication
  • Incident creation is audited for compliance
  • Only authorized users can convert alerts to incidents
  • Incident IDs must be unique to prevent conflicts
  • Alert IDs must exist and be accessible to the user

​
OpenAPI Specification

post:
  summary: "Convert alerts to incident"
  tags:
    - Incident Management
  security:
    - bearerAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ConvertToIncidentRequest'
  responses:
    '200':
      description: "Incident created successfully"
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
              incidentId:
                type: integer
              message:
                type: string
              alertsConverted:
                type: integer
    '400':
      description: "Invalid request or duplicate incident ID"
    '401':
      description: "Unauthorized"
    '404':
      description: "Alerts not found"
    '500':
      description: "Internal server error"

components:
  schemas:
    ConvertToIncidentRequest:
      type: object
      required:
        - eventIds
        - incidentName
        - incidentId
        - incidentSource
      properties:
        eventIds:
          type: array
          items:
            type: string
            format: uuid
          description: "Array of alert UUIDs to convert"
        incidentName:
          type: string
          description: "Descriptive name for the incident"
        incidentId:
          type: integer
          description: "Unique incident identifier"
        incidentSource:
          type: string
          description: "Source description for the incident"
⌘I