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

# Comments

> Add and manage comments on translation keys.

The **Comments** API lets you programmatically add, update, resolve, and delete comments on translation keys. Comments support threaded discussions and can be scoped to a specific language.

## Endpoints

```
POST   /api/projects/:projectId/keys/:keyId/comments                        Add a comment
GET    /api/projects/:projectId/keys/:keyId/comments                        List comments
PATCH  /api/projects/:projectId/keys/:keyId/comments/:commentId             Update a comment
DELETE /api/projects/:projectId/keys/:keyId/comments/:commentId             Delete a comment
PATCH  /api/projects/:projectId/keys/:keyId/comments/:commentId/resolve     Resolve/unresolve a comment
```

## Add a Comment

```bash theme={null}
curl -X POST https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/comments \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Does this refer to shopping cart checkout or hotel checkout?",
    "language": "fr",
    "parentId": null
  }'
```

**Request body:**

| Field      | Type   | Required | Description                                                                                             |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `body`     | string | Yes      | The comment text.                                                                                       |
| `language` | string | No       | Language code (e.g. `fr`) to scope this comment to a specific translation. Omit for key-level comments. |
| `parentId` | string | No       | ID of a parent comment to create a threaded reply.                                                      |

**Response:**

```json theme={null}
{
  "_id": "cmt_abc123",
  "keyId": "key_abc123",
  "projectId": "proj_6abc123def456",
  "language": "fr",
  "authorId": "user_xyz",
  "authorName": "Alice Martin",
  "body": "Does this refer to shopping cart checkout or hotel checkout?",
  "parentId": null,
  "resolved": false,
  "created": "2025-03-02T14:30:00.000Z"
}
```

## List Comments

```bash theme={null}
curl https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/comments \
  -H "Cookie: session=..."
```

Returns all comments for the key, ordered by creation time.

## Update a Comment

Update the text of an existing comment. Only the comment author can update their own comments:

```bash theme={null}
curl -X PATCH https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/comments/cmt_abc123 \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '"Updated comment text here"'
```

The request body is a plain JSON string (the new comment text).

## Delete a Comment

```bash theme={null}
curl -X DELETE https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/comments/cmt_abc123 \
  -H "Cookie: session=..."
```

## Resolve / Unresolve a Comment

Toggle the resolved state of a comment. Resolved comments are collapsed in the editor UI but remain in the history:

```bash theme={null}
curl -X PATCH https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/comments/cmt_abc123/resolve \
  -H "Cookie: session=..."
```

Each call toggles the resolved state. If the comment is currently unresolved, this resolves it. If it is already resolved, this unresolves it.

## Language-scoped Comments

Comments can be scoped to a specific language by setting the `language` field. This is useful when an issue applies only to a particular translation (e.g. a French translation uses the wrong gender agreement), rather than to the key as a whole.

Language-scoped and key-level comments are displayed together in the editor, but can be filtered by language.