# Alert Comments

## Overview

Use these API operations to interact with [alert comments](https://docs.panther.com/alerts/alert-management#adding-comments-to-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 `POST` operations, your API token must have the `Manage Alerts` permission.

## Operations

## POST /alert-comments

> Create a comment for an alert

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"comment","description":"The comment api handles all operations for alerts comments"}],"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":{"CommentAPI.ModifyCommentReq":{"type":"object","properties":{"alertId":{"type":"string","description":"The alert ID the comment is associated with"},"body":{"type":"string","description":"The body of the comment"},"format":{"type":"string","description":"The format of the comment","enum":["PLAIN_TEXT","HTML"]}},"required":["alertId","body","format"]},"CommentAPI.Comment":{"type":"object","properties":{"alertId":{"type":"string","description":"The alert ID the comment is associated with"},"body":{"description":"The body of the comment"},"createdAt":{"type":"string","description":"The date the comment was created"},"createdBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The actor who created the comment"},"format":{"type":"string","description":"The format of the comment","enum":["PLAIN_TEXT","HTML"]},"id":{"type":"string","description":"The comment ID"},"updatedAt":{"type":"string","description":"The date the comment was updated"},"updatedBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The actor who updated the comment"}}},"CommentAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"CommentAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alert-comments":{"post":{"tags":["comment"],"summary":"Create a comment for an alert","operationId":"comment#create","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.ModifyCommentReq"}}}},"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.Comment"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.NotFoundError"}}}}}}}}}
```

## GET /alert-comments/{id}

> Get a comment for an alert

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"comment","description":"The comment api handles all operations for alerts comments"}],"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":{"CommentAPI.Comment":{"type":"object","properties":{"alertId":{"type":"string","description":"The alert ID the comment is associated with"},"body":{"description":"The body of the comment"},"createdAt":{"type":"string","description":"The date the comment was created"},"createdBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The actor who created the comment"},"format":{"type":"string","description":"The format of the comment","enum":["PLAIN_TEXT","HTML"]},"id":{"type":"string","description":"The comment ID"},"updatedAt":{"type":"string","description":"The date the comment was updated"},"updatedBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The actor who updated the comment"}}},"CommentAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"CommentAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alert-comments/{id}":{"get":{"tags":["comment"],"summary":"Get a comment for an alert","operationId":"comment#get","parameters":[{"name":"id","in":"path","description":"ID of the comment","required":true,"schema":{"type":"string","description":"ID of the comment"}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.Comment"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.NotFoundError"}}}}}}}}}
```

## POST /alert-comments/{id}

> Update a comment for an alert

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"comment","description":"The comment api handles all operations for alerts comments"}],"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":{"CommentAPI.ModifyCommentReq":{"type":"object","properties":{"alertId":{"type":"string","description":"The alert ID the comment is associated with"},"body":{"type":"string","description":"The body of the comment"},"format":{"type":"string","description":"The format of the comment","enum":["PLAIN_TEXT","HTML"]}},"required":["alertId","body","format"]},"CommentAPI.Comment":{"type":"object","properties":{"alertId":{"type":"string","description":"The alert ID the comment is associated with"},"body":{"description":"The body of the comment"},"createdAt":{"type":"string","description":"The date the comment was created"},"createdBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The actor who created the comment"},"format":{"type":"string","description":"The format of the comment","enum":["PLAIN_TEXT","HTML"]},"id":{"type":"string","description":"The comment ID"},"updatedAt":{"type":"string","description":"The date the comment was updated"},"updatedBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The actor who updated the comment"}}},"CommentAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"CommentAPI.NotFoundError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alert-comments/{id}":{"post":{"tags":["comment"],"summary":"Update a comment for an alert","operationId":"comment#update","parameters":[{"name":"id","in":"path","description":"ID of the comment","required":true,"schema":{"type":"string","description":"ID of the comment"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.ModifyCommentReq"}}}},"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.Comment"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.BadRequestError"}}}},"404":{"description":"not_found: Not Found response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.NotFoundError"}}}}}}}}}
```

## GET /alert-comments

> List alert comments

```json
{"openapi":"3.0.3","info":{"title":"Panther REST API","version":"1.0"},"tags":[{"name":"comment","description":"The comment api handles all operations for alerts comments"}],"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":{"CommentAPI.ListResp":{"type":"object","properties":{"next":{"type":"string","description":"Pagination token for the next page of results"},"results":{"type":"array","items":{"$ref":"#/components/schemas/CommentAPI.Comment"}}},"required":["results"]},"CommentAPI.Comment":{"type":"object","properties":{"alertId":{"type":"string","description":"The alert ID the comment is associated with"},"body":{"description":"The body of the comment"},"createdAt":{"type":"string","description":"The date the comment was created"},"createdBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The actor who created the comment"},"format":{"type":"string","description":"The format of the comment","enum":["PLAIN_TEXT","HTML"]},"id":{"type":"string","description":"The comment ID"},"updatedAt":{"type":"string","description":"The date the comment was updated"},"updatedBy":{"type":"object","properties":{"id":{"type":"string","enum":["user","api-token","system"]},"type":{"type":"string"}},"description":"The actor who updated the comment"}}},"CommentAPI.BadRequestError":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"paths":{"/alert-comments":{"get":{"tags":["comment"],"summary":"List alert comments","operationId":"comment#list","parameters":[{"name":"alert-id","in":"query","description":"The alert ID the comments are associated with","allowEmptyValue":true,"required":true,"schema":{"type":"string","description":"The alert ID the comments are associated with"}},{"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}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.ListResp"}}}},"400":{"description":"bad_request: Bad Request response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentAPI.BadRequestError"}}}}}}}}}
```