# Kiteworks API — comments Operations

**7 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/comments.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/comments.json)

> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.

---

## GET /rest/comments/{id}

**Summary:** Get a comment

Returns the details of the specified comment, including the file it is attached to and the comment text. **Requires `comment_view` permission on the associated file.**

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the comment. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the comment record. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Comment):**

```json
{
  "id": 201,
  "parent_id": 0,
  "object_id": 7,
  "folder_id": 3,
  "user_id": 5,
  "created": "2024-03-15T10:00:00+00:00",
  "modified": "2024-03-15T10:00:00+00:00",
  "contents": "Please review section 3.",
  "deleted": false,
  "is_comment": true
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/comments/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier of the comment.

url = f"https://{{instance}}.kiteworks.com/rest/comments/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## PUT /rest/comments/{id}

**Summary:** Update a comment

Updates the text of the specified comment. **Requires `comment_edit` permission on the associated file.** Only the comment author or a folder manager may update the comment.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the comment. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `contents` | string | yes | Text content of the comment |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the updated comment record. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_MAX_VALUE, ERR_INPUT_HTML_TAGS_INVALID, ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Comment updated):**

```json
{
  "id": 201,
  "parent_id": 0,
  "object_id": 7,
  "folder_id": 3,
  "user_id": 5,
  "created": "2024-03-15T10:00:00+00:00",
  "modified": "2024-03-16T08:00:00+00:00",
  "contents": "Please review section 3 and section 4.",
  "deleted": false,
  "is_comment": true
}
```

**422 (ERR_INPUT_HTML_TAGS_INVALID):**

```json
{
  "errors": {
    "code": "ERR_INPUT_HTML_TAGS_INVALID",
    "message": "Cannot contain HTML tags other than B, I, or U"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

```json
{
  "errors": {
    "code": "ERR_INPUT_REQUIRED",
    "message": "Field is required"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/comments/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "contents": "string",
         "addLinks": true
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier of the comment.

url = f"https://{{instance}}.kiteworks.com/rest/comments/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "contents": "string",
  "addLinks": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/comments/{id}

**Summary:** Delete a comment

Deletes the specified comment. **Requires `comment_delete` permission on the associated file.** Only the comment author or a folder manager may delete the comment.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the comment. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The comment was successfully deleted. Returns no content. |
| 490 | Request blocked by WAF |

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/comments/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier of the comment.

url = f"https://{{instance}}.kiteworks.com/rest/comments/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```

---

## GET /rest/files/{id}/comments

**Summary:** Get file comments

Returns a list of comments on the specified file. **Requires `comment_view` permission on the file.**

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file. |
| `parentId` | query | no | Unique identifier of the parent comment |
| `parentId:in` | query | no | Unique identifier of the parent comment. Search for results that match any of the specified values for this parameter. |
| `userId` | query | no | Unique identifier of the comment author |
| `userId:in` | query | no | Unique identifier of the comment author. Search for results that match any of the specified values for this parameter. |
| `created` | query | no | The creation date of the comment. |
| `created:gt` | query | no | The creation date of the comment.. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | The creation date of the comment.. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | The creation date of the comment.. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | The creation date of the comment.. Search for results where this parameter value is less than or equal to the specified value. |
| `modified` | query | no | The last modification date of the comment. |
| `modified:gt` | query | no | The last modification date of the comment.. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | The last modification date of the comment.. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | The last modification date of the comment.. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | The last modification date of the comment.. Search for results where this parameter value is less than or equal to the specified value. |
| `contents:contains` | query | no | Content of the comment. Search for results that contain the specified characters in this parameter. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of comments for the specified file. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (File comment list):**

```json
{
  "data": [
    {
      "id": 201,
      "parent_id": 0,
      "object_id": 7,
      "folder_id": 3,
      "user_id": 5,
      "created": "2024-03-15T10:00:00+00:00",
      "modified": "2024-03-15T10:00:00+00:00",
      "contents": "Please review section 3.",
      "deleted": false,
      "is_comment": true
    },
    {
      "id": 202,
      "parent_id": 201,
      "object_id": 7,
      "folder_id": 3,
      "user_id": 3,
      "created": "2024-03-15T11:00:00+00:00",
      "modified": "2024-03-15T11:00:00+00:00",
      "contents": "Done, updated section 3.",
      "deleted": false,
      "is_comment": true
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 20
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/files/:id/comments" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier (UUID) of the file.

url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/comments"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## POST /rest/files/{id}/comments

**Summary:** Add file comment

Adds a comment to the specified file. To reply to an existing comment, include a `parentId` in the request body. **Requires `comment_add` permission on the file.**

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the file. |
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `mode` | query | no | Determines the detail level of the response body. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `parentId` | integer | no | Unique identifier of the parent comment. Set this value when replying to an existing comment |
| `contents` | string | yes | Text content of the comment |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the newly created comment record. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_MAX_VALUE, ERR_INPUT_HTML_TAGS_INVALID, ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Comment created):**

```json
{
  "id": 203,
  "parent_id": 0,
  "object_id": 7,
  "folder_id": 3,
  "user_id": 5,
  "created": "2024-03-16T09:00:00+00:00",
  "modified": "2024-03-16T09:00:00+00:00",
  "contents": "Looks good to me.",
  "deleted": false,
  "is_comment": true
}
```

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**422 (ERR_INPUT_HTML_TAGS_INVALID):**

```json
{
  "errors": {
    "code": "ERR_INPUT_HTML_TAGS_INVALID",
    "message": "Cannot contain HTML tags other than B, I, or U"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

```json
{
  "errors": {
    "code": "ERR_INPUT_REQUIRED",
    "message": "Field is required"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/files/:id/comments" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "parentId": 1,
         "contents": "string",
         "addLinks": true
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier (UUID) of the file.

url = f"https://{{instance}}.kiteworks.com/rest/files/{id}/comments"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "parentId": 1,
  "contents": "string",
  "addLinks": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/folders/{id}/comments

**Summary:** List comments for the folder

Returns all comments on files within the specified folder. **Requires `comment_view` permission on the folder.**

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier (UUID) of the folder. |
| `parentId` | query | no | Unique identifier of the parent comment |
| `parentId:in` | query | no | Unique identifier of the parent comment. Search for results that match any of the specified values for this parameter. |
| `userId` | query | no | Unique identifier of the comment author |
| `userId:in` | query | no | Unique identifier of the comment author. Search for results that match any of the specified values for this parameter. |
| `created` | query | no | The creation date of the comment. |
| `created:gt` | query | no | The creation date of the comment.. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | The creation date of the comment.. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | The creation date of the comment.. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | The creation date of the comment.. Search for results where this parameter value is less than or equal to the specified value. |
| `modified` | query | no | The last modification date of the comment. |
| `modified:gt` | query | no | The last modification date of the comment.. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | The last modification date of the comment.. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | The last modification date of the comment.. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | The last modification date of the comment.. Search for results where this parameter value is less than or equal to the specified value. |
| `contents:contains` | query | no | Content of the comment. Search for results that contain the specified characters in this parameter. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of comments for files within the specified folder. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Folder comment list):**

```json
{
  "data": [
    {
      "id": 201,
      "parent_id": 0,
      "object_id": 7,
      "folder_id": 3,
      "user_id": 5,
      "created": "2024-03-15T10:00:00+00:00",
      "modified": "2024-03-15T10:00:00+00:00",
      "contents": "Please review section 3.",
      "deleted": false,
      "is_comment": true
    },
    {
      "id": 202,
      "parent_id": 201,
      "object_id": 7,
      "folder_id": 3,
      "user_id": 3,
      "created": "2024-03-15T11:00:00+00:00",
      "modified": "2024-03-15T11:00:00+00:00",
      "contents": "Done, updated section 3.",
      "deleted": false,
      "is_comment": true
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 20
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/folders/:id/comments" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier (UUID) of the folder.

url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/comments"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## GET /rest/permissions/comment/{comment_id}

**Summary:** Return the list of permissions available on a comment

Returns the list of actions the current user is allowed to perform on the specified comment, such as editing or deleting it.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `comment_id` | path | yes | ID of the comment |
| `id` | query | no | Unique action identifier |
| `id:in` | query | no | Unique action identifier. Search for results that match any of the specified values for this parameter. |
| `name` | query | no | Action name |
| `name:contains` | query | no | Action name. Search for results that contain the specified characters in this parameter. |
| `allowed` | query | no | Determines if one has permissions to perform action |
| `enabled` | query | no | Determines if the given action is available considering the current object state (locked, deleted, etc.). |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Comment permissions retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (CommentPermissions):**

```json
{
  "data": [
    {
      "id": "COMMENT_EDIT",
      "name": "Edit Comment",
      "allowed": true
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/permissions/comment/:comment_id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

comment_id = "VALUE"  # ID of the comment

url = f"https://{{instance}}.kiteworks.com/rest/permissions/comment/{comment_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---