# Alert Comments

## Overview

Use these API operations to interact with [alert comments](/alerts/alert-management.md#adding-comments-to-alerts) 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 `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"}}}}}}}}}
```


---

# 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/alert-comments.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.