UTMSTACK logoUTMSTACK logo
API Documentation Reference Tables

Reference Tables

Alert Object Structure

FieldTypeDescription
idstring (UUID)Unique alert identifier
@timestampstring (ISO 8601)Alert timestamp
namestringAlert rule name
descriptionstringDetailed alert description
severityintegerSeverity code (1-4)
severityLabelstringSeverity display label (Low, Medium, High, Critical)
statusintegerStatus code (see below)
statusLabelstringStatus display label
statusObservationstringObservation text from status change
categorystringMITRE ATT&CK tactic category
techniquestringMITRE ATT&CK technique
dataSourcestringSource host/system
dataTypestringData type (linux, wineventlog, etc.)
isIncidentbooleanWhether alert is part of an incident
incidentDetailobjectIncident details if linked
tagsstring[]/nullApplied tags
notesstringNotes added to the alert
adversaryobjectSource entity details (file, host, user)
targetobject/nullTarget entity details
impactobjectImpact scores (integrity, confidentiality, availability)
eventsarrayAssociated raw log events
lastEventobjectMost recent associated event
referencestring[]Reference URLs
solutionstringRecommended solution

Alert Status Codes

CodeLabelDescription
1Automatic reviewAlert under automatic review
2OpenAlert is open and needs attention
3In reviewAlert is being reviewed by an analyst
5CompletedAlert has been resolved/completed

Status codes 4 and 6 do not exist and will return HTTP 500 if used.

Incident Status Values

StatusDescription
OPENNew/open incident
IN_REVIEWUnder investigation
COMPLETEDResolved/closed

Filter Operators

The FilterType object is used across all search, count, and chart-view endpoints.

{
  "field": "<field_name>",
  "operator": "<operator>",
  "value": "<value_or_array>"
}
OperatorValue TypeDescriptionExample
ISstringExact match{"field":"status","operator":"IS","value":"2"}
IS_NOTstringNot equal{"field":"status","operator":"IS_NOT","value":"5"}
IS_BETWEENarray [2]Range (dates, numbers){"field":"@timestamp","operator":"IS_BETWEEN","value":["now-24h","now"]}
IS_NOT_BETWEENarray [2]Outside range{"field":"@timestamp","operator":"IS_NOT_BETWEEN","value":["start","end"]}
CONTAINstringContains substring{"field":"name","operator":"CONTAIN","value":"Windows"}
DOES_NOT_CONTAINstringDoes not contain{"field":"name","operator":"DOES_NOT_CONTAIN","value":"test"}
IS_ONE_OFarrayMatch any value{"field":"status","operator":"IS_ONE_OF","value":["2","3"]}
IS_NOT_ONE_OFarrayExclude values{"field":"status","operator":"IS_NOT_ONE_OF","value":["5"]}
CONTAIN_ONE_OFarrayContains any substring{"field":"dataSource","operator":"CONTAIN_ONE_OF","value":["centos","rocky"]}
DOES_NOT_CONTAIN_ONE_OFarrayExclude substrings
EXISTstring (empty)Field exists{"field":"target.user","operator":"EXIST","value":""}
DOES_NOT_EXISTstring (empty)Field missing{"field":"target.user","operator":"DOES_NOT_EXIST","value":""}
START_WITHstringStarts with prefix{"field":"dataSource","operator":"START_WITH","value":"windows"}
NOT_START_WITHstringDoes not start with
ENDS_WITHstringEnds with suffix{"field":"dataSource","operator":"ENDS_WITH","value":"10"}
NOT_ENDS_WITHstringDoes not end with
IS_GREATER_THANstringGreater than{"field":"log.eventCode","operator":"IS_GREATER_THAN","value":"5000"}
IS_LESS_THAN_OR_EQUALSstringLess than or equal

Important notes:

  • For IS_BETWEEN, the value must be a JSON array of two strings: ["start","end"]. Using a comma-separated string causes HTTP 500 errors.

  • For exact-match operators (IS, IS_ONE_OF, EXIST) on text fields, use the .keyword suffix (e.g., dataType.keyword instead of dataType).

  • For substring operators (CONTAIN, START_WITH, ENDS_WITH), use the text field without .keyword.

  • Multiple filters in the array are combined with AND logic.

  • Pass [] (empty array) for no filters.

Relative Date Expressions

Supported in @timestamp filter values:

ExpressionMeaning
nowCurrent time
now-1h1 hour ago
now-24h24 hours ago
now-7d7 days ago
now-30d30 days ago
now-90d90 days ago

Pagination

All list endpoints support pagination via query parameters:

ParameterDescription
pagePage number (0-based)
sizeItems per page
sortSort field and direction (e.g., @timestamp,desc)
topMaximum total results (search endpoint only)

Response Headers:

HeaderDescription
X-Total-CountTotal number of matching results
LinkPagination links (next, prev, first, last)

Common API Errors

HTTP CodeMeaningCommon Cause
200SuccessRequest completed successfully
201CreatedResource created successfully
400Bad RequestMissing required parameters, invalid request body
401UnauthorizedInvalid or missing API key
404Not FoundResource not found or endpoint does not exist
405Method Not AllowedHTTP method not supported for this endpoint
500Internal Server ErrorInvalid filter value format, non-existent status code, or server issue

Endpoint Summary

MethodEndpointDescription
Search & Query
POST/api/elasticsearch/searchSearch alerts or logs with filters
POST/api/elasticsearch/countCheck if matching events exist
GET/api/elasticsearch/index/allList all indices
GET/api/elasticsearch/index/propertiesGet field mappings for an index pattern
GET/api/elasticsearch/property/valuesGet distinct field values
POST/api/elasticsearch/property/values-with-countGet field values with occurrence counts
POST/api/log-analyzer/chart-viewGet time-bucketed event counts
POST/api/elasticsearch/search/sqlSQL query interface
Alert Management
GET/api/utm-alerts/count-open-alertsCount open alerts
POST/api/utm-alerts/statusChange alert status
POST/api/utm-alerts/notesAdd notes to an alert
POST/api/utm-alerts/tagsAdd/remove tags on alerts
POST/api/utm-alerts/convert-to-incidentConvert alerts to incident
Incident Management
GET/api/utm-incidentsList incidents
GET/api/utm-incidents/{id}Get specific incident
POST/api/utm-incidentsCreate new incident
PUT/api/utm-incidents/change-statusChange incident status
POST/api/utm-incidents/add-alertsAdd alerts to incident
GET/api/utm-incident-alertsList alerts in an incident
DELETE/api/utm-incident-alerts/{id}Remove alert from incident
POST/api/utm-incident-alerts/update-statusUpdate alert status in incident
GET/api/utm-incident-notesList incident notes
POST/api/utm-incident-notesAdd note to incident
Data Sources & Agents
GET/api/utm-data-input-statusesList data input statuses
GET/api/utm-data-input-statuses/countCount data input statuses
GET/api/agent-manager/agentsList agents
GET/api/data-typesList supported data types
GET/api/utm-index-patternsList index patterns
System
GET/api/pingHealth check
GET/api/info/versionGet API version