Task configuration and views
Read and update task attributes, types, statuses, templates, and shared saved views.
Get the task configuration
GET /v1/task-management/configuration
Gets the statuses, task types, attributes, saved views and required properties a task can use in your connected Attio workspace. A task's status decides whether it is completed. Saved views come in the order the view menu lists them, after All tasks, and default_view_id is the view everyone's task list opens with unless they chose their own (null: All tasks). A saved view's filters hold its search text and conditions that all must hold. Each condition names an attribute_id (an attribute's ID, "type" for the task type or "created" for when the task was created), an operator and a value; value is null for is_empty and is_not_empty. In a member condition, "me" means whoever views the list; in a date condition, "today" means the day it is viewed.
Requires tasks:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: get_task_configuration. Its arguments use the names below, except fields marked REST only. An HTTP header is passed using its argument name in MCP.
No request parameters are needed.
Response
| HTTP status | Result |
|---|---|
200 |
The configuration. |
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_configuration" |
Yes | |
data.version |
string | Yes | |
data.statuses |
array of object | Yes | |
data.statuses[].id |
string | Yes | |
data.statuses[].name |
string | Yes | |
data.statuses[].color |
"gray", "blue", "light-blue", "orange", "yellow", "green", "purple", "red" |
Yes | |
data.statuses[].completed |
boolean | Yes | |
data.types |
array of object | Yes | |
data.types[].id |
string (uuid) | Yes | |
data.types[].name |
string | Yes | |
data.types[].icon |
"CheckSquare", "Calendar", "Clock", "Folder", "Note", "User", "Users", "Email", "Phone", "Company", "Sales", "BarChart", "Rocket", "Star", "Tag", "Code", "Globe", "Location", "Workflows", "Activity", "Comment", "Grid", "Link", "Check", "HelpCircle" or null |
Yes | |
data.types[].description |
string or null | Yes | |
data.types[].status_ids |
array of string or null | Yes | |
data.types[].attribute_ids |
array of string (uuid) or null | Yes | |
data.types[].default_open_status_id |
string | Yes | |
data.types[].default_done_status_id |
string | Yes | |
data.attributes |
array of object | Yes | |
data.attributes[].id |
string (uuid) | Yes | |
data.attributes[].name |
string | Yes | |
data.attributes[].kind |
"Text", "Number", "Date", "Select", "Task name", "Description", "Status", "Related records", "Owner", "Assignees", "Priority", "Due date", "Parent task" |
Yes | |
data.attributes[].required |
boolean | Yes | |
data.attributes[].enabled |
boolean | Yes | |
data.attributes[].removed |
boolean | Yes | |
data.attributes[].description |
string or null | Yes | |
data.attributes[].options |
array of string | Yes | |
data.attributes[].multiple |
boolean | Yes | |
data.attributes[].default_value |
string or array of string or null | Yes | |
data.attributes[].default_creator |
boolean | Yes | |
data.attributes[].default_date |
object or null | Yes | |
data.attributes[].default_date.amount |
integer | Yes | Alternative 1. |
data.attributes[].default_date.unit |
"days", "weeks", "months", "years" |
Yes | Alternative 1. |
data.attributes[].default_date.direction |
"after", "before" |
Yes | Alternative 1. |
data.attributes[].default_date.anchor |
string | Yes | Alternative 1. |
data.templates |
array of object | Yes | |
data.templates[].id |
string (uuid) | Yes | |
data.templates[].name |
string | Yes | |
data.templates[].version |
integer | Yes | |
data.templates[].type_id |
string (uuid) | Yes | |
data.templates[].title |
string | Yes | |
data.templates[].description |
string | Yes | |
data.templates[].status_id |
string | Yes | |
data.templates[].priority |
"Low", "Normal", "High", "Urgent" |
Yes | |
data.templates[].owner_id |
string (uuid) or null | Yes | |
data.templates[].assignee_ids |
array of string (uuid) | Yes | |
data.templates[].team |
string | Yes | |
data.templates[].attributes |
object | Yes | |
data.templates[].attributes.{key} |
string or array of string | No | Value for each key in this object. |
data.templates[].checklist |
array of object | Yes | |
data.templates[].checklist[].id |
string (uuid) | Yes | |
data.templates[].checklist[].title |
string | Yes | |
data.templates[].due_offset_days |
integer or null | Yes | |
data.templates[].due_offset_unit |
"days", "weeks", "months", "years" |
Yes | |
data.templates[].is_default |
boolean | Yes | |
data.views |
array of object | Yes | |
data.views[].id |
string (uuid) | Yes | |
data.views[].name |
string | Yes | |
data.views[].layout |
"List", "Board" |
Yes | |
data.views[].filters |
object | Yes | |
data.views[].filters.search |
string | Yes | |
data.views[].filters.conditions |
array of object | Yes | |
data.views[].filters.conditions[].attribute_id |
string | Yes | |
data.views[].filters.conditions[].operator |
"contains", "does_not_contain", "is_empty", "is_not_empty", "is_any_of", "is_none_of", "equals", "not_equals", "greater_than", "less_than", "before", "after", "on", "not_on", "last_days", "not_last_days", "links_to", "does_not_link_to" |
Yes | |
data.views[].filters.conditions[].value |
string or number or array of string or object or null | Yes | |
data.views[].filters.conditions[].value.object_id |
string (uuid) | Yes | Alternative 1. Alternative 4. |
data.views[].filters.conditions[].value.record_id |
string (uuid) | Yes | Alternative 1. Alternative 4. |
data.default_view_id |
string (uuid) or null | Yes | |
data.priorities |
array of "Low", "Normal", "High", "Urgent" |
Yes | |
data.required_properties |
array of string | 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.
Replace the task configuration
PUT /v1/task-management/configuration
Replaces the statuses, task types, attributes with their defaults and templates, all at once. Send the configuration as you read it, changed; its version is the one checked, or send it as expected_version. The read's priorities and required properties may be sent back and are ignored; anything a list leaves out is removed. A status, type, attribute or option a task still uses can't be removed, except an option of a Select attribute that allows multiple values: tasks that have it keep it. Send a new template with version 1, and an existing one with its version as read. views, when sent, replaces the saved views in the order sent, which is the order the view menu lists them; each view keeps the columns it shows. default_view_id sets the view everyone's task list opens with (null: All tasks). Leave either out to keep it as it is; a change that would break a saved view you didn't send is refused: update the view first. The attributes that match an Attio task field (Title, Description, Due date, Assignees, Related records, Status and Owner) keep their names; a rename is refused. A status's new name reaches Attio the next time a task is sent there. A template's title and description can insert values when a task is created from it: {{today}}, {{creator}}, {{due_date}}, {{record:OBJECT_ID:ATTRIBUTE_ID}} for an attribute of the task's first linked record of that object, and {{record:OBJECT_ID:RELATIONSHIP_ATTRIBUTE_ID:RELATED_OBJECT_ID:ATTRIBUTE_ID}} for an attribute of the record that relationship points at. A value that is missing reads blank. is_default makes New task start from that template; one template at most. What this replaces is not kept, so it can't be undone.
Requires tasks:config:write. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: update_task_configuration. 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 |
|---|---|---|---|---|
expected_version |
JSON body | No | string | |
object |
JSON body | No | "task_configuration" |
|
version |
JSON body | No | string | |
views |
JSON body | No | array of object | |
views[].id |
Within the JSON value | Within this object | string (uuid) | |
views[].name |
Within the JSON value | Within this object | string | |
views[].layout |
Within the JSON value | Within this object | "List", "Board" |
|
views[].filters |
Within the JSON value | Within this object | object | |
views[].filters.search |
Within the JSON value | Within this object | string | |
views[].filters.conditions |
Within the JSON value | Within this object | array of object | |
views[].filters.conditions[].attribute_id |
Within the JSON value | Within this object | string | |
views[].filters.conditions[].operator |
Within the JSON value | Within this object | "contains", "does_not_contain", "is_empty", "is_not_empty", "is_any_of", "is_none_of", "equals", "not_equals", "greater_than", "less_than", "before", "after", "on", "not_on", "last_days", "not_last_days", "links_to", "does_not_link_to" |
|
views[].filters.conditions[].value |
Within the JSON value | Within this object | string or number or array of string or object or null | |
views[].filters.conditions[].value.object_id |
Within the JSON value | Within this object | string (uuid) | Alternative 1. Alternative 4. |
views[].filters.conditions[].value.record_id |
Within the JSON value | Within this object | string (uuid) | Alternative 1. Alternative 4. |
default_view_id |
JSON body | No | string (uuid) or null | |
priorities |
JSON body | No | array of value | |
required_properties |
JSON body | No | array of value | |
statuses |
JSON body | Yes | array of object | |
statuses[].id |
Within the JSON value | Within this object | string | |
statuses[].name |
Within the JSON value | Within this object | string | |
statuses[].color |
Within the JSON value | Within this object | "gray", "blue", "light-blue", "orange", "yellow", "green", "purple", "red" |
|
statuses[].completed |
Within the JSON value | Within this object | boolean | |
types |
JSON body | Yes | array of object | |
types[].id |
Within the JSON value | Within this object | string (uuid) | |
types[].name |
Within the JSON value | Within this object | string | |
types[].icon |
Within the JSON value | Within this object | "CheckSquare", "Calendar", "Clock", "Folder", "Note", "User", "Users", "Email", "Phone", "Company", "Sales", "BarChart", "Rocket", "Star", "Tag", "Code", "Globe", "Location", "Workflows", "Activity", "Comment", "Grid", "Link", "Check", "HelpCircle" or null |
|
types[].description |
Within the JSON value | Within this object | string or null | |
types[].status_ids |
Within the JSON value | Within this object | array of string or null | |
types[].attribute_ids |
Within the JSON value | Within this object | array of string (uuid) or null | |
types[].default_open_status_id |
Within the JSON value | Within this object | string | |
types[].default_done_status_id |
Within the JSON value | Within this object | string | |
attributes |
JSON body | Yes | array of object | |
attributes[].id |
Within the JSON value | Within this object | string (uuid) | |
attributes[].name |
Within the JSON value | Within this object | string | |
attributes[].kind |
Within the JSON value | Within this object | "Text", "Number", "Date", "Select", "Task name", "Description", "Status", "Related records", "Owner", "Assignees", "Priority", "Due date", "Parent task" |
|
attributes[].required |
Within the JSON value | Within this object | boolean | |
attributes[].enabled |
Within the JSON value | Within this object | boolean | |
attributes[].removed |
Within the JSON value | Within this object | boolean | |
attributes[].description |
Within the JSON value | Within this object | string or null | |
attributes[].options |
Within the JSON value | Within this object | array of string | |
attributes[].multiple |
Within the JSON value | Within this object | boolean | |
attributes[].default_value |
Within the JSON value | Within this object | string or array of string or null | |
attributes[].default_creator |
Within the JSON value | Within this object | boolean | |
attributes[].default_date |
Within the JSON value | Within this object | object or null | |
attributes[].default_date.amount |
Within the JSON value | Within this object | integer | Alternative 1. |
attributes[].default_date.unit |
Within the JSON value | Within this object | "days", "weeks", "months", "years" |
Alternative 1. |
attributes[].default_date.direction |
Within the JSON value | Within this object | "after", "before" |
Alternative 1. |
attributes[].default_date.anchor |
Within the JSON value | Within this object | "created" or string (uuid) |
Alternative 1. |
templates |
JSON body | Yes | array of object | |
templates[].id |
Within the JSON value | Within this object | string (uuid) | |
templates[].name |
Within the JSON value | Within this object | string | |
templates[].version |
Within the JSON value | Within this object | integer | |
templates[].type_id |
Within the JSON value | Within this object | string (uuid) | |
templates[].title |
Within the JSON value | Within this object | string | |
templates[].description |
Within the JSON value | Within this object | string | |
templates[].status_id |
Within the JSON value | Within this object | string | |
templates[].priority |
Within the JSON value | Within this object | "Low", "Normal", "High", "Urgent" |
|
templates[].owner_id |
Within the JSON value | Within this object | string (uuid) or null | |
templates[].assignee_ids |
Within the JSON value | Within this object | array of string (uuid) | |
templates[].team |
Within the JSON value | Within this object | string | |
templates[].attributes |
Within the JSON value | Within this object | object | |
templates[].attributes.{key} |
Within the JSON value | No | string or array of string | Value for each key in this object. |
templates[].checklist |
Within the JSON value | Within this object | array of object | |
templates[].checklist[].id |
Within the JSON value | Within this object | string (uuid) | |
templates[].checklist[].title |
Within the JSON value | Within this object | string | |
templates[].due_offset_days |
Within the JSON value | Within this object | integer or null | |
templates[].due_offset_unit |
Within the JSON value | No | "days", "weeks", "months", "years" |
|
templates[].is_default |
Within the JSON value | No | boolean | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
200 |
The configuration as saved, with its new version. |
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_configuration" |
Yes | |
data.version |
string | Yes | |
data.statuses |
array of object | Yes | |
data.statuses[].id |
string | Yes | |
data.statuses[].name |
string | Yes | |
data.statuses[].color |
"gray", "blue", "light-blue", "orange", "yellow", "green", "purple", "red" |
Yes | |
data.statuses[].completed |
boolean | Yes | |
data.types |
array of object | Yes | |
data.types[].id |
string (uuid) | Yes | |
data.types[].name |
string | Yes | |
data.types[].icon |
"CheckSquare", "Calendar", "Clock", "Folder", "Note", "User", "Users", "Email", "Phone", "Company", "Sales", "BarChart", "Rocket", "Star", "Tag", "Code", "Globe", "Location", "Workflows", "Activity", "Comment", "Grid", "Link", "Check", "HelpCircle" or null |
Yes | |
data.types[].description |
string or null | Yes | |
data.types[].status_ids |
array of string or null | Yes | |
data.types[].attribute_ids |
array of string (uuid) or null | Yes | |
data.types[].default_open_status_id |
string | Yes | |
data.types[].default_done_status_id |
string | Yes | |
data.attributes |
array of object | Yes | |
data.attributes[].id |
string (uuid) | Yes | |
data.attributes[].name |
string | Yes | |
data.attributes[].kind |
"Text", "Number", "Date", "Select", "Task name", "Description", "Status", "Related records", "Owner", "Assignees", "Priority", "Due date", "Parent task" |
Yes | |
data.attributes[].required |
boolean | Yes | |
data.attributes[].enabled |
boolean | Yes | |
data.attributes[].removed |
boolean | Yes | |
data.attributes[].description |
string or null | Yes | |
data.attributes[].options |
array of string | Yes | |
data.attributes[].multiple |
boolean | Yes | |
data.attributes[].default_value |
string or array of string or null | Yes | |
data.attributes[].default_creator |
boolean | Yes | |
data.attributes[].default_date |
object or null | Yes | |
data.attributes[].default_date.amount |
integer | Yes | Alternative 1. |
data.attributes[].default_date.unit |
"days", "weeks", "months", "years" |
Yes | Alternative 1. |
data.attributes[].default_date.direction |
"after", "before" |
Yes | Alternative 1. |
data.attributes[].default_date.anchor |
string | Yes | Alternative 1. |
data.templates |
array of object | Yes | |
data.templates[].id |
string (uuid) | Yes | |
data.templates[].name |
string | Yes | |
data.templates[].version |
integer | Yes | |
data.templates[].type_id |
string (uuid) | Yes | |
data.templates[].title |
string | Yes | |
data.templates[].description |
string | Yes | |
data.templates[].status_id |
string | Yes | |
data.templates[].priority |
"Low", "Normal", "High", "Urgent" |
Yes | |
data.templates[].owner_id |
string (uuid) or null | Yes | |
data.templates[].assignee_ids |
array of string (uuid) | Yes | |
data.templates[].team |
string | Yes | |
data.templates[].attributes |
object | Yes | |
data.templates[].attributes.{key} |
string or array of string | No | Value for each key in this object. |
data.templates[].checklist |
array of object | Yes | |
data.templates[].checklist[].id |
string (uuid) | Yes | |
data.templates[].checklist[].title |
string | Yes | |
data.templates[].due_offset_days |
integer or null | Yes | |
data.templates[].due_offset_unit |
"days", "weeks", "months", "years" |
Yes | |
data.templates[].is_default |
boolean | Yes | |
data.views |
array of object | Yes | |
data.views[].id |
string (uuid) | Yes | |
data.views[].name |
string | Yes | |
data.views[].layout |
"List", "Board" |
Yes | |
data.views[].filters |
object | Yes | |
data.views[].filters.search |
string | Yes | |
data.views[].filters.conditions |
array of object | Yes | |
data.views[].filters.conditions[].attribute_id |
string | Yes | |
data.views[].filters.conditions[].operator |
"contains", "does_not_contain", "is_empty", "is_not_empty", "is_any_of", "is_none_of", "equals", "not_equals", "greater_than", "less_than", "before", "after", "on", "not_on", "last_days", "not_last_days", "links_to", "does_not_link_to" |
Yes | |
data.views[].filters.conditions[].value |
string or number or array of string or object or null | Yes | |
data.views[].filters.conditions[].value.object_id |
string (uuid) | Yes | Alternative 1. Alternative 4. |
data.views[].filters.conditions[].value.record_id |
string (uuid) | Yes | Alternative 1. Alternative 4. |
data.default_view_id |
string (uuid) or null | Yes | |
data.priorities |
array of "Low", "Normal", "High", "Urgent" |
Yes | |
data.required_properties |
array of string | 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. |
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, version_conflict. |
410 |
One of: resource_expired. |
413 |
One of: request_too_large. |
422 |
One of: invalid_selection, configuration_in_use, attribute_type_locked, 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.