# Alerts

## Overview

Use these API operations to interact with [alerts](https://docs.panther.com/alerts) in Panther.

To call the API, see the [How to use the Panther REST API](https://docs.panther.com/panther-developer-workflows/api/rest/..#how-to-use-the-panther-rest-api) instructions—including [directions for how to invoke it directly from this documentation page](https://docs.panther.com/panther-developer-workflows/api/rest/..#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"}}}}}}}}}
```