Update Alert Tags API

Add or update tags for one or multiple alerts with optional automatic rule creation and auditing capabilities.

Overview

Adds or updates tags for one or multiple alerts. Tags can categorize alerts, help in filtering, and optionally trigger automatic rules based on tag creation. Supports auditing for traceability.

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

Endpoint Details

POST /api/utm-alerts/tags

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 with tags["c1c4e32c-dd9f-4a15-98c4-0dac2af40740", "d2f5e12a-b5a4-4bcd-91d0-2a8f5b6d9e1f"]

paramarray

Array of tag strings to assign to the alerts (can be empty to remove tags)["Investigation Needed", "SOC Review", "False Positive"]

parambooleanrequired

Whether to automatically create a tag rule when assigning tags

JSON Schema

{
  "type": "object",
  "properties": {
    "alertIds": {
      "type": "array",
      "items": { 
        "type": "string", 
        "format": "uuid" 
      },
      "description": "List of alert UUIDs to update"
    },
    "tags": {
      "type": "array",
      "items": { 
        "type": "string" 
      },
      "description": "List of tags to assign"
    },
    "createRule": { 
      "type": "boolean",
      "description": "Create automatic tag rule"
    }
  },
  "required": ["alertIds", "createRule"]
}

Request & Response Examples

curl -X POST "https://demo.utmstack.com/api/utm-alerts/tags" 
  -H "Authorization: Bearer <your_access_token>" 
  -H "Content-Type: application/json" 
  -d '{
    "alertIds": ["c1c4e32c-dd9f-4a15-98c4-0dac2af40740", "d2f5e12a-b5a4-4bcd-91d0-2a8f5b6d9e1f"],
    "tags": ["Investigation Needed", "SOC Review"],
    "createRule": true
  }'

HTTP/1.1 200 OK
Content-Length: 0

Additional Code Examples

import axios from "axios";

const updateAlertTags = async () => {
  const token = "<your_access_token>";
  
  const payload = {
    alertIds: [
      "c1c4e32c-dd9f-4a15-98c4-0dac2af40740", 
      "d2f5e12a-b5a4-4bcd-91d0-2a8f5b6d9e1f"
    ],
    tags: ["Investigation Needed", "SOC Review"],
    createRule: true
  };

  try {
    const response = await axios.post(
      "https://demo.utmstack.com/api/utm-alerts/tags", 
      payload, 
      {
        headers: { 
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json"
        }
      }
    );
    
    console.log("Tags updated successfully", response.status);
    return response;
  } catch (error) {
    console.error("Error updating tags:", 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 request",
      "message": "Alert IDs cannot be empty",
      "timestamp": "2024-10-16T10:30:00.000Z",
      "status": 400
    }

Note: The API returns HTTP 200 OK with no response body when tags are successfully updated.

Status Codes

200OK

Tags 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 tag update

Usage Examples

Add Investigation Tags

{
  "alertIds": ["c1c4e32c-dd9f-4a15-98c4-0dac2af40740"],
  "tags": ["Under Investigation", "Priority High", "Escalated"],
  "createRule": false
}

Mark as False Positive with Rule Creation

{
  "alertIds": ["d2f5e12a-b5a4-4bcd-91d0-2a8f5b6d9e1f"],
  "tags": ["False Positive", "Reviewed"],
  "createRule": true
}

Remove All Tags

{
  "alertIds": ["7a12c4f3-894c-4e2a-9f1b-c7c7a0b84522"],
  "tags": [],
  "createRule": false
}

Bulk Tag Assignment

{
  "alertIds": [
    "c1c4e32c-dd9f-4a15-98c4-0dac2af40740",
    "d2f5e12a-b5a4-4bcd-91d0-2a8f5b6d9e1f",
    "7a12c4f3-894c-4e2a-9f1b-c7c7a0b84522"
  ],
  "tags": ["Batch Processed", "Weekly Review"],
  "createRule": false
}

Tag Categories

[Unknown component: details]

Automatic Rule Creation

ℹ️ Info: When createRule is set to true, UTMStack automatically creates tag rules that will apply the same tags to future alerts matching similar criteria. This helps automate recurring tagging scenarios.

Rule Creation Behavior

Triggers: Based on alert patterns, source IPs, or rule names
Scope: Applied to future alerts matching criteria
Management: Rules can be viewed and modified in the UTMStack interface
Audit: Rule creation is logged for compliance

Security Considerations

⚠️ Warning: Security Notes:

Requires Bearer token authentication
All tag changes are audited for traceability
Tag rules creation requires appropriate permissions
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 tags"
  tags:
    - Alerts
  security:
    - bearerAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/UpdateAlertTagsRequest'
  responses:
    '200':
      description: "Tags updated successfully"
    '400':
      description: "Invalid request payload"
    '401':
      description: "Unauthorized"
    '404':
      description: "Alert not found"
    '500':
      description: "Internal server error"

components:
  schemas:
    UpdateAlertTagsRequest:
      type: object
      required:
        - alertIds
        - createRule
      properties:
        alertIds:
          type: array
          items:
            type: string
            format: uuid
          description: "List of alert UUIDs to update"
        tags:
          type: array
          items:
            type: string
          description: "List of tags to assign"
        createRule:
          type: boolean
          description: "Create automatic tag rule"