Tasks and imports
Create, read, update, or archive a Better Task, and add an existing Attio task.
List tasks
GET /v1/task-management
Lists tasks in your connected Attio workspace, one page at a time. Filters combine; status_id can be sent more than once and matches any of them. A page can return fewer tasks 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_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 | |
assignee_id |
query | No | string (uuid) | |
status_id |
query | No | array of string | Repeat this query parameter for multiple values. |
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) | |
completed |
query | No | boolean | Use true or false in the query string. |
due_from |
query | No | string (date-time) | |
due_before |
query | No | string (date-time) | |
has_due_date |
query | No | boolean | Use true or false in the query string. |
repeats |
query | No | boolean | Use true or false in the query string. |
needs_attention |
query | No | boolean | Use true or false in the query string. |
updated_since |
query | No | string (date-time) | |
include_archived |
query | No | boolean | Use true or false in the query string. |
sort |
query | No | "created_at", "-created_at", "updated_at", "-updated_at" |
Response
| HTTP status | Result |
|---|---|
200 |
A page of tasks. |
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" |
Yes | |
data[].id |
string (uuid) | Yes | |
data[].version |
string | Yes | |
data[].title |
string | Yes | |
data[].type_id |
string (uuid) | Yes | |
data[].status_id |
string | Yes | |
data[].completed |
boolean | Yes | |
data[].assignee_ids |
array of string (uuid) | Yes | |
data[].due_at |
string (date-time) or null | Yes | |
data[].linked_records |
array of object | Yes | |
data[].linked_records[].object_id |
string (uuid) | Yes | |
data[].linked_records[].record_id |
string (uuid) | Yes | |
data[].parent_task_id |
string (uuid) or null | Yes | |
data[].archived |
boolean | Yes | |
data[].sync_state |
"pending", "synced", "conflict", "attention", "archived" |
Yes | |
data[].sync_issue |
"create_unconfirmed", "provider", "conflict", "missing", "configuration", "type_deleted" or null |
Yes | |
data[].native_task_id |
string (uuid) or null | Yes | |
data[].created_at |
string (date-time) | Yes | |
data[].updated_at |
string (date-time) | Yes | |
pagination |
object | Yes | |
pagination.next_cursor |
string or null | Yes | |
references |
array of object | Yes | |
references[].provider |
"attio" |
Yes | |
references[].workspace_id |
string or null | Yes | |
references[].object_id |
string or null | Yes | |
references[].object_slug |
string or null | Yes | |
references[].records |
array of object | Yes | |
references[].records[].record_id |
string | Yes | |
references[].records[].web_url |
string (uri) or null | Yes | |
references[].records[].attributes |
array of object | Yes | |
references[].records[].attributes[].attribute_id |
string or null | Yes | |
references[].records[].attributes[].attribute_slug |
string or null | Yes | |
references[].records[].via |
array of object | Yes | |
references[].records[].via[].source_object_id |
string or null | Yes | |
references[].records[].via[].source_object_slug |
string or null | Yes | |
references[].records[].via[].source_record_id |
string | Yes | |
references[].records[].via[].attribute_id |
string or null | Yes | |
references[].records[].via[].attribute_slug |
string or null | Yes | |
references[].records[].via[].target_object_id |
string or null | Yes | |
references[].records[].via[].target_object_slug |
string or null | Yes | |
references[].records[].via[].target_record_id |
string | Yes | |
references[].lookup_hint |
object | Yes | |
references[].lookup_hint.resource |
"records" |
Yes | |
references[].lookup_hint.object |
string | Yes | |
references[].lookup_hint.record_ids |
array of string | 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.
Create a task
POST /v1/task-management
Creates a task in your connected Attio workspace. The task is saved first and then sent to Attio; poll the returned operation to follow it. Works only for an API key given Better tasks access in Settings, Integrations & MCP.
Requires tasks:create. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: create_task. 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 |
|---|---|---|---|---|
title |
JSON body | Yes | string | |
linked_records |
JSON body | No | array of object | |
linked_records[].object_id |
Within the JSON value | Within this object | string (uuid) | |
linked_records[].record_id |
Within the JSON value | Within this object | string (uuid) | |
description |
JSON body | No | string | |
type_id |
JSON body | No | string (uuid) | |
status_id |
JSON body | No | string | |
priority |
JSON body | No | "Low", "Normal", "High", "Urgent" |
|
owner_id |
JSON body | No | string (uuid) or null | |
assignee_ids |
JSON body | No | array of string (uuid) | |
due_at |
JSON body | No | string (date-time) or null | |
due_type |
JSON body | No | "Target", "Deadline" |
|
parent_task_id |
JSON body | No | string (uuid) or null | |
attributes |
JSON body | No | object | |
attributes.{key} |
Within the JSON value | No | string or array of string | Value for each key in this object. |
checklist |
JSON body | No | array of object | |
checklist[].id |
Within the JSON value | Within this object | string (uuid) | |
checklist[].title |
Within the JSON value | Within this object | string | |
checklist[].done |
Within the JSON value | Within this object | boolean | |
file_links |
JSON body | No | array of object | |
file_links[].id |
Within the JSON value | Within this object | string (uuid) | |
file_links[].name |
Within the JSON value | Within this object | string | |
file_links[].url |
Within the JSON value | Within this object | string (uri) | |
recurrence |
JSON body | No | object or null | |
recurrence.every |
Within the JSON value | Within this object | integer | Alternative 1. |
recurrence.unit |
Within the JSON value | Within this object | "days", "weeks", "months", "years" |
Alternative 1. |
recurrence.basis |
Within the JSON value | Within this object | "schedule", "completion" |
Alternative 1. |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
202 |
The task is saved and on its way to Attio. |
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. |
Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See operation status.
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, setup_required. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: invalid_selection, budget_exceeded. |
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 an existing Attio task
POST /v1/task-management/imports
Adds a task that already exists in your connected Attio workspace to Better tasks, by its Attio task id. Its values are read from Attio; blanks take the task type's defaults, which are then sent to Attio. Poll the returned operation to follow it; resource_id is the task's id in Better tasks. A task that is already in Better tasks is not added twice. Works only for an API key given Better tasks access in Settings, Integrations & MCP.
Requires tasks:create. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: create_task_from_attio. 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 |
|---|---|---|---|---|
native_task_id |
JSON body | Yes | string (uuid) | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
202 |
The task is in Better tasks, and its defaults are on their way to Attio. |
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. |
Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See operation status.
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, setup_required. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: invalid_selection. |
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 Attio tasks to import
GET /v1/task-management/attio-tasks
Lists the tasks in your connected Attio workspace and whether each is already in Better tasks: imported is true and task_id is its task there. Send imported false to find the ones that aren't yet, then add them with Import Attio tasks. q matches words in a task's title. Filters combine; assignee_id can be sent more than once and matches any of them, and assignee_id me means the person who connected this AI app, when they are a member of the Attio workspace. A filter never matches a task that has no value for it; send has_due_date false or has_assignees false to find those. The newest tasks come first unless sort says otherwise. complete is false when only your newest Attio tasks are listed. 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_importable_attio_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 | |
q |
query | No | string | |
imported |
query | No | boolean | Use true or false in the query string. |
completed |
query | No | boolean | Use true or false in the query string. |
assignee_id |
query | No | array of string (uuid) or "me" |
Repeat this query parameter for multiple values. |
has_assignees |
query | No | boolean | Use true or false in the query string. |
object_id |
query | No | string (uuid) | |
record_id |
query | No | string (uuid) | |
due_from |
query | No | string (date-time) | |
due_before |
query | No | string (date-time) | |
has_due_date |
query | No | boolean | Use true or false in the query string. |
created_from |
query | No | string (date-time) | |
created_before |
query | No | string (date-time) | |
sort |
query | No | "created_at", "-created_at", "due_at", "-due_at", "title", "-title", "completed", "-completed", "imported", "-imported" |
Response
| HTTP status | Result |
|---|---|
200 |
A page of Attio tasks. |
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 |
"attio_task" |
Yes | |
data[].id |
string (uuid) | Yes | |
data[].title |
string | Yes | |
data[].completed |
boolean | Yes | |
data[].due_at |
string (date-time) or null | Yes | |
data[].created_at |
string (date-time) | Yes | |
data[].assignee_ids |
array of string | Yes | |
data[].linked_records |
array of object | Yes | |
data[].linked_records[].object_id |
string (uuid) | Yes | |
data[].linked_records[].record_id |
string (uuid) | Yes | |
data[].imported |
boolean | Yes | |
data[].task_id |
string (uuid) or null | Yes | |
complete |
boolean | Yes | |
pagination |
object | Yes | |
pagination.next_cursor |
string or null | Yes | |
references |
array of object | Yes | |
references[].provider |
"attio" |
Yes | |
references[].workspace_id |
string or null | Yes | |
references[].object_id |
string or null | Yes | |
references[].object_slug |
string or null | Yes | |
references[].records |
array of object | Yes | |
references[].records[].record_id |
string | Yes | |
references[].records[].web_url |
string (uri) or null | Yes | |
references[].records[].attributes |
array of object | Yes | |
references[].records[].attributes[].attribute_id |
string or null | Yes | |
references[].records[].attributes[].attribute_slug |
string or null | Yes | |
references[].records[].via |
array of object | Yes | |
references[].records[].via[].source_object_id |
string or null | Yes | |
references[].records[].via[].source_object_slug |
string or null | Yes | |
references[].records[].via[].source_record_id |
string | Yes | |
references[].records[].via[].attribute_id |
string or null | Yes | |
references[].records[].via[].attribute_slug |
string or null | Yes | |
references[].records[].via[].target_object_id |
string or null | Yes | |
references[].records[].via[].target_object_slug |
string or null | Yes | |
references[].records[].via[].target_record_id |
string | Yes | |
references[].lookup_hint |
object | Yes | |
references[].lookup_hint.resource |
"records" |
Yes | |
references[].lookup_hint.object |
string | Yes | |
references[].lookup_hint.record_ids |
array of string | 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, plan_required, not_available, resource_forbidden. |
404 |
One of: not_found. |
409 |
One of: setup_required. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: invalid_selection. |
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.
Import Attio tasks
POST /v1/task-management/attio-tasks/imports
Adds tasks that already exist in your connected Attio workspace to Better tasks, by their Attio task ids from List Attio tasks to import. Each task's values are read from Attio; blanks take the task type's defaults, which are then sent to Attio. Each id gets one entry in results, in the order sent, and each is its own: one already in Better tasks is not added again and names its task_id, one Attio doesn't have says not_found, and the others are still imported. Works only for an API key given Better tasks access in Settings, Integrations & MCP.
Requires tasks:create. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: create_tasks_from_attio. 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 |
|---|---|---|---|---|
native_task_ids |
JSON body | Yes | array of string (uuid) | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
200 |
Each Attio task's result. |
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 |
object | Yes | |
data.object |
"attio_task_import_batch" |
Yes | |
data.results |
array of object | Yes | |
data.results[].task_id |
string (uuid) or null | Yes | |
data.results[].already_imported |
boolean | Yes | |
data.results[].error |
"not_found", "invalid_values", "unavailable" or null |
Yes |
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, setup_required. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: invalid_selection. |
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.
Get a task
GET /v1/task-management/{task_id}
Gets one task, including an archived one, which has archived true. Linked records come back as their object ID and record ID; read a record's values in Attio.
Requires tasks:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: get_task. 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 |
Response
| HTTP status | Result |
|---|---|
200 |
The task. |
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 |
object | Yes | |
data.object |
"task" |
Yes | |
data.id |
string (uuid) | Yes | |
data.version |
string | Yes | |
data.title |
string | Yes | |
data.type_id |
string (uuid) | Yes | |
data.status_id |
string | Yes | |
data.completed |
boolean | Yes | |
data.assignee_ids |
array of string (uuid) | Yes | |
data.due_at |
string (date-time) or null | Yes | |
data.linked_records |
array of object | Yes | |
data.linked_records[].object_id |
string (uuid) | Yes | |
data.linked_records[].record_id |
string (uuid) | Yes | |
data.parent_task_id |
string (uuid) or null | Yes | |
data.archived |
boolean | Yes | |
data.sync_state |
"pending", "synced", "conflict", "attention", "archived" |
Yes | |
data.sync_issue |
"create_unconfirmed", "provider", "conflict", "missing", "configuration", "type_deleted" or null |
Yes | |
data.native_task_id |
string (uuid) or null | Yes | |
data.created_at |
string (date-time) | Yes | |
data.updated_at |
string (date-time) | Yes | |
data.description |
string | Yes | |
data.priority |
"Low", "Normal", "High", "Urgent" |
Yes | |
data.owner_id |
string (uuid) or null | Yes | |
data.due_type |
"Target", "Deadline" |
Yes | |
data.attributes |
object | Yes | |
data.attributes.{key} |
string or array of string | No | Value for each key in this object. |
data.checklist |
array of object | Yes | |
data.checklist[].id |
string (uuid) | Yes | |
data.checklist[].title |
string | Yes | |
data.checklist[].done |
boolean | Yes | |
data.file_links |
array of object | Yes | |
data.file_links[].id |
string (uuid) | Yes | |
data.file_links[].name |
string | Yes | |
data.file_links[].url |
string | Yes | |
data.recurrence |
object or null | Yes | |
data.recurrence.every |
integer | Yes | Alternative 1. |
data.recurrence.unit |
"days", "weeks", "months", "years" |
Yes | Alternative 1. |
data.recurrence.basis |
"schedule", "completion" |
Yes | Alternative 1. |
data.subtask_ids |
array of string (uuid) | Yes | |
data.comment_count |
integer | Yes | |
references |
array of object | Yes | |
references[].provider |
"attio" |
Yes | |
references[].workspace_id |
string or null | Yes | |
references[].object_id |
string or null | Yes | |
references[].object_slug |
string or null | Yes | |
references[].records |
array of object | Yes | |
references[].records[].record_id |
string | Yes | |
references[].records[].web_url |
string (uri) or null | Yes | |
references[].records[].attributes |
array of object | Yes | |
references[].records[].attributes[].attribute_id |
string or null | Yes | |
references[].records[].attributes[].attribute_slug |
string or null | Yes | |
references[].records[].via |
array of object | Yes | |
references[].records[].via[].source_object_id |
string or null | Yes | |
references[].records[].via[].source_object_slug |
string or null | Yes | |
references[].records[].via[].source_record_id |
string | Yes | |
references[].records[].via[].attribute_id |
string or null | Yes | |
references[].records[].via[].attribute_slug |
string or null | Yes | |
references[].records[].via[].target_object_id |
string or null | Yes | |
references[].records[].via[].target_object_slug |
string or null | Yes | |
references[].records[].via[].target_record_id |
string | Yes | |
references[].lookup_hint |
object | Yes | |
references[].lookup_hint.resource |
"records" |
Yes | |
references[].lookup_hint.object |
string | Yes | |
references[].lookup_hint.record_ids |
array of string | Yes |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, unknown_parameter. |
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.
Edit a task
PATCH /v1/task-management/{task_id}
Changes a task. Send the task's version as expected_version. Properties you leave out stay as they are, a list you send replaces the saved one, and null clears a property. attributes, when sent, replaces all of the task's attribute values, so an attribute you leave out of it is cleared. A task's title can't change here once the task is in Attio: Attio doesn't let other apps change a task's text, so rename it in Attio. The change is sent to Attio after, so poll the returned operation to follow it. Syncing with Attio changes the task's version again, so get the task for its current version before your next change. What this replaces is not kept, so it can't be undone.
Requires tasks:update. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: update_task. 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 | |
expected_version |
JSON body | Yes | string | |
title |
JSON body | No | string | |
linked_records |
JSON body | No | array of object | |
linked_records[].object_id |
Within the JSON value | Within this object | string (uuid) | |
linked_records[].record_id |
Within the JSON value | Within this object | string (uuid) | |
description |
JSON body | No | string | |
type_id |
JSON body | No | string (uuid) | |
status_id |
JSON body | No | string | |
priority |
JSON body | No | "Low", "Normal", "High", "Urgent" |
|
owner_id |
JSON body | No | string (uuid) or null | |
assignee_ids |
JSON body | No | array of string (uuid) | |
due_at |
JSON body | No | string (date-time) or null | |
due_type |
JSON body | No | "Target", "Deadline" |
|
parent_task_id |
JSON body | No | string (uuid) or null | |
attributes |
JSON body | No | object | |
attributes.{key} |
Within the JSON value | No | string or array of string | Value for each key in this object. |
checklist |
JSON body | No | array of object | |
checklist[].id |
Within the JSON value | Within this object | string (uuid) | |
checklist[].title |
Within the JSON value | Within this object | string | |
checklist[].done |
Within the JSON value | Within this object | boolean | |
file_links |
JSON body | No | array of object | |
file_links[].id |
Within the JSON value | Within this object | string (uuid) | |
file_links[].name |
Within the JSON value | Within this object | string | |
file_links[].url |
Within the JSON value | Within this object | string (uri) | |
recurrence |
JSON body | No | object or null | |
recurrence.every |
Within the JSON value | Within this object | integer | Alternative 1. |
recurrence.unit |
Within the JSON value | Within this object | "days", "weeks", "months", "years" |
Alternative 1. |
recurrence.basis |
Within the JSON value | Within this object | "schedule", "completion" |
Alternative 1. |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
202 |
The change is saved and on its way to Attio. |
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. |
Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See operation status.
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, setup_required, version_conflict. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: invalid_selection. |
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.
Archive a task
POST /v1/task-management/{task_id}/archive
Archives a task and deletes it and its activity in Attio. Send the task's current version as expected_version: syncing with Attio changes it after each change, so get the task first rather than reusing a version from an earlier operation. This can't be undone.
Requires tasks:archive. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: archive_task. 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 | |
expected_version |
JSON body | Yes | string | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
200 |
The task is archived. |
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, resource_forbidden. |
404 |
One of: not_found. |
409 |
One of: idempotency_conflict, version_conflict. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: invalid_selection. |
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.