Bot API: comments

Bot comment endpoints use the bot token and operate only on tasks in forms the bot can access.

Authentication

Send the bot token with every request:

Authorization: Bearer <BOT_TOKEN>

List task comments

GET /bot/tasks/{task_id}/comments?limit=50&cursor=<next_cursor>

Comments are returned newest first. The endpoint uses cursor pagination and does not load the task's entire comment history.

Query parameters

Parameter	Required	Description
limit	No	Number of comments to return. Default and maximum: 50.
cursor	No	Opaque cursor from the previous response's pagination.next_cursor. Maximum length: 512 characters.

Example response:

{
  "success": true,
  "error_message": null,
  "data": {
    "comments": [
      {
        "id": 501,
        "date": "2026-08-12T10:30:00+00:00",
        "task_id": 123,
        "author_id": 17,
        "value": "Please review this task",
        "parent_comment_id": null,
        "files": [],
        "is_system": false,
        "system_data": []
      }
    ],
    "pagination": {
      "limit": 50,
      "returned_count": 1,
      "has_more": false,
      "next_cursor": null
    }
  }
}

When has_more is true, pass next_cursor unchanged in the next request.

Create a task comment

POST /bot/tasks/{task_id}/comments
Content-Type: application/json

Request body:

{
  "value": "Please review this task",
  "parent_comment_id": null,
  "recipients": [12, 34]
}

Field	Required	Description
value	Yes	Non-blank comment text, maximum 10,000 characters.
parent_comment_id	No	Parent comment ID for a reply. The parent must belong to the same task.
recipients	No	User IDs to notify. Maximum 50 unique users; each user must have access to the form.

The request body may not exceed 16 KiB.

The task's responsible user and all users listed in recipients receive inbox notifications. Notification jobs are also placed in the external-channel queue. Duplicate recipients are removed, and the bot does not notify itself.

The comment, notifications, and notification queue jobs are saved in one transaction. If any part fails, none of them are saved.

Rate limits

Reading comments uses a shared per-bot quota across Bot API and MCP, regardless of client IP. Creating comments retains its separate per-bot, client-IP quota:

Operation	Limit
List comments	60 requests per minute
Create comments	20 requests per minute

A limit applies across all tasks, not separately to each task. A rate-limited request returns HTTP 429 with a retry delay in the error message.

Errors

Status	Meaning
400	Invalid cursor or parent comment does not belong to the task.
401	Missing, invalid, or expired bot token.
403	Bot has no form access, or a recipient has no form access.
404	Task was not found.
413	Create-comment payload exceeds 16 KiB.
422	Request validation failed.
429	Rate limit exceeded.