# Better Tasks API

Source: https://neondeerdata.com/docs/api/tasks/

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](https://neondeerdata.com/docs/platform/better-tasks/) for setup and the [permissions guide](https://neondeerdata.com/docs/api/permissions/) 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](https://neondeerdata.com/docs/api/tasks/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](https://neondeerdata.com/docs/api/tasks/creation/). 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](https://neondeerdata.com/docs/api/tasks/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](https://neondeerdata.com/docs/api/tasks/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](https://neondeerdata.com/docs/api/tasks/comments/). 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](https://neondeerdata.com/docs/api/tasks/sync/). 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](https://neondeerdata.com/docs/api/tasks/tasks/) 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.
