# Alerts

## Overview

Use these API operations to interact with [alerts](/alerts.md) in Panther.

To call the API, see the [How to use the Panther REST API](/panther-developer-workflows/api/rest.md#how-to-use-the-panther-rest-api) instructions—including [directions for how to invoke it directly from this documentation page](/panther-developer-workflows/api/rest.md#step-3-invoke-the-panther-rest-api).

## Required permissions

* For `GET` operations, your API token must have the `Read Alerts` permission.
* For `PATCH` operations, your API token must have the `Manage Alerts` permission.

## Operations

## GET /alerts/{id}

> Get an alert

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"alert","description":"The alert api handles all operations for alerts"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"AlertAPI.Alert":{"type":"object","properties":{"assignee":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The Actor that is assigned to this alert"},"context":{"description":"The context of this alert"},"contextTags":{"type":"array","items":{"type":"string","description":"Tag to provide context for this alert","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30},"description":"the context tags for the alert","maxItems":10},"createdAt":{"type":"string","description":"Date and time when the alert got created"},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/AlertAPI.Delivery"},"description":"The metadata around the alert's delivery attempts"},"detection":{"$ref":"#/components/schemas/AlertAPI.DetectionInfo"},"eventCount":{"type":"integer","description":"The number of events that have been received for this alert","format":"int64"},"firstEventOccurredAt":{"type":"string","description":"Date and time of this alert's first event"},"id":{"type":"string","description":"The unique identifier of this alert"},"lastReceivedEventAt":{"type":"string","description":"Date and time that the last event related to this alert was received"},"quality":{"type":"string","description":"The quality of this Alert","enum":["NOISE","USEFUL"]},"runbook":{"type":"string","description":"The runbook for this Alert, as extracted from its origin"},"severity":{"type":"string","description":"The severity of this Alert","enum":["CRITICAL","HIGH","MEDIUM","LOW","INFO"]},"status":{"type":"string","description":"The status of this Alert","enum":["OPEN","CLOSED","TRIAGED","RESOLVED"]},"systemError":{"$ref":"#/components/schemas/AlertAPI.SystemError"},"title":{"type":"string","description":"The title of this alert"},"type":{"type":"string","description":"The type of this alert"},"updatedBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The Actor that last updated the state of this alert"}},"required":["id","type","status"]},"AlertAPI.Delivery":{"type":"object","properties":{"dispatchedAt":{"type":"string"},"label":{"type":"string","description":"The label of the alert at where it was delivered (channel name/ID, jira ticket, asana issue, etc)"},"message":{"type":"string"},"outputId":{"type":"string"},"statusCode":{"type":"integer","format":"int64"},"success":{"type":"boolean"}},"required":["dispatchedAt","label","message","statusCode","success","outputId"]},"AlertAPI.DetectionInfo":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of this Detection"},"type":{"type":"string","description":"The type of this Detection","enum":["RULE","CORRELATION_RULE","POLICY","SCHEDULED_RULE"]}}},"AlertAPI.SystemError":{"type":"object","properties":{"detection":{"$ref":"#/components/schemas/AlertAPI.DetectionInfo"},"sourceId":{"type":"string","description":"The source ID of this SystemError"},"sourceType":{"type":"string","description":"The source type of this SystemError"},"type":{"type":"string","description":"The type of this SystemError"}}},"AlertAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"AlertAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alerts/{id}":{"get":{"tags":["alert"],"summary":"Get an alert","operationId":"alert#get","parameters":[{"name":"id","in":"path","description":"ID of the alert","required":true,"schema":{"type":"string","description":"ID of the alert"}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.Alert"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.NotFoundError"}}}}}}}}}
```

## PATCH /alerts/{id}

> Update the status, assignee, quality or contextTags of an alert

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"alert","description":"The alert api handles all operations for alerts"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"AlertAPI.PatchAlertReq":{"type":"object","properties":{"assignee":{"type":"string","description":"The ID of the assignee for this alert"},"contextTags":{"type":"array","items":{"type":"string","description":"Tag to provide context for this alert","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30},"description":"the context tags for the alert","maxItems":10},"quality":{"type":"string","description":"The quality of this Alert","enum":["NOISE","USEFUL",""]},"status":{"type":"string","description":"The status of this Alert","enum":["OPEN","CLOSED","TRIAGED","RESOLVED"]}}},"AlertAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"AlertAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alerts/{id}":{"patch":{"tags":["alert"],"summary":"Update the status, assignee, quality or contextTags of an alert","operationId":"alert#patch","parameters":[{"name":"id","in":"path","description":"ID of the alert","required":true,"schema":{"type":"string","description":"ID of the alert"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.PatchAlertReq"}}}},"responses":{"200":{"description":"OK response."},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.NotFoundError"}}}}}}}}}
```

## GET /alerts

> List alerts

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"alert","description":"The alert api handles all operations for alerts"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"AlertAPI.ListResp":{"type":"object","properties":{"next":{"type":"string","description":"Pagination token for the next page of results"},"results":{"type":"array","items":{"$ref":"#/components/schemas/AlertAPI.Alert"}}},"required":["results"]},"AlertAPI.Alert":{"type":"object","properties":{"assignee":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The Actor that is assigned to this alert"},"context":{"description":"The context of this alert"},"contextTags":{"type":"array","items":{"type":"string","description":"Tag to provide context for this alert","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30},"description":"the context tags for the alert","maxItems":10},"createdAt":{"type":"string","description":"Date and time when the alert got created"},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/AlertAPI.Delivery"},"description":"The metadata around the alert's delivery attempts"},"detection":{"$ref":"#/components/schemas/AlertAPI.DetectionInfo"},"eventCount":{"type":"integer","description":"The number of events that have been received for this alert","format":"int64"},"firstEventOccurredAt":{"type":"string","description":"Date and time of this alert's first event"},"id":{"type":"string","description":"The unique identifier of this alert"},"lastReceivedEventAt":{"type":"string","description":"Date and time that the last event related to this alert was received"},"quality":{"type":"string","description":"The quality of this Alert","enum":["NOISE","USEFUL"]},"runbook":{"type":"string","description":"The runbook for this Alert, as extracted from its origin"},"severity":{"type":"string","description":"The severity of this Alert","enum":["CRITICAL","HIGH","MEDIUM","LOW","INFO"]},"status":{"type":"string","description":"The status of this Alert","enum":["OPEN","CLOSED","TRIAGED","RESOLVED"]},"systemError":{"$ref":"#/components/schemas/AlertAPI.SystemError"},"title":{"type":"string","description":"The title of this alert"},"type":{"type":"string","description":"The type of this alert"},"updatedBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The Actor that last updated the state of this alert"}},"required":["id","type","status"]},"AlertAPI.Delivery":{"type":"object","properties":{"dispatchedAt":{"type":"string"},"label":{"type":"string","description":"The label of the alert at where it was delivered (channel name/ID, jira ticket, asana issue, etc)"},"message":{"type":"string"},"outputId":{"type":"string"},"statusCode":{"type":"integer","format":"int64"},"success":{"type":"boolean"}},"required":["dispatchedAt","label","message","statusCode","success","outputId"]},"AlertAPI.DetectionInfo":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of this Detection"},"type":{"type":"string","description":"The type of this Detection","enum":["RULE","CORRELATION_RULE","POLICY","SCHEDULED_RULE"]}}},"AlertAPI.SystemError":{"type":"object","properties":{"detection":{"$ref":"#/components/schemas/AlertAPI.DetectionInfo"},"sourceId":{"type":"string","description":"The source ID of this SystemError"},"sourceType":{"type":"string","description":"The source type of this SystemError"},"type":{"type":"string","description":"The type of this SystemError"}}},"AlertAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alerts":{"get":{"tags":["alert"],"summary":"List alerts","operationId":"alert#list","parameters":[{"name":"type","in":"query","allowEmptyValue":true,"schema":{"type":"string","default":"ALERT","enum":["ALERT","DETECTION_ERROR","SYSTEM_ERROR"]}},{"name":"sub-type","in":"query","description":"The sub-type of the alert","allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","enum":["RULE","RULE_ERROR","SCHEDULED_RULE","SCHEDULED_RULE_ERROR","POLICY","SYSTEM_ERROR","CORRELATION_RULE","CORRELATION_RULE_ERROR"]},"description":"The sub-type of the alert"}},{"name":"cursor","in":"query","description":"the pagination token","allowEmptyValue":true,"schema":{"type":"string","description":"the pagination token"}},{"name":"limit","in":"query","description":"the maximum results to return","allowEmptyValue":true,"schema":{"type":"integer","description":"the maximum results to return","default":25,"format":"int64","maximum":50}},{"name":"created-after","in":"query","description":"The date and time after which the alerts were created. If empty we default to 30 days ago","allowEmptyValue":true,"schema":{"type":"string","description":"The date and time after which the alerts were created. If empty we default to 30 days ago"}},{"name":"created-before","in":"query","description":"The date and time before which the alerts were created. If empty we default to the current time","allowEmptyValue":true,"schema":{"type":"string","description":"The date and time before which the alerts were created. If empty we default to the current time"}},{"name":"detection-id","in":"query","description":"The detection ID to filter alerts by","allowEmptyValue":true,"schema":{"type":"string","description":"The detection ID to filter alerts by"}},{"name":"sort-dir","in":"query","description":"The sort direction of the results","allowEmptyValue":true,"schema":{"type":"string","description":"The sort direction of the results","default":"desc","enum":["asc","desc"]}},{"name":"name-contains","in":"query","description":"A string to search for in the alert name","allowEmptyValue":true,"schema":{"type":"string","description":"A string to search for in the alert name"}},{"name":"log-source","in":"query","description":"The log source of the alert","allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"},"description":"The log source of the alert"}},{"name":"log-type","in":"query","description":"The log type of the alert","allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"},"description":"The log type of the alert"}},{"name":"resource-type","in":"query","description":"The resource type of the alert","allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"},"description":"The resource type of the alert"}},{"name":"status","in":"query","description":"The status of the alert","allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","enum":["OPEN","CLOSED","TRIAGED","RESOLVED"]},"description":"The status of the alert"}},{"name":"severity","in":"query","description":"The severity of the alert","allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","enum":["CRITICAL","HIGH","MEDIUM","LOW","INFO"]},"description":"The severity of the alert"}},{"name":"assignee","in":"query","description":"The assignee of the alert. This should be a user id","allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string"},"description":"The assignee of the alert. This should be a user id"}},{"name":"event-count-min","in":"query","description":"The minimum number of events in the alert","allowEmptyValue":true,"schema":{"type":"integer","description":"The minimum number of events in the alert","format":"int64"}},{"name":"event-count-max","in":"query","description":"The maximum number of events in the alert","allowEmptyValue":true,"schema":{"type":"integer","description":"The maximum number of events in the alert","format":"int64"}},{"name":"quality","in":"query","description":"Filter by alert quality","allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","enum":["NOISE","USEFUL"]},"description":"Filter by alert quality"}},{"name":"context-tag","in":"query","description":"Filter by context tags applied to alerts","allowEmptyValue":true,"schema":{"type":"array","items":{"type":"string","description":"Tag to provide context for this alert","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30},"description":"Filter by context tags applied to alerts"}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.ListResp"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.BadRequestError"}}}}}}}}}
```

## PATCH /alerts

> Update the status, assignee, quality or contextTags of multiple alerts

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"alert","description":"The alert api handles all operations for alerts"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"AlertAPI.BulkPatchAlertReq2":{"type":"object","properties":{"assignee":{"type":"string","description":"The ID of the assignee for this alert"},"contextTags":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9_-]+$","minLength":1,"maxLength":30},"description":"the context tags for the alert","maxItems":10},"ids":{"type":"array","items":{"type":"string"},"description":"The IDs of the alerts to patch"},"quality":{"type":"string","description":"The quality of this Alert","enum":["NOISE","USEFUL",""]},"status":{"type":"string","description":"The status of this Alert","enum":["OPEN","CLOSED","TRIAGED","RESOLVED"]}},"required":["ids"]},"AlertAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"AlertAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alerts":{"patch":{"tags":["alert"],"summary":"Update the status, assignee, quality or contextTags of multiple alerts","operationId":"alert#bulkPatch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.BulkPatchAlertReq2"}}}},"responses":{"204":{"description":"No Content response."},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.NotFoundError"}}}}}}}}}
```

## GET /alerts/{id}/events

> List alert events

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"alert","description":"The alert api handles all operations for alerts"}],"servers":[{"url":"https://{api_host}","variables":{"api_host":{"default":"your-api-host"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{"AlertAPI.ListEventsResp":{"type":"object","properties":{"next":{"type":"string","description":"Pagination token for the next page of results"},"results":{"type":"array","items":{}}},"required":["results"]},"AlertAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"AlertAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alerts/{id}/events":{"get":{"tags":["alert"],"summary":"List alert events","operationId":"alert#events","parameters":[{"name":"cursor","in":"query","description":"the pagination token","allowEmptyValue":true,"schema":{"type":"string","description":"the pagination token"}},{"name":"limit","in":"query","description":"the maximum results to return","allowEmptyValue":true,"schema":{"type":"integer","description":"the maximum results to return","default":25,"format":"int64","maximum":50}},{"name":"id","in":"path","description":"The alert id","required":true,"schema":{"type":"string","description":"The alert id"}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.ListEventsResp"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertAPI.NotFoundError"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.panther.com/panther-developer-workflows/api/rest/alerts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.