Skip to main content

Endpoint

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:
Required scope: tasks:write
The comment is posted as the access token’s user, and any attachments are uploaded as them too.

Path Parameters

Request Body

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

Required Fields

Optional Fields

Attachment Object

Each item in the attachments array must contain:

Request Example

Response

Success Response

Status Code: 200 OK

Response Fields

Error Responses

400 Bad Request

Returned when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

403 Forbidden

Returned when the token lacks the required scope:
Or when the user may not comment on this task:

404 Not Found

Returned when the task does not exist.

422 Validation Error

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

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

500 Internal Server Error

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

Notes

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.
When a comment is posted, a flows.tasks.commented webhook event is triggered, allowing external systems to react to new comments in real time.
Attachments are sent as base64-encoded content in the request body. For large files, consider the impact on request size and timeout limits.

Use Cases

This endpoint is useful for:
  • Two-way chat integrations - Relay a user’s message from Slack or Teams, posted as that user
  • 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
  • Correct authorship - Ensure comments show the real person, not a shared integration account