Task comments
Read and add comments on a task, or find comments across tasks.
List comments across tasks
GET /v1/task-management/comments
Lists comments on tasks in your connected Attio workspace, newest first, one page at a time. The task filters work as they do when listing tasks and decide which tasks' comments count; author_id, created_from and created_before narrow the comments, and q matches a comment's text or its task's title. With group_by task, each task appears once with its newest comment, the most recently commented task first. A page can return fewer comments than limit, or none, before the end: keep reading until next_cursor is null. Works only for an API key given Better tasks access in Settings, Integrations & MCP.
Requires tasks:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: list_comments_across_tasks. Its arguments use the names below, except fields marked REST only. An HTTP header is passed using its argument name in MCP.
Parameters
| Name | Send in | Required | Type or allowed values | Notes |
|---|---|---|---|---|
limit |
query | No | integer | |
cursor |
query | No | string | |
group_by |
query | No | "comment", "task" |
|
q |
query | No | string | |
author_id |
query | No | string (uuid) | |
created_from |
query | No | string (date-time) | |
created_before |
query | No | string (date-time) | |
assignee_id |
query | No | string (uuid) | |
status_id |
query | No | array of string | Repeat this query parameter for multiple values. |
completed |
query | No | boolean | Use true or false in the query string. |
object_id |
query | No | string (uuid) | |
record_id |
query | No | string (uuid) | |
type_id |
query | No | string (uuid) | |
parent_task_id |
query | No | string (uuid) |
Response
| HTTP status | Result |
|---|---|
200 |
A page of comments. |
Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.
| Response field | Type | Required in object | Notes |
|---|---|---|---|
data |
array of object | Yes | |
data[].object |
"task_comment" |
Yes | |
data[].id |
string (uuid) | Yes | |
data[].task_id |
string (uuid) | Yes | |
data[].author_kind |
"workspace_member", "integration" |
Yes | |
data[].author_id |
string (uuid) | Yes | |
data[].author_name |
string | Yes | |
data[].body |
string | Yes | |
data[].created_at |
string (date-time) | Yes | |
pagination |
object | Yes | |
pagination.next_cursor |
string or null | Yes |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, invalid_request, unknown_parameter, invalid_cursor. |
401 |
One of: missing_credential, invalid_credential, credential_expired, credential_revoked. |
402 |
One of: payment_overdue. |
403 |
One of: scope_required, resource_forbidden. |
404 |
One of: not_found. |
409 |
One of: idempotency_conflict, recovery_not_available, setup_required, version_conflict. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: attribute_type_locked, budget_exceeded, configuration_in_use, invalid_selection, status_name_reserved. |
423 |
One of: organization_reopening. |
428 |
One of: customer_agreement_required. |
429 |
One of: rate_limited. |
503 |
One of: service_unavailable. |
See errors and recovery and safe retries before repeating a write.
List a task's comments
GET /v1/task-management/{task_id}/comments
Lists a task's comments, oldest first. A comment this API key added has author_kind integration and the key's name; an Attio workspace member's comment has the member's ID and name.
Requires tasks:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: list_task_comments. Its arguments use the names below, except fields marked REST only. An HTTP header is passed using its argument name in MCP.
Parameters
| Name | Send in | Required | Type or allowed values | Notes |
|---|---|---|---|---|
task_id |
path | Yes | string | |
limit |
query | No | integer | |
cursor |
query | No | string |
Response
| HTTP status | Result |
|---|---|
200 |
A page of comments. |
Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.
| Response field | Type | Required in object | Notes |
|---|---|---|---|
data |
array of object | Yes | |
data[].object |
"task_comment" |
Yes | |
data[].id |
string (uuid) | Yes | |
data[].task_id |
string (uuid) | Yes | |
data[].author_kind |
"workspace_member", "integration" |
Yes | |
data[].author_id |
string (uuid) | Yes | |
data[].author_name |
string | Yes | |
data[].body |
string | Yes | |
data[].created_at |
string (date-time) | Yes | |
pagination |
object | Yes | |
pagination.next_cursor |
string or null | Yes |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, invalid_request, unknown_parameter, invalid_cursor. |
401 |
One of: missing_credential, invalid_credential, credential_expired, credential_revoked. |
402 |
One of: payment_overdue. |
403 |
One of: scope_required, resource_forbidden. |
404 |
One of: not_found. |
409 |
One of: idempotency_conflict, recovery_not_available, setup_required, version_conflict. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: attribute_type_locked, budget_exceeded, configuration_in_use, invalid_selection, status_name_reserved. |
423 |
One of: organization_reopening. |
428 |
One of: customer_agreement_required. |
429 |
One of: rate_limited. |
503 |
One of: service_unavailable. |
See errors and recovery and safe retries before repeating a write.
Add a comment
POST /v1/task-management/{task_id}/comments
Adds a comment to a task. The comment shows this API key's name as its author.
Requires tasks:comments:write. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: create_task_comment. Its arguments use the names below, except fields marked REST only. An HTTP header is passed using its argument name in MCP.
Parameters
| Name | Send in | Required | Type or allowed values | Notes |
|---|---|---|---|---|
task_id |
path | Yes | string | |
body |
JSON body | Yes | string | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
201 |
The comment is added. |
Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.
| Response field | Type | Required in object | Notes |
|---|---|---|---|
data |
OperationReceipt | Yes | |
data.id |
string | Yes | |
data.object |
"operation" |
Yes | |
data.version |
string | Yes | |
data.resource_id |
string | Yes | |
data.resource_type |
string | Yes | |
data.status |
"pending", "succeeded", "failed", "canceled", "needs_attention" |
Yes | |
data.terminal |
boolean | Yes | |
data.created_at |
string (date-time) | Yes | |
data.ended_at |
string (date-time) or null | Yes | |
data.reason_code |
string or null | Yes | |
data.replayed |
true |
No | |
data.operation_type |
"scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "task_create", "task_update", "task_archive", "task_comment_create", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer", "task_import" |
Yes | When data.operation_type is "scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "task_create", "task_update", "task_archive", "task_comment_create", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer", "task_import". |
data.action_metadata |
object | Yes | |
data.action_metadata.resource_version |
string | Yes | |
data.action_metadata.allowed_actions |
array of string | Yes | |
data.operation_type |
"merge_execute", "merge_cancel" |
Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.execute_not_before |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.authorization_expires_at |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.operation_type |
"plan_prepare", "plan_revision_prepare", "retry_plan_prepare" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.plan_revision |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.effects_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.preview_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.recovery_coverage_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement |
object | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.scope |
"organization_baseline" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.mode |
"api_key_allowed", "not_allowed" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.policy_version |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.grant_evaluation |
"at_execution" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.reason_code |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_state |
"unauthorized", "authorized", "rejected", "invalidated", "expired" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.operation_type |
"review_bulk_update", "exclusion_bulk_create" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results |
array of object | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].index |
integer | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].outcome |
"succeeded", "failed" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.id |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.version |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.code |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.message |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.param |
string | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.operation_type |
"scan", "scan_continue" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child |
object | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.state |
"not_requested", "pending_admission", "admitted", "skipped", "failed" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.reason_code |
string or null | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_run_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_operation_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.operation_url |
string (uri) | No | When data.operation_type is "scan", "scan_continue". |
data.operation_type |
"brevo_list_add" |
Yes | When data.operation_type is "brevo_list_add". |
data.action_metadata.list_id |
integer | Yes | When data.operation_type is "brevo_list_add". |
data.action_metadata.records |
array of object | Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". When data.operation_type is value. When data.operation_type is value. When data.operation_type is value. |
data.action_metadata.records[].record_id |
string | Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". When data.operation_type is value. When data.operation_type is value. When data.operation_type is value. |
data.action_metadata.records[].outcome |
"pending", "added", "skipped", "unconfirmed", "failed" |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is value. |
data.action_metadata.records[].reason |
"restricted", "identity_hold", "monitoring_not_current", "no_email", "no_contact", "excluded", "changed", "confirming", "record_not_found" or null |
Yes | When data.operation_type is "brevo_list_add". |
data.action_metadata.records[].addresses |
array of object | Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". |
data.action_metadata.records[].addresses[].source |
"profile" or object |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". |
data.action_metadata.records[].addresses[].source.attribute |
"email_addresses" |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". Alternative 2. |
data.action_metadata.records[].addresses[].source.position |
integer | Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". Alternative 2. |
data.action_metadata.records[].addresses[].outcome |
"used", "skipped" |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". |
data.action_metadata.records[].addresses[].reason |
"restricted" or null |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". |
data.operation_type |
"brevo_email_send" |
Yes | When data.operation_type is "brevo_email_send". |
data.action_metadata.template_id |
integer | Yes | When data.operation_type is "brevo_email_send". |
data.action_metadata.records[].outcome |
"pending", "sent", "skipped", "unconfirmed", "failed" |
Yes | When data.operation_type is "brevo_email_send". When data.operation_type is value. |
data.action_metadata.records[].reason |
"restricted", "identity_hold", "monitoring_not_current", "no_email", "excluded", "recently_sent", "changed", "confirming", "record_not_found" or null |
Yes | When data.operation_type is "brevo_email_send". |
data.operation_type |
value | Yes | When data.operation_type is value. When data.operation_type is value. When data.operation_type is value. When data.operation_type is value. |
data.action_metadata.list_id |
string | Yes | When data.operation_type is value. When data.operation_type is value. |
data.action_metadata.records[].reason |
"restricted", "identity_hold", "monitoring_not_current", "no_contact", "excluded", "changed", "record_not_found" or null |
Yes | When data.operation_type is value. |
data.action_metadata.records[].outcome |
"pending", "removed", "skipped", "unconfirmed", "failed" |
Yes | When data.operation_type is value. |
data.action_metadata.records[].reason |
"not_in_list", "identity_hold", "no_contact", "changed", "record_not_found" or null |
Yes | When data.operation_type is value. |
data.action_metadata.outcome |
"pending", "unsubscribed", "unconfirmed", "failed", "skipped" |
Yes | When data.operation_type is value. |
data.action_metadata.reason |
"no_contact", "changed" or null |
Yes | When data.operation_type is value. |
data.action_metadata.metric |
string | Yes | When data.operation_type is value. |
data.action_metadata.properties |
object | Yes | When data.operation_type is value. |
data.action_metadata.properties.{key} |
string or number or boolean or null | No | When data.operation_type is value. Value for each key in this object. |
data.action_metadata.records[].reason |
"restricted", "identity_hold", "monitoring_not_current", "no_contact", "excluded", "recently_sent", "changed", "record_not_found" or null |
Yes | When data.operation_type is value. |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, invalid_request, unknown_parameter. |
401 |
One of: missing_credential, invalid_credential, credential_expired, credential_revoked. |
402 |
One of: payment_overdue. |
403 |
One of: scope_required, plan_required, not_available, resource_forbidden. |
404 |
One of: not_found. |
409 |
One of: idempotency_conflict. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: attribute_type_locked, budget_exceeded, configuration_in_use, invalid_selection, status_name_reserved. |
423 |
One of: organization_reopening. |
428 |
One of: customer_agreement_required. |
429 |
One of: rate_limited. |
503 |
One of: service_unavailable. |
See errors and recovery and safe retries before repeating a write.
The public OpenAPI document lists generally available API families. Alpha operations may not appear in that document; their request and response fields are listed on this page. Use the API Playground to inspect a real response with your connection's access.