> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://contentful.com/developers/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server. Users can add comments to an entry. This allows for teams to collaborate and have conversations. #### Availability Comments are globally available for all customers. ### Mentions in comments > **Info** > > The mentions in comments capability is not available for workflows. Mentions in comments allow you to tag collaborators in the comments tab of an entry. By including the "@" followed by an individual's or team's name, you can directly engage in conversations regarding feedback, workflow statuses, or general comments. Only when creating a comment that includes a mention of a collaborator, the mentioned recipient will receive an email notification. The following comments that do not include a mention of a user or team, such as replies or updates, will not be subject to notifications. > **Info** > > For a rich-text comment, the following `NodeTypes` are accepted: `document`, `paragraph`, `text` and now `mention`. To mention users, you must provide a `body` in Contentful's [rich-text format](/concepts/rich-text). There, include a node of type `mention` where you indicate the `user ID`, using the following code: ```js { "nodeType": "document", "data": {}, "content": [ { "nodeType": "paragraph", "data": {}, "content": [ { "nodeType": "text", "value": "Text ab with ", "marks": [], "data": {} }, { "nodeType": "mention", // new node type "data": { "target": { "sys": { "id": "userId", "type": "Link", "linkType": "User" } } }, "content": [] }, ] } ] } ``` To mention teams, instead of indicating the 'user ID' and a 'linkType: User', include the 'team ID' and use 'Team' as the 'linkType'. For example: ```js { "nodeType": "document", "data": {}, "content": [ { "nodeType": "paragraph", "data": {}, "content": [ { "nodeType": "text", "value": "Text ab with ", "marks": [], "data": {} }, { "nodeType": "mention", // new node type "data": { "target": { "sys": { "id": "teamId", "type": "Link", "linkType": "Team" } } }, "content": [] }, ] } ] } ``` To submit comments with `rich-text`, provide the following header: `x-contentful-comment-body-format` to mention a user in the comment with the value: `rich-text`. You can request a comment using either format `plain-text` or `rich-text` by passing either value in this header. The request for the header will return the following: ```js { "sys": { "version": 0, "parent": { "sys": { "id": "string", "linkType": "Comment", "type": "Link" } }, "updatedAt": "string", "updatedBy": { "sys": { "id": "string", "linkType": "User", "type": "Link" } }, "createdAt": "string", "createdBy": { "sys": { "id": "string", "linkType": "User", "type": "Link" } }, "parentEntity": { "sys": { "id": "string", "linkType": "Entry", "type": "Link" } }, "environment": { "sys": { "id": "string", "linkType": "Environment", "type": "Link" } }, "space": { "sys": { "id": "string", "linkType": "Space", "type": "Link" } }, "type": "Comment", "id": "string" }, "body": Object } ``` If you request a comment that was previously created as rich-text and request without a header or `plain-text` header specification, the comment will be returned in plain-text. In the `plain-text` representations, mentions will have the following format: `User(id=1xGZIRXr2WPnsLkKfREo0z)`. You can also fetch the `rich-text` representation of a `plain-text` comment by passing `rich-text` as the value in the above header. ### Comment schema A comment has two top level properties: `body` and `sys`. These are described in detail below. | Field | Type | Required | Description | | ------ | ---------------- | -------- | ----------------------------------------------------------------------------------------- | | body | String or Object | true | The body of the comment. String: maximum size of 512 bytes. Object: maximum of 100 nodes. | | status | String | false | The status of the comment, it can be either `active` or `resolved`. `active` by default. | | sys | Object | true | System resource properties | In addition to the [common sys properties](#/introduction/common-resource-attributes) comments have the following extra `sys` properties | Field | Type | Description | | ------------ | ---- | ----------------------------------------------------------- | | parentEntity | Link | A reference to the entry in which the comment exists | | parent | Link | A reference to the replied comment (optional) | | resolvedBy | Link | A reference to the user who resolved the comment (optional) | The property `resolvedBy` is only defined if the comment is resolved. Reopening a comment will remove the field from the sys property. ## Entry comments collection [Get all comments of an entry](/references/content-management-api/entry-comments/get-all-comments-of-an-entry) Use this endpoint to get all the comments of an entry. This API does not offer pagination, calls to it will return all the existing comments. It is possible to filter comments by optionally providing the `status` query parameter, if no value is provided comments with any status will be returned. #### Permissions Any user with read access to an entry can read all the comments in the entry. Space admins can read all the comments in any entry. [Create a comment](/references/content-management-api/entry-comments/create-a-comment) Use this endpoint to create a new comment. When using this endpoint, an ID will be automatically generated for the created comment and returned in the response. If you want to create a reply to a specific comment, you need to set the header `X-Contentful-Parent-Id` with the comment ID you want to reply to. To reference a specific field and locale with your comment, you can set the header `X-Contentful-Parent-Entity-Reference`. Only values specifying a path to a field and locale of the entry are considered valid, therefore the value must match the pattern `fields..`. There's a limit of 100 comments per entry. An attempt to create more than 100 comments will result in an error. #### Permissions Any user with read access to an entry can create comments in the entry. Space admins can create comments on any entry. #### Errors * A `400 - BadRequest` error is returned if there's an attempt to create more than 100 comments in one entry. * A `422 - ValidationFailed` error is returned if the `body` field has a value bigger than 512 bytes. ## Comment [Get a comment](/references/content-management-api/entry-comments/get-a-comment) Use this endpoint to fetch a comment with a specified ID. #### Permissions Any user with read access to an entry can read a comment in the entry. Space admins can read any comment in any entry. [Delete a comment](/references/content-management-api/entry-comments/delete-a-comment) Use this method to delete a comment. #### Permissions Comment creators can delete their own comments. Admins can delete any comment on any entry. [Update a comment](/references/content-management-api/entry-comments/update-a-comment) Use this method to modify the body of the comment. #### Permissions The creator or an admin can update the comment. #### Errors * An `403 - AccessDenied` error is returned if a user different from the comment creator or an admin changed the comment body. * A `422 - ValidationFailed` error is returned if the `body` field has a value bigger than 512 bytes. ## API Docs - Entry comments [Get all comments of an entry](https://contentful.com/developers/docs/references/content-management-api/entry-comments/get-all-comments-of-an-entry.md) - Entry comments [Create a comment](https://contentful.com/developers/docs/references/content-management-api/entry-comments/create-a-comment.md) - Entry comments [Get a comment](https://contentful.com/developers/docs/references/content-management-api/entry-comments/get-a-comment.md) - Entry comments [Update a comment](https://contentful.com/developers/docs/references/content-management-api/entry-comments/update-a-comment.md) - Entry comments [Delete a comment](https://contentful.com/developers/docs/references/content-management-api/entry-comments/delete-a-comment.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://contentful.com/developers/docs/openapi.json) - [OpenAPI YAML](https://contentful.com/developers/docs/openapi.yaml)