Better Tasks API
Create and manage Better Tasks, configure views, read comments, and resolve sync issues.
Access
The Better Tasks app and API are generally available. API access is included on Paid and during an active trial. The connection still needs the relevant task permissions. MCP is generally available and uses the same plan and permission checks. Read the app guide for setup and the permissions guide before granting writes.
Task creation allowances
Task creation allowances belong to the app and are separate from API availability. Free does not include API access.
Free includes 20 new Better Tasks per month, up to 200 in total. Paid plans and the trial include unlimited task creation. Imported Attio tasks do not count; new subtasks and repeating occurrences do. Archived tasks remain counted.
Create and template requests return budget_exceeded when the plan's creation allowance is used. Creating tasks for several records can return successful tasks alongside allowance_used for records that received none. Review each outcome before retrying. Editing, completing, commenting, and syncing existing tasks still work.
Tasks and templates
Create, read, update, archive, or import tasks. Importing an existing Attio task brings it into Better Tasks. A task already in Attio must be renamed in Attio; other supported properties can be updated here. Newly assigned owners and assignees must be active Attio members. Existing assignments to a member later suspended remain valid.
Create from a template or for selected records. Read the template and its version from configuration first. A changed or removed template returns version_conflict. Creation from a template returns an operation to follow until the task reaches Attio.
For one task per record, supply exactly one of task or template, the records, and a submission_id. Review each record's result. Reusing the submission ID creates only tasks still missing from that submission. No separate confirmation is required for this task action. Omit confirmed in new callers; the legacy value true is optional and ignored. This applies to REST and MCP. Permissions and plan checks still apply.
Related records and configuration
linked_records is optional on direct task creation and template creation unless the workspace requires Related records. Read required_properties from task configuration before creating a task. Missing required records are refused as invalid_selection, with linked_records as the parameter. New organizations start with related records optional; older configurations retain the requirement until an admin changes it. Tasks already linked to records must keep at least one.
Select attributes and views
Read task configuration before writing. Former Tags attributes now return kind: "Select" with multiple: true. Their IDs, options, defaults, and saved values are preserved. Update callers that still write kind: "Tags"; that value is refused. Task and template values remain in attributes, keyed by attribute ID. The earlier top-level tags and attribute binding fields remain unsupported.
Configuration includes task types, statuses, attribute definitions, templates, ordered views, and default_view_id. A view has a name, layout, and filters. Supplying views replaces the saved view list: omitted existing views are deleted, while retained views keep their columns. Leaving out views or default_view_id leaves that setting unchanged. Use the current configuration version when updating it.
An organization default view is available through the API. Each member's personal default is managed in Neon Deer or the Attio app, not through a public API operation.
Comments and pagination
Read or add comments on a task, or search comments across tasks. Use group_by=comment for individual comments or group_by=task for each task's newest comment. Filter by author, date, text, or the supported task fields.
A cross-task comments page may be empty before the end. Continue with pagination.next_cursor until it is null. Once using a cursor, send it without the original filters.
Review and repair sync
Filter tasks with needs_attention=true, then read the sync review. It identifies whether to resolve conflicting values, link the correct Attio task, or retry an unchanged task. For conflicting values, compare the saved task with the Attio task before choosing a source for each value. The Activity is a display copy, not a source for resolving differences.
Resolution requires the review's current version and fingerprint. Linking requires the current version and the Attio task ID. These task repair actions no longer require an extra confirmation in MCP or REST. The optional legacy confirmed: true is ignored. Follow returned operations until they finish. If the task changed meanwhile, read a fresh review before retrying.
Sync issue changes
Task reads can return sync_issue: "type_deleted" when the Better Tasks Activity type was removed in Attio. Read the current sync review and follow the offered retry to repair setup. Task changes are queued for Attio immediately; a refused Activity setup step no longer holds up the linked task update. Changes to Activity records in Attio are not automatically read back.
The visible ID fields are External task ID, Attio task ID, and Parent external task ID. These labels do not rename the API's stable identifiers.
Archiving deletes the linked task in Attio
POST /v1/task-management/{task_id}/archive and MCP archive_task retain the archived copy in Better Tasks and delete its linked Attio task and Activity. This cannot be undone. The Attio deletions may continue after the task is shown as archived and are retried if Attio is unavailable. Tasks archived before this change keep their Attio task.
Deleting the Attio task archives its Better Task and subtasks. Deleting only its Activity does not archive the task: Neon Deer recreates that display copy. Edits made directly to the Activity are overwritten on the task's next change. Edit the Better Task or the Attio task instead.
A task whose creation in Attio is unconfirmed must first be linked with link_task_to_attio_task; otherwise archiving is refused with invalid_selection. When archiving from Better Tasks, archive or move open subtasks first.
Configuration and request compatibility
Remove templates[].assign_record_owner from configuration writes; it is no longer supported and is refused. Title, Description, Due date, Assignees, Related records, Status, and Owner keep their built-in names. Their names cannot be changed through configuration.
New tasks still need required values. An existing task missing a value that became required later can be edited, but an edit cannot clear a required value the task already holds. A refused request names what needs fixing. Incorrect types or IDs return invalid_request; a task value or attribute not permitted by its task type returns invalid_selection.
Filter operators and empty values
Saved task-view filters now include is_none_of for owners, assignees, and recurrence; does_not_contain for text; not_equals for numbers; not_on, not_last_days, and is_not_empty for dates; and does_not_link_to and is_not_empty for related records. Read configuration and use operators supported by the field's type.
Negated comparisons do not include empty values. Null, empty or whitespace-only text, and empty lists count as empty. Use is_empty to include those tasks; use is_not_empty when you require a value.
Select, Owner, Assignees, and Number attributes also support is_empty and is_not_empty. Status, Priority, Task type, and Repeat always hold a value and do not offer these operators.
Current sync-review responses
The activity source and conflicts[].activity are removed. Sync-review situations are conflict, create_unconfirmed, and retry; activity_missing, activity_invalid, and attio_task_missing are no longer returned. A missing Attio task is handled through the review's retry next step rather than a separate missing-task situation.
Review, resolve, link, and retry requests return recovery_not_available when the task no longer needs sync attention. version_conflict still identifies a stale version. Re-read the task after synchronization, since sync itself can change its version; do not keep reusing the creation receipt's version.
Import existing Attio tasks
Use Tasks and imports to list existing Attio tasks with GET /v1/task-management/attio-tasks. Set imported=false to find tasks not yet in Better Tasks. Search with q, filter by completion, assignees, related records, due dates, or creation dates, and use sort to set the order. Repeated assignee_id values match any listed member. assignee_id=me refers to the member who connected the AI app; an API key has no signed-in member to infer.
Each result includes imported and its Better Tasks task_id, when present. Follow pagination.next_cursor until null. complete: false means the list does not cover every Attio task; finishing those pages does not make it a complete inventory.
Send selected Attio task IDs as native_task_ids to POST /v1/task-management/attio-tasks/imports, with an Idempotency-Key header. MCP uses list_importable_attio_tasks and create_tasks_from_attio, with request_key for the write. Each requested ID has a result in the same order: imported, already imported, or an error such as not_found, invalid_values, or unavailable. Inspect every result before retrying. The existing single-task import remains available.
An imported task's blank values take its task type's defaults, which are then sent to Attio. Review those defaults before importing. Importing existing Attio tasks does not use the new-task allowance.
Editing task attributes
When update_task includes attributes, it replaces the task's complete set of custom attribute values. An attribute omitted from that object is cleared. Read the current task, preserve values you want to keep, and send the complete replacement with the current version. Omit attributes entirely when you are not changing those values.
Configuration reads include built-in Title, Description, Status, and Due date even before they have been customized. Their names stay fixed. Sending unchanged definitions back does not create overrides.