Update Alert Status API

Update the status of one or more alerts with auditing and optional false positive tagging capabilities.

Overview

Updates the status of one or more alerts. Allows analysts to change the alert state (e.g., Open, In Review, Completed) and optionally add an observation note. Supports auditing for traceability.

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

Endpoint Details

POST /api/utm-alerts/status

Method: POST
Content-Type: application/json
Authentication: Bearer Token required
Response: HTTP 200 OK (no body)

Request Body

paramarrayrequired

Array of alert UUIDs to update["c1c4e32c-dd9f-4a15-98c4-0dac2af40740", "7a12c4f3-894c-4e2a-9f1b-c7c7a0b84522"]

paramintegerrequired

New status code for the alerts (see status codes below)

paramstring

Optional observation note about the status change

paramboolean

Whether to add a "False positive" tag to the alerts

Status Codes Reference

OPEN

Value: 2
Alert is open and pending review

IN_REVIEW

Value: 3
Alert is currently being reviewed

COMPLETED

Value: 5
Alert has been resolved/completed

JSON Schema

{
  "type": "object",
  "properties": {
    "alertIds": {
      "type": "array",
      "items": { 
        "type": "string", 
        "format": "uuid" 
      },
      "description": "Array of alert UUIDs"
    },
    "status": { 
      "type": "integer", 
      "enum": [2, 3, 5],
      "description": "New status code"
    },
    "statusObservation": { 
      "type": "string",
      "description": "Optional observation note"
    },
    "addFalsePositiveTag": { 
      "type": "boolean",
      "description": "Add false positive tag"
    }
  },
  "required": ["alertIds", "status"]
}

Request & Response Examples

curl -X POST "https://demo.utmstack.com/api/utm-alerts/status" 
  -H "Authorization: Bearer <your_access_token>" 
  -H "Content-Type: application/json" 
  -d '{
    "alertIds": ["c1c4e32c-dd9f-4a15-98c4-0dac2af40740"],
    "status": 3,
    "statusObservation": "Reviewed and confirmed as false positive",
    "addFalsePositiveTag": true
  }'

HTTP/1.1 200 OK
Content-Length: 0

Additional Code Examples

import axios from "axios";

const updateAlertStatus = async () => {
  const token = "<your_access_token>";
  
  const payload = {
    alertIds: ["c1c4e32c-dd9f-4a15-98c4-0dac2af40740"],
    status: 3,
    statusObservation: "Reviewed and confirmed as false positive",
    addFalsePositiveTag: true
  };

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

Response Details

Successful Update

Success Response

    HTTP/1.1 200 OK
    Content-Length: 0
    Date: Wed, 16 Oct 2024 10:30:00 GMT

Error Response

    {
      "error": "Invalid alert ID",
      "message": "Alert with ID 'invalid-uuid' not found",
      "timestamp": "2024-10-16T10:30:00.000Z",
      "status": 404
    }

Note: The API returns HTTP 200 OK with no response body when the status is successfully updated.

Status Codes

200OK

Status updated successfully

400Bad Request

Invalid request payload or malformed JSON

401Unauthorized

Missing or invalid Bearer token

404Not Found

One or more alerts not found

500Internal Server Error

Internal server error during update

Usage Examples

Mark Alert as False Positive

{
  "alertIds": ["c1c4e32c-dd9f-4a15-98c4-0dac2af40740"],
  "status": 5,
  "statusObservation": "Confirmed false positive after investigation",
  "addFalsePositiveTag": true
}

Move Alert to Review

{
  "alertIds": ["7a12c4f3-894c-4e2a-9f1b-c7c7a0b84522"],
  "status": 3,
  "statusObservation": "Escalated to security team for detailed analysis"
}

Bulk Status Update

{
  "alertIds": [
    "c1c4e32c-dd9f-4a15-98c4-0dac2af40740",
    "7a12c4f3-894c-4e2a-9f1b-c7c7a0b84522",
    "9b34f5e7-123a-456b-789c-def012345678"
  ],
  "status": 5,
  "statusObservation": "Bulk closure after investigation completed"
}

Security Considerations

⚠️ Warning: Security Notes:

Requires Bearer token authentication
All status changes are audited using ApplicationEventService for traceability
Users without proper permissions will receive 401 Unauthorized
Alert IDs must be valid UUIDs that exist in the system

Best Practices

[Unknown component: details]

OpenAPI Specification

post:
  summary: "Update alert status"
  tags:
    - Alerts
  security:
    - bearerAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/UpdateAlertStatusRequest'
  responses:
    '200':
      description: "Status updated successfully"
    '400':
      description: "Invalid request payload"
    '401':
      description: "Unauthorized"
    '404':
      description: "Alert not found"
    '500':
      description: "Internal server error"

components:
  schemas:
    UpdateAlertStatusRequest:
      type: object
      required:
        - alertIds
        - status
      properties:
        alertIds:
          type: array
          items:
            type: string
            format: uuid
        status:
          type: integer
          enum: [2, 3, 5]
        statusObservation:
          type: string
        addFalsePositiveTag:
          type: boolean
          default: false