Comment on a task

Adds a comment to a task's thread: a question, progress, or why something is blocked. Anyone who may work on the entity's tasks can comment, also on finished tasks and while someone else holds the task. Comments can't be edited or deleted. Never put credentials (portal passwords, PINs, certificates) in a comment.

At a glance#

• REST: POST /api/v1/tasks/{id}/comments
• MCP tool: tasks_comments_create
• Operation ID: tasks.comments.create
• Scope: Organization, or one of its legal entities or brands
• Permission: tasks:write
• Risk tier: write
• Dry run: Supported (send Ownrecord-Dry-Run: true)
• Idempotency: Idempotency-Key required
• Modes: Test and live
• Authentication: API key with the tasks:write scope
• Since: M10

Request#

Path parameters#

Body#

A JSON object (Content-Type: application/json):

Response#

201 Created with a JSON object:

Examples#

Report progress#

POST /api/v1/tasks/task_01m4ttwd3veh9apbewxheq5xa9/comments
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "body": "The portal asks for a second confirmation code; waiting for the finance team."
}

Response (201):

{
  "id": "tcm_01m4ttwd3veh9apbewxheq5xa4",
  "object": "task_comment",
  "taskId": "task_01m4ttwd3veh9apbewxheq5xa9",
  "author": {
    "type": "agent",
    "id": "agt_01m4ttwd3veh9apbewxheq5xa6"
  },
  "body": "The portal asks for a second confirmation code; waiting for the finance team.",
  "createdAt": "2026-10-15T09:20:00.000Z"
}

Errors#

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.