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

# Add Comment

> Post a comment on a task with optional mentions, threading, and file attachments

## Endpoint

```
POST /tasks/{task_id}/comment
```

## Authentication

This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:

```bash theme={null}
X-API-Key: ca_your_api_key_here
```

## Path Parameters

| Parameter | Type    | Required | Description                    |
| --------- | ------- | -------- | ------------------------------ |
| `task_id` | integer | Yes      | Unique identifier for the task |

## Request Body

The request body must be a JSON object with the following fields:

### Required Fields

| Field     | Type   | Description          |
| --------- | ------ | -------------------- |
| `comment` | string | Comment text content |

### Optional Fields

| Field              | Type            | Description                                                        |
| ------------------ | --------------- | ------------------------------------------------------------------ |
| `user_email`       | string          | Email of the user posting the comment (defaults to API key owner)  |
| `mention_user_ids` | array\[integer] | List of user IDs to mention in the comment                         |
| `reply_to`         | integer         | Activity log ID of an existing comment to reply to (for threading) |
| `attachments`      | array\[object]  | Files to attach to the comment (uploaded automatically)            |

### Attachment Object

Each item in the `attachments` array must contain:

| Field            | Type   | Description                                         |
| ---------------- | ------ | --------------------------------------------------- |
| `filename`       | string | Filename including extension (e.g., `"report.pdf"`) |
| `base64_content` | string | Base64-encoded file content                         |

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.chamelio.ai/tasks/12345/comment" \
    -H "X-API-Key: ca_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "comment": "The contract has been reviewed and looks good.",
      "user_email": "reviewer@example.com",
      "mention_user_ids": [42, 57],
      "attachments": [
        {
          "filename": "review-notes.pdf",
          "base64_content": "JVBERi0xLjQKMSAwIG9iago..."
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  task_id = 12345

  url = f"https://platform.chamelio.ai/tasks/{task_id}/comment"
  headers = {
      "X-API-Key": "ca_your_api_key_here",
      "Content-Type": "application/json"
  }

  payload = {
      "comment": "The contract has been reviewed and looks good.",
      "user_email": "reviewer@example.com",
      "mention_user_ids": [42, 57],
      "attachments": [
          {
              "filename": "review-notes.pdf",
              "base64_content": "JVBERi0xLjQKMSAwIG9iago..."
          }
      ]
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const taskId = 12345;

  const response = await fetch(
    `https://platform.chamelio.ai/tasks/${taskId}/comment`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'ca_your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        comment: 'The contract has been reviewed and looks good.',
        user_email: 'reviewer@example.com',
        mention_user_ids: [42, 57],
        attachments: [
          {
            filename: 'review-notes.pdf',
            base64_content: 'JVBERi0xLjQKMSAwIG9iago...'
          }
        ]
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "success": true,
  "activity_log_id": 98765,
  "message": "Comment created successfully"
}
```

### Response Fields

| Field             | Type    | Description                                                                        |
| ----------------- | ------- | ---------------------------------------------------------------------------------- |
| `success`         | boolean | Whether the comment was created successfully                                       |
| `activity_log_id` | integer | ID of the created activity log entry (use this as `reply_to` for threaded replies) |
| `message`         | string  | Success confirmation message                                                       |

## Error Responses

### 401 Unauthorized

Returned when authentication fails. See the [authentication errors](/api-reference/introduction#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 404 Not Found

Returned when the task doesn't exist or you don't have access to it.

```json theme={null}
{
  "detail": "Task not found"
}
```

### 422 Validation Error

Returned when the request body is invalid or required fields are missing.

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "comment"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

### 500 Internal Server Error

Returned when the comment creation fails due to a server error.

```json theme={null}
{
  "detail": "Failed to create comment"
}
```

## Notes

<Info>
  The `activity_log_id` returned in the response can be used as the `reply_to` value in subsequent requests to create threaded conversations on a task.
</Info>

<Tip>
  When a comment is posted, a [`flows.tasks.commented`](/api-reference/webhooks/flows/task-commented) webhook event is triggered, allowing external systems to react to new comments in real time.
</Tip>

<Warning>
  Attachments are sent as base64-encoded content in the request body. For large files, consider the impact on request size and timeout limits.
</Warning>

## Use Cases

This endpoint is useful for:

* **Automated status updates** - Post comments from external systems when events occur (e.g., approval from a third-party tool)
* **Threaded conversations** - Build reply chains using the `reply_to` field with `activity_log_id` values
* **File sharing** - Attach documents or reports to task comments programmatically
* **Cross-system notifications** - Mention specific users to alert them about updates from integrated systems