Overview This endpoint retrieves alerts from UTMStack’s Elasticsearch index. It supports advanced filtering, pagination, and sorting, allowing analysts to query alerts within specific time ranges or by defined conditions.
Authorization Required: All requests must include a valid Bearer Token obtained from the authentication endpoint.
Endpoint Details
POST /api/elasticsearch/search Method: POSTContent-Type: application/jsonAuthentication: Bearer Token requiredResponse: Array of alert objects
Query Parameters Current page number (starts at 1)
Number of results per page (e.g., 25)
Maximum number of records to retrieve (e.g., 100000000)
Elasticsearch index pattern (e.g., alert-*)
Sorting field and direction (e.g., @timestamp,desc)
Request Body The request body is a JSON array of filter definitions used to refine the search.
Filter Structure Name of the alert field to filter (e.g., “status”, “tags”, “@timestamp”)
Filter operator: IS, IS_NOT, IS_BETWEEN, CONTAINS, etc.
Filter value (string, number, or array for range operations)
Example Filter Payload [ { "field" : "status" , "operator" : "IS_NOT" , "value" : 1 }, { "field" : "tags" , "operator" : "IS_NOT" , "value" : "False positive" }, { "field" : "@timestamp" , "operator" : "IS_BETWEEN" , "value" : [ "now-7d" , "now" ] } ] Request & Response Examples curl -X POST "https://demo.utmstack.com/api/elasticsearch/search?page=1&size=25&top=100000000&indexPattern=alert-*&sort=@timestamp,desc" \ -H "Authorization: Bearer <your_access_token>" \ -H "Content-Type: application/json" \ -d '[ {"field": "status", "operator": "IS_NOT", "value": 1}, {"field": "tags", "operator": "IS_NOT", "value": "False positive"}, {"field": "@timestamp", "operator": "IS_BETWEEN", "value": ["now-7d", "now"]} ]' [ { "severity" : 3 , "severityLabel" : "High" , "status" : 2 , "statusLabel" : "Open" , "name" : "Windows: Multiple Windows logon failures" , "description" : "Adversaries may use brute force techniques to gain access to accounts when passwords are unknown or when password hashes are obtained." , "tactic" : "Brute Force" , "category" : "Potentially Malicious Activity" , "dataSource" : "dev-wsrv-2016" , "@timestamp" : "2024-10-15T10:30:00.000Z" , "source" : { "ip" : "192.168.1.100" , "hostname" : "workstation-01" }, "destination" : { "ip" : "192.168.1.10" , "hostname" : "domain-controller" } } ] Additional Code Examples import axios from 'axios' ; const searchAlerts = async () => { const url = 'https://demo.utmstack.com/api/elasticsearch/search' ; const params = { page: 1 , size: 25 , top: 100000000 , indexPattern: 'alert-*' , sort: '@timestamp,desc' }; const filters = [ { field: 'status' , operator: 'IS_NOT' , value: 1 }, { field: 'tags' , operator: 'IS_NOT' , value: 'False positive' }, { field: '@timestamp' , operator: 'IS_BETWEEN' , value: [ 'now-7d' , 'now' ] } ]; try { const response = await axios . post ( url , filters , { params , headers: { 'Authorization' : 'Bearer <your_access_token>' , 'Content-Type' : 'application/json' } }); return response . data ; } catch ( error ) { console . error ( 'Error fetching alerts:' , error ); } };
Response Details Returns a JSON array of alert objects. Each alert includes metadata, source/destination information, and contextual details.
Complete Response Structure Success Response
Empty Response
Error Response
[ { "severity" : 2 , "severityLabel" : "Medium" , "status" : 2 , "statusLabel" : "Open" , "TagRulesApplied" : null , "notes" : "" , "dataType" : "wineventlog" , "name" : "Windows: Multiple Windows logon failures" , "description" : "Adversaries may use brute force techniques to gain access to accounts when passwords are unknown or when password hashes are obtained." , "solution" : "Set account lockout policies after a certain number of failed login attempts to prevent passwords from being guessed. Use multi-factor authentication." , "statusObservation" : "This alert has been evaluated by the tag rules engine" , "tactic" : "Brute Force" , "category" : "Potentially Malicious Activity" , "dataSource" : "dev-wsrv-2016" , "tags" : null , "@timestamp" : "2024-10-15T10:30:00.000Z" , "source" : { "ip" : "192.168.1.100" , "hostname" : "workstation-01" }, "destination" : { "ip" : "192.168.1.10" , "hostname" : "domain-controller" } } ] Response Fields Alert severity level (1-5, where 5 is highest)
Human-readable severity label (Low, Medium, High, Critical)
Alert status code (1=Ignored, 2=Open, 3=In Review, 5=Completed)
Human-readable status label
Detailed description of the security event
Recommended remediation steps
MITRE ATT&CK tactic classification
Alert category classification
Source system that generated the alert
ISO 8601 timestamp when the alert was created
Filter Operators
IS : Exact matchIS_NOT : Not equal toCONTAINS : Contains substringSTARTS_WITH : Begins with valueENDS_WITH : Ends with value
GREATER_THAN : Greater than valueLESS_THAN : Less than valueGREATER_EQUAL : Greater than or equal toLESS_EQUAL : Less than or equal to
IS_BETWEEN : Between two values (requires array)IS_IN : Value in list (requires array)IS_NOT_IN : Value not in list (requires array) Common Filter Examples Filter by Severity [ { "field" : "severity" , "operator" : "GREATER_EQUAL" , "value" : 3 } ] Filter by Time Range (Last 24 hours) [ { "field" : "@timestamp" , "operator" : "IS_BETWEEN" , "value" : [ "now-24h" , "now" ] } ] Filter by Multiple Statuses [ { "field" : "status" , "operator" : "IS_IN" , "value" : [ 2 , 3 ] } ] Filter by Data Source [ { "field" : "dataSource" , "operator" : "CONTAINS" , "value" : "windows" } ] Status Codes Search completed successfully. Returns array of alerts.
Invalid request parameters or malformed filter syntax.
Missing or invalid Bearer token.
Insufficient permissions to access alerts.
Elasticsearch service error or internal server issue.
The API supports pagination through the page and size parameters:
page : Current page number (1-based)size : Number of results per pagetop : Maximum total results to consider
For optimal performance, use reasonable size values (25-100) and implement client-side pagination for large result sets.
Performance Tips:
Use specific time ranges to limit search scope
Apply filters to reduce the result set size
Avoid very large top values unless necessary
Consider using field-specific filters for better query performance
