Convert to Incident API

Convert one or more alerts into a formal security incident for comprehensive case management and investigation tracking.

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.

Note: 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

paramarrayrequired

Array of alert UUIDs to convert into an incident["c1c4e32c-dd9f-4a15-98c4-0dac2af40740", "d2f5e12a-b5a4-4bcd-91d0-2a8f5b6d9e1f"]

paramstringrequired

Descriptive name for the new incident

paramintegerrequired

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

paramstringrequired

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

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

Error Response

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

200OK

Incident created successfully from the provided alerts

400Bad Request

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

401Unauthorized

Missing or invalid Bearer token

404Not Found

One or more alerts not found with the specified IDs

500Internal 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

[Unknown component: details]

Best Practices