Alerts Operations Acknowledge

Alerts Operations Acknowledge
Acknowledge an alert to indicate triage in progress (NEW -> ACKNOWLEDGED only)

Moves an alert from NEW to ACKNOWLEDGED, records the acting user and time, and stores the optional analystNote (up to 2048 characters). The body must carry expectedVersion, the version read from the alert. 409 ALERT_INVALID_STATE_TRANSITION unless the alert is NEW, 409 ALERT_VERSION_CONFLICT when expectedVersion is missing or stale (refetch and retry), 404 ALERT_NOT_FOUND. Every success is audited. Requires the ADMIN or SECURITY_OPERATOR role (the AUDITOR role receives 403). Also accepts a Bearer API token with Full access (a Read-only token receives 403 API_TOKEN_NOT_PERMITTED).

Request
URI
POST
https://{api_host}/api/v1/alerts/{alertId}/acknowledge
COPY
Path Parameters
integer
alertId
Required  

Canonical alert ID

alertId example
1

Request Body

The version of the alert the caller read, as expectedVersion, and an optional analystNote of up to 2048 characters. A missing or stale expectedVersion is answered 409 ALERT_VERSION_CONFLICT.

AlertActionRequest of type(s) application/json
Required  
{
    "analystNote": "Reviewing with the host owner",
    "expectedVersion": 1
}
string
analystNote
Optional

Optional triage or resolution note

integer As int32 As int32
expectedVersion
Optional

Expected optimistic concurrency version

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The alert after it moved to ACKNOWLEDGED, with its new version

Returns AlertDetailDto of type(s) application/json
{
    "alertId": 0,
    "title": "string",
    "description": "string",
    "alertClass": "string",
    "agentPk": 0,
    "hostname": "string",
    "groupName": "string",
    "currentGroupName": "string",
    "severity": 0,
    "eventUuid": "string",
    "eventIngestTime": "string",
    "alertRuleId": 0,
    "alertRuleName": "string",
    "alertRuleRevision": 0,
    "qualificationSnapshot": "string",
    "matchedRulePk": 0,
    "matchedRuleName": "string",
    "matchedRuleAction": "string",
    "matchedRuleRevision": 0,
    "matchedRules": [
        {
            "ruleId": 0,
            "name": "string",
            "action": "string",
            "revision": 0,
            "builtIn": false,
            "firstMatchedAt": "string"
        }
    ],
    "mode": "string",
    "outcome": "string",
    "eventCount": 0,
    "state": "string",
    "resolutionReason": "string",
    "version": 0,
    "analystNote": "string",
    "actedBy": 0,
    "actedAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "firstSeenAt": "string",
    "lastSeenAt": "string"
}
integer As int64 As int64
alertId
Required  

Unique canonical alert identifier

string
title
Required  

Human-readable incident title

string
description
Optional

Optional narrative description

string
alertClass
Required  

High-level architectural domain of the alert

  • SECURITY: Raised by the alert engine when the threshold of an Alert Rule is breached by Agent events; carries the number of events
  • SYSTEM_HEALTH: Raised by the console itself rather than by Agent events; today only the per-license expiration alerts of the built-in license rule. It has no events, so its event count is always 0
Enumeration: SECURITY, SYSTEM_HEALTH
integer As int64 As int64
agentPk
Optional

Database primary key of the associated agent, if applicable

string
hostname
Optional

Hostname of the affected agent

string
groupName
Optional

Security Group the alert was raised under: the Group the agent was in when the alert's first event arrived, kept on the alert so moving the agent does not change it. While that Group still exists this is its current name, so a rename is not a move. Alerts raised before this was recorded fall back to the agent's current Group. Null for license alerts, which have no agent

string
currentGroupName
Optional

Security Group the agent is in now; differs from groupName once the agent has been moved to another Group. Null when the alert has no agent or the agent has no Group

integer As int32 As int32
severity
Optional
Constraints: minimum: 1 maximum: 100

Alert severity score from 1 to 100; present only for license-expiration alerts, null for security alerts

string As uuid As uuid
eventUuid
Optional

UUID of the originating security event for deep-linking

string As date-time As date-time
eventIngestTime
Optional

Ingest timestamp partition key of the originating event

integer As int64 As int64
alertRuleId
Required  

ID of the Alert Rule that qualified this incident

string
alertRuleName
Required  

Name snapshot of the Alert Rule

integer As int32 As int32
alertRuleRevision
Required  

Revision snapshot of the Alert Rule

string
qualificationSnapshot
Required  

JSON snapshot of the qualification criteria

integer As int64 As int64
matchedRulePk
Optional

Primary key of the matched protection rule if applicable

string
matchedRuleName
Optional

Name snapshot of the matched protection rule

string
matchedRuleAction
Optional

Action of the matched Rule at the time the Alert was opened: ALLOW, BLOCK, AUDIT or MFA_REQUIRED; null when the Alert has no matched Rule, including system-health alerts

integer As int32 As int32
matchedRuleRevision
Optional

Revision snapshot of the matched protection rule

array of object
matchedRules
Required  

Every distinct protection Rule that matched a qualifying event of this alert, ordered by firstMatchedAt ascending (ties by name). Never empty for an alert that names a Rule: an alert with nothing stored yet lists the one Rule it names. Empty when no Rule matched and for license and system-health alerts. matchedRuleName and the other matchedRule fields still describe the Rule of the latest qualifying event

string
mode
Optional

Group mode when received, captured when the Alert was opened (UI label: Group mode when received; it can differ from the mode at login): MONITOR or ENFORCE; null for a system-health alert

string
outcome
Optional

Outcome of the event that opened the Alert: one of ALLOWED, DETECTED_OBSERVE, PREVENTED, TERMINATED, ERROR, CHALLENGED or CHALLENGE_FAILED; null for a system-health alert

integer As int32 As int32
eventCount
Required  

Number of aggregated events in this incident

string
state
Required  

Current state in the alert investigation lifecycle

  • NEW: Raised and not yet handled; the state of every new alert. It can be acknowledged, resolved or marked false positive
  • ACKNOWLEDGED: Acknowledged by an operator (possible only from NEW). Still active and still counted in the active count; it can still be resolved or marked false positive
  • RESOLVED: Closed by the resolve or mark-false-positive action, or by the console resolving a license alert itself. The only terminal state; the resolution reason says which
Enumeration: NEW, ACKNOWLEDGED, RESOLVED
resolutionReason
Optional

Resolution disposition if state is RESOLVED

integer As int32 As int32
version
Required  

Optimistic locking version

string
analystNote
Optional

Analyst notes recorded during triage or resolution

integer As int64 As int64
actedBy
Optional

User ID of the actor who transitioned the alert state

string As date-time As date-time
actedAt
Optional

Timestamp of the most recent lifecycle transition

string As date-time As date-time
createdAt
Required  

Timestamp when the incident was created

string As date-time As date-time
updatedAt
Required  

Timestamp when the incident was last modified

string As date-time As date-time
firstSeenAt
Required  

Timestamp when the first event in this incident occurred

string As date-time As date-time
lastSeenAt
Required  

Timestamp when the latest event in this incident occurred


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: FORBIDDEN when the signed-in role is not allowed to call this operation; CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)

Returns ForbiddenWrite of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


404

404 Not Found: ALERT_NOT_FOUND when no alert has the id; RESOURCE_NOT_FOUND when the alertId is not a number, because the route only matches digits

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


409

409 Conflict: ALERT_INVALID_STATE_TRANSITION when the alert is not in the state NEW; ALERT_VERSION_CONFLICT when expectedVersion is missing or is not the current version of the alert, or another caller changed the alert first

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{}' https://{api_host}/api/v1/alerts/{alertId}/acknowledge