Skip to main content

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

​
alertIds
array
required
Array of alert UUIDs to update
​
status
integer
required
New status code for the alerts (see status codes below)
​
statusObservation
string
Optional observation note about the status change
​
addFalsePositiveTag
boolean
default:"false"
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

HTTP/1.1 200 OK
Content-Length: 0
Date: Wed, 16 Oct 2024 10:30:00 GMT
The API returns HTTP 200 OK with no response body when the status is successfully updated.

​
Status Codes

​
200
OK
Status updated successfully
​
400
Bad Request
Invalid request payload or malformed JSON
​
401
Unauthorized
Missing or invalid Bearer token
​
404
Not Found
One or more alerts not found
​
500
Internal 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

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

Follow a logical status progression:
  1. OPEN (2) - Initial alert state
  2. IN_REVIEW (3) - Under investigation
  3. COMPLETED (5) - Resolved or closed
Always include meaningful statusObservation notes:
  • Document the reason for status change
  • Include investigation findings
  • Reference any related tickets or incidents
When marking alerts as false positives:
  • Set status to 5 (COMPLETED)
  • Set addFalsePositiveTag to true
  • Include detailed reasoning in statusObservation

​
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