> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# comment

> sift/comment/v1/comment.proto

<a name="sift_comment_v1_comment-proto" />

<a name="sift_comment_v1_comment-proto-services" />

## Services

*RPC methods exposed by this API.*

### CommentService

| Method        | Request                                       | Response                                        | Description                                                                                                                         |
| :------------ | :-------------------------------------------- | :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| CreateComment | [CreateCommentRequest](#createcommentrequest) | [CreateCommentResponse](#createcommentresponse) | Creates a comment on a resource.                                                                                                    |
| ListComments  | [ListCommentsRequest](#listcommentsrequest)   | [ListCommentsResponse](#listcommentsresponse)   | Retrieves comments using an optional filter. Commonly used to bulk-fetch comments for a set of resource IDs of a given entity type. |
| UpdateComment | [UpdateCommentRequest](#updatecommentrequest) | [UpdateCommentResponse](#updatecommentresponse) | Updates the body of an existing comment.                                                                                            |
| DeleteComment | [DeleteCommentRequest](#deletecommentrequest) | [DeleteCommentResponse](#deletecommentresponse) | Deletes a comment.                                                                                                                  |

<a name="sift_comment_v1_comment-proto-messages" />

## Messages

*Data models used across requests/responses.*

### Comment

A single comment attached to a resource.

| Field                   | Type                                      | Label    | Description                                                                             |
| :---------------------- | :---------------------------------------- | :------- | :-------------------------------------------------------------------------------------- |
| comment\_id             | string                                    |          |                                                                                         |
| resource\_id            | string                                    |          | The ID of the resource the comment is attached to (e.g. a canvas\_cell\_execution\_id). |
| entity\_type            | [CommentEntityType](#commententitytype)   |          | The kind of resource `resource_id` refers to.                                           |
| created\_date           | google.protobuf.Timestamp                 |          |                                                                                         |
| modified\_date          | google.protobuf.Timestamp                 |          |                                                                                         |
| created\_by\_user\_id   | string                                    |          |                                                                                         |
| created\_by\_user\_name | string                                    |          |                                                                                         |
| body                    | [CommentBodyElement](#commentbodyelement) | repeated | The rich-text body of the comment.                                                      |

### CommentBodyElement

A single element of a comment body. Either plain text or a user mention.

| Field         | Type                                              | Label | Description                            |
| :------------ | :------------------------------------------------ | :---- | :------------------------------------- |
| type          | [CommentBodyElementType](#commentbodyelementtype) |       |                                        |
| text          | string                                            |       | Only set when `type` is TEXT.          |
| user\_mention | [CommentUserMention](#commentusermention)         |       | Only set when `type` is USER\_MENTION. |

### CommentUserMention

| Field       | Type   | Label | Description |
| :---------- | :----- | :---- | :---------- |
| user\_id    | string |       |             |
| user\_email | string |       |             |

### CreateCommentRequest

The request for a call to `CommentService_CreateComment`.

| Field        | Type                                      | Label    | Description                                      |
| :----------- | :---------------------------------------- | :------- | :----------------------------------------------- |
| resource\_id | string                                    |          | The ID of the resource to attach the comment to. |
| entity\_type | [CommentEntityType](#commententitytype)   |          | The kind of resource `resource_id` refers to.    |
| body         | [CommentBodyElement](#commentbodyelement) | repeated | The rich-text body of the new comment.           |

### CreateCommentResponse

The response of a call to `CommentService_CreateComment`.

| Field   | Type                | Label | Description |
| :------ | :------------------ | :---- | :---------- |
| comment | [Comment](#comment) |       |             |

### DeleteCommentRequest

The request for a call to `CommentService_DeleteComment`.

| Field       | Type   | Label | Description |
| :---------- | :----- | :---- | :---------- |
| comment\_id | string |       |             |

### DeleteCommentResponse

The response of a call to `CommentService_DeleteComment`.

*This message has no fields.*

### ListCommentsRequest

The request for a call to `CommentService_ListComments`. Commonly invoked
with a CEL `filter` of the form
`entity_type == "CANVAS_CELL_EXECUTION" && resource_id in ["<uuid>", ...]`
to bulk-fetch comments for a set of resources.

| Field       | Type   | Label | Description                                                                                                                                                                                                                           |
| :---------- | :----- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| page\_size  | uint32 |       | The maximum number of comments to return. Defaults to 50, max 1000.                                                                                                                                                                   |
| page\_token | string |       | A page token, received from a previous `ListComments` call.                                                                                                                                                                           |
| filter      | string |       | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `comment_id`, `resource_id`, `entity_type`, `created_by_user_id`, `created_date`, and `modified_date`.      |
| order\_by   | string |       | How to order the retrieved comments. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are `created_date` and `modified_date`. Defaults to `created_date` ascending (oldest-first). |

### ListCommentsResponse

The response of a call to `CommentService_ListComments`.

| Field             | Type                | Label    | Description |
| :---------------- | :------------------ | :------- | :---------- |
| comments          | [Comment](#comment) | repeated |             |
| next\_page\_token | string              |          |             |

### UpdateCommentRequest

The request for a call to `CommentService_UpdateComment`.

| Field        | Type                | Label | Description                                                         |
| :----------- | :------------------ | :---- | :------------------------------------------------------------------ |
| comment      | [Comment](#comment) |       |                                                                     |
| update\_mask | string              |       | Comma-separated list of fields to update. Only `body` is supported. |

### UpdateCommentResponse

The response of a call to `CommentService_UpdateComment`.

| Field   | Type                | Label | Description |
| :------ | :------------------ | :---- | :---------- |
| comment | [Comment](#comment) |       |             |

<a name="sift_comment_v1_comment-proto-enums" />

## Enums

*Allowed constant values used in message fields.*

### CommentBodyElementType

| Name                                        | Number | Description |
| :------------------------------------------ | :----- | :---------- |
| COMMENT\_BODY\_ELEMENT\_TYPE\_UNSPECIFIED   | 0      |             |
| COMMENT\_BODY\_ELEMENT\_TYPE\_TEXT          | 1      |             |
| COMMENT\_BODY\_ELEMENT\_TYPE\_USER\_MENTION | 2      |             |

### CommentEntityType

The type of resource a comment is attached to. Designed to be extended over time.

| Name                                           | Number | Description |
| :--------------------------------------------- | :----- | :---------- |
| COMMENT\_ENTITY\_TYPE\_UNSPECIFIED             | 0      |             |
| COMMENT\_ENTITY\_TYPE\_CANVAS\_CELL\_EXECUTION | 1      |             |