---
myst:
  html_meta:
    "description": "Plone offers to users a feature to post comments on any content object with plone.app.discussion."
    "property=og:description": "Plone offers to users a feature to post comments on any content object with plone.app.discussion."
    "property=og:title": "Comments"
    "keywords": "Plone, plone.restapi, REST, API, Comments, plone.app.discussion"
---

# Comments

```{versionchanged} Plone 6.1
Discussion is disabled by default in Plone 6.1 and later.
To enable discussion, see the Plone 6.1 upgrade guide section {ref}`backend-upgrade-plone-v61-discussion-label`.
```

Discussion is a feature that allows your site visitors to comment on web pages for any content object.

Commenting can be enabled globally for specific content types and for single content objects.

When commenting is enabled on your content object, you can retrieve a list of all existing comments, add new comments, reply to existing comments, or delete a comment.


## Listing Comments

You can list the existing comment on a content object by sending a `GET` request to the URL of the content object and appending `/@comments`:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/comments_get.req
```

The server will respond with a `Status 200` and a batched list of all comments:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/comments_get.resp
:language: http
```

The following fields are returned.

- `@id`: Link to the current endpoint
- `items`: a list of comments for the current resource
- `items_total`: the total number of comments for the resource
- `batching`: batching information

The `items` attribute returns a list of comments.
Each comment provides the following fields.

- `@id`: hyperlink to the comment
- `@parent`: (optional) the parent comment
- `author_name`: the full name of the author of this comment
- `author_username`: the username of the author of this comment
- `comment_id`: the comment ID uniquely identifies the comment
- `in_reply_to`: the comment ID of the parent comment
- `creation_date`: when the comment was placed
- `modification_date`: when the comment was last updated
- `text`: contains a `mime-type` and `text` attribute with the text of the comment.
  Default `mime-type` is `text/plain`.
- `user_notification`: boolean value to indicate if the author of the comment requested notifications on replies


## Adding a Comment

To add a new comment to a content object, send a `POST` request to the URL of the content object and append `/@comments` to the URL.
The body of the request needs to contain a JSON structure with a `text` attribute that contains the comment text:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/comments_add_root.req
```

If the creation of the comment has been successful, the server will respond with a {term}`204 No Content` status and the URL of the newly created comment in the location header:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/comments_add_root.resp
:language: http
```


## Replying to a Comment

To add a direct reply to an existing comment, send a `POST` request to the URL of the comment
 to which you want to reply.
The body of the request needs to contain a JSON structure with a `text` attribute that contains the comment text:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/comments_add_sub.req
```

If the creation of the comment has been successful, the server will respond with a {term}`204 No Content` status and the URL of the newly created comment in the location header:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/comments_add_sub.resp
:language: http
```


## Updating a Comment

```{note}
The permission to update a comment is, by default, only granted to the creator (owner role) of the comment.
```

An existing comment can be updated by sending a `PATCH` request to the URL of the comment.
The request body needs to contain a JSON structure with at least a `text` attribute:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/comments_update.req
```

The server will respond with a {term}`204 No Content` response and a location header with the comment URL when the comment has been updated successfully:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/comments_update.resp
:language: http
```


## Deleting a Comment

An existing comment can be deleted by sending a `DELETE` request to the URL of the comment.

```{note}
Deleting a comment will, by default, also delete all existing replies to that comment.
```

```{eval-rst}
..  http:example:: curl httpie python-requests
         :request: ../../../src/plone/restapi/tests/http-examples/comments_delete.req
```

When the comment has been deleted successfully, the server will respond with a {term}`204 No Content` response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/comments_delete.resp
:language: http
```