Convert to Incident API

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

array

required

Array of alert UUIDs to convert into an incident

Show Example

["c1c4e32c-dd9f-4a15-98c4-0dac2af40740", "d2f5e12a-b5a4-4bcd-91d0-2a8f5b6d9e1f"]

string

required

Descriptive name for the new incident

integer

required

Unique identifier for the incident (must be unique in the system)

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);
  }
};

import requests

def convert_alerts_to_incident():
    url = "https://demo.utmstack.com/api/utm-alerts/convert-to-incident"
    
    payload = {
        "eventIds": ["c1c4e32c-dd9f-4a15-98c4-0dac2af40740"],
        "incidentName": "Security Incident - Multiple Failed Logins",
        "incidentId": 1001,
        "incidentSource": "UTMStack Alert Investigation"
    }
    
    headers = {
        "Authorization": "Bearer <your_access_token>",
        "Content-Type": "application/json"
    }
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        print("Incident created successfully:", response.json())
    else:
        print(f"Error: {response.status_code} - {response.text}")
    
    return response

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"
}

{
  "error": "Incident ID already exists",
  "message": "An incident with ID 1001 already exists in the system",
  "timestamp": "2024-10-16T10:30:00.000Z",
  "status": 400
}

Status Codes

Incident created successfully from the provided alerts

Bad Request

Invalid request payload, duplicate incident ID, or invalid alert IDs

Unauthorized

Missing or invalid Bearer token

Not Found

One or more alerts not found with the specified IDs

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

Single Complex Alert

Convert when:

Alert requires extensive investigation
Multiple teams need to collaborate
Formal incident response procedures required
Compliance documentation needed

Escalation Scenarios

Convert when:

Alert severity requires management attention
Potential data breach or compromise
Customer-impacting security event
Regulatory reporting required

Best Practices

Incident Naming

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

Incident ID Management

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

Source Documentation

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"

Getting Started

Authentication

Alert Management

Incident Management

Analytics & Utilities

Overview

Endpoint Details

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

Request Body

JSON Schema

Request & Response Examples

Additional Code Examples

Response Details

Successful Conversion

Status Codes

Usage Examples

Single Alert to Incident

Malware Investigation

When to Convert to Incident

Best Practices

Integration with Incident Management

Security Considerations

OpenAPI Specification

​Overview

​Endpoint Details

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

​Request Body

​JSON Schema

​Request & Response Examples

​Additional Code Examples

​Response Details

​Successful Conversion

​Status Codes

​Usage Examples

​Single Alert to Incident

​Multiple Related Alerts

​Malware Investigation

​When to Convert to Incident

​Best Practices

​Integration with Incident Management

​Security Considerations

​OpenAPI Specification

Overview

Endpoint Details

Request Body

JSON Schema

Request & Response Examples

Additional Code Examples

Response Details

Successful Conversion

Status Codes

Usage Examples

Single Alert to Incident

Multiple Related Alerts

Malware Investigation

When to Convert to Incident

Best Practices

Integration with Incident Management

Security Considerations

OpenAPI Specification