# Delete comment by ID

> DELETE /v1/comments/{id} · Core resources API

Source: https://developer.kustomer.com/api/core-resources/delete-comment-by-id

```http
DELETE https://{orgname}.api.kustomerapp.com/v1/comments/{id}
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.note.delete`; or legacy `org.user.note.write`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Deletes a comment based on the unique comment ID.

## About Comments

A comment is a short internal note that agents leave on a custom object record, such as a task. Customers never see comments; they are for discussion among your team, with optional mentions and attachments.

Comments let agents discuss a [KObject](https://developer.kustomer.com/api/core-resources#kobjects-custom-objects), for example to record progress on a task or ask a teammate about a return. They appear on the record in the agent desktop for Klasses that have the `commentable` mixin. Comments are separate from [notes](https://developer.kustomer.com/api/core-resources#notes): notes attach to customers and conversations, while comments attach only to KObjects.

A comment is created against one KObject and stays attached to it. Its `body` can be edited later, and it is removed with `DELETE`. Only the comment's author can edit or delete it, unless the caller has admin access to notes. Responses also include relationships to the related customer, conversation and Klass, and to the assigned user and team where there are any.

#### Key fields

| Field | Meaning |
| --- | --- |
| `body` | Required. The comment text, up to 10,240 characters. |
| `userMentions` | Up to 20 mentions, each with a `user` or a `team` ID. |
| `attachments` | Files attached to the comment. Read them back with `include=attachments`, or manage them with the [comment attachments](https://developer.kustomer.com/api/core-resources#comments-attachments) endpoints. |
| `importedAt` | Marks a comment you are importing from another system. |
| `object` | In responses, the KObject the comment belongs to. |

`createdAt`, `modifiedAt`, `deletedAt` and the `createdBy`, `modifiedBy` and `deletedBy` relationships record who did what and when.

#### Which endpoint to use

| To | Call |
| --- | --- |
| List the comments on a KObject | [`GET /v1/kobjects/{id}/comments`](https://developer.kustomer.com/api/core-resources/get-comments-by-kobject-id) |
| Add a comment to a KObject | [`POST /v1/kobjects/{id}/comments`](https://developer.kustomer.com/api/core-resources/create-comment-on-kobject) |
| Read one or several comments | [`GET /v1/comments/{id}`](https://developer.kustomer.com/api/core-resources/get-comment-by-id) |
| Edit or delete a comment | [`PUT`](https://developer.kustomer.com/api/core-resources/update-comment-by-id) or [`DELETE /v1/comments/{id}`](https://developer.kustomer.com/api/core-resources/delete-comment-by-id) |

The list endpoint takes the KObject's ID (no Klass name needed), pages with `page` and `pageSize`, and sorts by `createdAt` with `sort=asc` or `sort=desc`. `GET /v1/comments/{id}` accepts a comma-separated list of IDs to fetch several comments at once. Permissions differ by endpoint: listing comments needs KObject read access, while reading, creating, updating and deleting individual comments use note roles (such as `org.permission.note.create`), so give your API key both.

Related: [KObjects (custom objects)](https://developer.kustomer.com/api/core-resources#kobjects-custom-objects), [Comment attachments](https://developer.kustomer.com/api/core-resources#comments-attachments), [Notes](https://developer.kustomer.com/api/core-resources#notes)

### Recipes

#### 1. Comment on a task and mention a teammate

Post an update on a custom object record from your system, such as a status change on a return, and notify the person who needs to act.

**Step 1.** [`GET /v1/klasses/{name}/externalId={externalId}`](https://developer.kustomer.com/api/core-resources/get-kobject-by-external-id.md). Find the KObject by your own ID and keep its `id`. Comment endpoints take the KObject ID only, with no Klass name.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/klasses/$KLASS/externalId=$RETURN_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
KOBJECT_ID=$(kusty api GET "/v1/klasses/$KLASS/externalId=$RETURN_ID" | jq -r '.data.id')
```

**Step 2.** [`GET /v1/users`](https://developer.kustomer.com/api/access-management/get-users.md). Look up the teammate's user ID by email. Mentions take IDs, not names.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/users?email=$TEAMMATE_EMAIL" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
USER_ID=$(kusty api GET /v1/users --query email=$TEAMMATE_EMAIL | jq -r '.data[0].id')
```

**Step 3.** [`POST /v1/kobjects/{id}/comments`](https://developer.kustomer.com/api/core-resources/create-comment-on-kobject.md). Post the comment with `body` and up to 20 `userMentions`, each with a `user` or a `team` ID. The comment is created as the user behind your API key, who becomes its author.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/kobjects/$KOBJECT_ID/comments" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"body\": \"Return received at the warehouse. Please approve the refund.\", \"userMentions\": [{\"user\": \"$USER_ID\"}]}"
```

```bash title="kusty"
kusty api POST /v1/kobjects/$KOBJECT_ID/comments \
  --field body="Return received at the warehouse. Please approve the refund." \
  --field "userMentions:=[{\"user\": \"$USER_ID\"}]"
```

> Agents see comments only on Klasses with the `commentable` mixin; see [Klasses](https://developer.kustomer.com/api/core-resources#klasses).

#### 2. Export a record's comment thread

Copy the full discussion on a KObject into another system, such as a ticket in your returns tool, oldest comment first.

**Step 1.** [`GET /v1/kobjects/{id}/comments`](https://developer.kustomer.com/api/core-resources/get-comments-by-kobject-id.md). Page through the KObject's comments with `sort=asc` for chronological order. Add `include=attachments` to get the attached files' details in the same response.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/kobjects/$KOBJECT_ID/comments?sort=asc&include=attachments&pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/kobjects/$KOBJECT_ID/comments --query sort=asc --all \
  | jq -r '.data | [.attributes.createdAt, .relationships.createdBy.data.id, .attributes.body] | @tsv' > thread.tsv
```

**Step 2.** [`GET /v1/users/{id}`](https://developer.kustomer.com/api/access-management/get-user-by-id.md). Comments carry the author's user ID. Look each author up once and cache the name.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/users/$USER_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/users/$USER_ID --fields attributes.displayName
```

#### 3. Edit a comment without overwriting a newer change

Correct a comment your integration posted, failing safely if someone changed it in the meantime.

**Step 1.** [`GET /v1/comments/{id}`](https://developer.kustomer.com/api/core-resources/get-comment-by-id.md). Read the comment for its current `body` and `rev`.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/comments/$COMMENT_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/comments/$COMMENT_ID --fields attributes.body,attributes.rev
```

**Step 2.** [`PUT /v1/comments/{id}`](https://developer.kustomer.com/api/core-resources/update-comment-by-id.md). Send the new `body` with the `rev` you read. A `409 Conflict` means the comment changed since then; read it again before retrying. Only the comment's author can edit it, unless your key has admin access to notes, so edit with the same API key that posted it.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/comments/$COMMENT_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"body\": \"Return received. Refund approved on 21 Oct.\", \"rev\": $REV}"
```

```bash title="kusty"
kusty api PUT /v1/comments/$COMMENT_ID \
  --field body="Return received. Refund approved on 21 Oct." --field rev:=$REV
```

> To remove a comment instead, call [`DELETE /v1/comments/{id}`](https://developer.kustomer.com/api/core-resources/delete-comment-by-id). The same author rule applies.

### Example object

A real record from [`GET /v1/comments/{id}`](https://developer.kustomer.com/api/core-resources/get-comment-by-id.md):

```json
{
  "type": "comment",
  "id": "57cf1d65079e780006e34f79",
  "attributes": {
    "body": "Followed up with the customer about this order.",
    "createdAt": "2016-09-06T19:47:49.235Z",
    "updatedAt": "2016-09-06T19:47:49.236Z",
    "rev": 1
  },
  "relationships": {
    "object": {
      "links": {
        "self": "/v1/kobjects/57ce17d2369f251400fc8e89"
      },
      "data": {
        "type": "kobject",
        "id": "57ce17d2369f251400fc8e89"
      }
    },
    "org": {
      "links": {
        "self": "/v1/orgs/57bb5d2e32e83a130052e94e"
      },
      "data": {
        "type": "org",
        "id": "57bb5d2e32e83a130052e94e"
      }
    },
    "createdBy": {
      "links": {
        "self": "/v1/users/57bb5d2e32e83a130052e94f"
      },
      "data": {
        "type": "user",
        "id": "57bb5d2e32e83a130052e94f"
      }
    }
  },
  "links": {
    "self": "/v1/comments/57cf1d65079e780006e34f79"
  }
}
```

Fields:

- `attributes.body` (string): The comment text, up to 10,240 characters. Required on create, and the main thing you change on `PUT`.
- `attributes.createdAt` (string (date-time)): When the comment was posted. Comment lists sort by it, oldest first unless you pass `sort=desc`.
- `attributes.updatedAt` (string (date-time)): Changes whenever the comment is edited.
- `attributes.rev` (number): The revision, incremented on every edit. Send it back on `PUT` to fail with `409 Conflict` if the comment changed since you read it.
- `relationships.object` (object): The KObject the comment is on. It's fixed when the comment is created and can't be moved to another record.
- `relationships.createdBy` (object): The comment's author, the user behind the API key that created it. Only the author can edit or delete a comment, unless the caller has admin access to notes.

### Relationships

- Points to **KObjects (custom objects)** via `relationships.object`: The KObject a comment is on. Comments attach only to KObjects; list a KObject's comments with `GET /v1/kobjects/{id}/comments`.
- Points to **Customers** via `relationships.customer`: On a comment, the customer that the commented KObject belongs to. It's copied from the KObject and is absent when the KObject has no customer.
- Points to **Conversations** via `relationships.conversation`: On a comment, the conversation the commented KObject is linked to, when there is one.
- Points to **Klasses** via `relationships.klass`: On a comment, the Klass of the KObject it's on. `data.id` is the Klass `name`, not its ID.
- Points to **Users** via `relationships.userMentions` (list): The users mentioned in a comment, sent as `userMentions` when you create or edit it. An entry can be a team instead, typed `team`.
- Points to **Attachments** via `relationships.attachments` (list): Files attached to a comment. Request them with `include=attachments`, or manage them with the comment attachment endpoints.

### Permissions

Fewest roles for a read-only integration: `org.permission.kobject.kobject_*.read`, `org.permission.note.read`. For every endpoint: `org.permission.kobject.kobject_*.read`, `org.permission.note.create`, `org.permission.note.delete`, `org.permission.note.read`, `org.permission.note.update`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Unique comment ID. Supports a comma-separated list of IDs for multi-get. |

## Responses

### 204

No Content

### 401

Unauthorized

### 403

Forbidden

### 404

Not Found

## Example request

```bash
curl --request DELETE \
  --url 'https://api.kustomerapp.com/v1/comments/57cf1d65079e780006e34f79' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```