Menu

Mattering Automations Todoist integration

Connect Todoist to Mattering Automations: projects, tasks with filter queries and natural language quick add, sections, labels, and comments as workflow steps on the current unified API v1, authenticated with a Todoist API token.

The Mattering Automations Todoist integration adds Todoist to your automation canvas: projects with archive and unarchive, tasks with Todoist's filter query language and natural language quick add, completed-task history, sections, labels including shared labels, and comments.

Setup takes a couple of minutes: copy your API token from Todoist's settings, attach it as a credential in Mattering, and test the connection. This guide walks through each step and ends with the full node reference.

This integration is built on Todoist's current unified API v1 (api.todoist.com/api/v1), not the deprecated REST v2. That matters for one practical reason: the migration changed ids to opaque strings, and old numeric ids from v2-era integrations are rejected. If you are porting automations from an older Todoist setup, re-fetch ids through these nodes rather than reusing stored numeric ones.

Before you start

  • A Todoist account (any plan; the API works on the free tier).
  • Your API token from Settings, then Integrations, then the Developer tab.
  • A Mattering workspace with access to the Automations app.

Get your Todoist API token

Mattering authenticates to Todoist with your personal API token, sent as a bearer credential on every request. The token acts as you across everything your account can see.

In Todoist, open Settings, then Integrations, then the Developer tab.
Copy your API token.
The token grants full account access and has no scopes. Treat it like a password: if it leaks, reset it from the same Developer tab, which invalidates the old value, then update the credential here.

Connect Todoist to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Todoist from the list.
Click Create new credential, paste your API token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection: Mattering lists your projects, a safe read that always returns at least the Inbox.
Click Connect. All 35 Todoist nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Todoist section should list the query and action nodes. Drop Todoist: List Projects onto the canvas and run a test step: it is a safe read, never empty (the Inbox always exists), and returns the project ids other nodes use. Note that ids are opaque strings in the unified API, not numbers.

For a satisfying end-to-end check, run Todoist: Quick Add Task (Natural Language) with a plain sentence including a due phrase: the response shows the parsed task with its due date, and Todoist: Delete Task or a manual delete in Todoist cleans it up. Or stay read-only with Todoist: List Tasks by Filter Query and the query today.

Node reference

35 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 14

Todoist: Get Comment

todoist_get_comment

Return one comment by ID, including its content, author, post time, and attachment metadata.

Todoist: Get Label

todoist_get_label

Return one personal label by ID, including its name, color, order, and favorite flag.

Todoist: Get Project

todoist_get_project

Return one project by its opaque string ID, including name, color, view style, sharing state, and hierarchy position.

Todoist: Get Section

todoist_get_section

Return one section by its opaque string ID, including its name, project, order, and archived state.

Todoist: Get Task

todoist_get_task

Return one active (non-completed) task by ID, including content, due and deadline objects, labels, priority, and its project/section/parent placement.

Todoist: List Comments

todoist_list_comments

Get all comments of one task OR one project, paginated. Provide exactly one of task_id or project_id; providing neither or both is an error. File attachments arrive as metadata objects with a file_url, never inline file content.

Todoist: List Completed Tasks

todoist_list_completed_tasks

Get tasks completed within a date-time range of up to 3 months, paginated - the building block for done-this-week digests and completion reports. Optionally narrowed by workspace, project, section, parent task, or a filter query. Note the page items arrive under an 'items' key on this endpoint.

Todoist: List Labels

todoist_list_labels

Get all of the user's personal labels, paginated. Label NAMES (not ids) are what task label fields and the label filter expect.

Todoist: List Project Collaborators

todoist_list_project_collaborators

Get all collaborators of a shared project, paginated. Collaborator user ids are what the task assignee_id field expects.

Todoist: List Projects

todoist_list_projects

Get all active projects for the user, paginated. Works with an empty config (every account has at least the Inbox project), which is why it doubles as the credential health check. Project ids from here feed every project-scoped node.

Todoist: List Sections

todoist_list_sections

Get active sections, paginated - all of them, or only those of one project via project_id.

Todoist: List Shared Labels

todoist_list_shared_labels

Get the unique shared label names currently in use on active tasks, paginated. Shared labels are names applied by collaborators that are not in the user's personal label list.

Todoist: List Tasks

todoist_list_tasks

Get active (uncompleted) tasks, paginated. All parameters are optional and combine to narrow the list: by project, section, parent task, label name, or an explicit id list. With no parameters it returns every active task the user can see.

Todoist: List Tasks by Filter Query

todoist_list_tasks_by_filter

Get active tasks matching a Todoist filter query, paginated. Filters are Todoist's own query language: 'today | overdue', '#Work & p1', 'due before: next week', '@waiting'. One filter expression per call (the comma operator that combines several filters into tabs is not supported here).

Action nodes 21

Todoist: Archive Project

todoist_archive_project

Archive a project and return it. Personal projects are archived only for the initiating user; workspace projects are archived for every workspace user. Reversible with Todoist: Unarchive Project, so this is not flagged destructive.

Todoist: Close Task

todoist_close_task

Complete a task, exactly like checking it off in the app: regular tasks (with their sub-tasks) move to history, and recurring tasks are rescheduled to their next occurrence. Reversible with Todoist: Reopen Task, so this is not flagged destructive. Returns null on success.

Todoist: Create Comment

todoist_create_comment

Add a comment to one task OR one project and return it. Provide exactly one of task_id or project_id. An attachment is passed as a metadata object referencing an already-hosted file URL (this connector does not upload file bytes).

Todoist: Create Label

todoist_create_label

Create a personal label and return it. Free-plan label limits apply; exceeding them returns a premium-only error.

Todoist: Create Project

todoist_create_project

Create a new project and return it. Give a parent_id to nest it as a sub-project, or a workspace_id to create a workspace project instead of a personal one.

Todoist: Create Section

todoist_create_section

Create a new section inside a project and return it.

Todoist: Create Task

todoist_create_task

Create a new task with explicit typed fields and return it. Only content is required; without a project_id the task lands in the Inbox. For natural-language input ('Buy milk tomorrow #Shopping p1') use Todoist: Quick Add Task instead.

Todoist: Delete Comment

todoist_delete_comment

PERMANENTLY delete a comment. This cannot be undone. Returns null on success.

Todoist: Delete Label

todoist_delete_label

PERMANENTLY delete a personal label and remove it from every task that carries it. This cannot be undone. Returns null on success.

Todoist: Delete Project

todoist_delete_project

PERMANENTLY delete a project together with ALL of its sections and tasks. This cannot be undone; archive the project instead if you may need it back. Returns null on success.

Todoist: Delete Section

todoist_delete_section

PERMANENTLY delete a section and ALL of its tasks. This cannot be undone. Returns null on success.

Todoist: Delete Task

todoist_delete_task

PERMANENTLY delete a task and all of its sub-tasks. This cannot be undone; use Todoist: Close Task if completing it is enough. Returns null on success.

Todoist: Move Task

todoist_move_task

Move a task to another project, section, or under a parent task, and return the moved task. Provide exactly ONE of project_id, section_id, or parent_id as the destination.

Todoist: Quick Add Task (Natural Language)

todoist_quick_add_task

Create a task from one natural-language string using the same Quick Add parser as Todoist's own apps: dates ('tomorrow at 5pm'), #Project, /Section, @label, priority p1-p4, +Assignee, {deadline}, !reminder, and '// description' in a single line. If part of the text fails to parse the task is still created with the unparsed text left in the content.

Todoist: Reopen Task

todoist_reopen_task

Uncomplete a task, restoring it (and any completed ancestor tasks or sections) from history to the end of the list inside its parent. Returns null on success.

Todoist: Unarchive Project

todoist_unarchive_project

Restore an archived project to active, and return it. For workspace projects this makes it visible again to all applicable workspace users.

Todoist: Update Comment

todoist_update_comment

Replace a comment's text content and return the updated comment.

Todoist: Update Label

todoist_update_label

Update a personal label's name, order, color, or favorite flag, and return it. Omitted fields are left unchanged; at least one field must be provided.

Todoist: Update Project

todoist_update_project

Update a project's name, description, color, favorite flag, view style, or position, and return the updated project. Omitted fields are left unchanged.

Todoist: Update Section

todoist_update_section

Update a section's name, order, collapsed state, or description, and return it. Omitted fields are left unchanged.

Todoist: Update Task

todoist_update_task

Update an existing task's fields and return it. Omitted fields are left unchanged. To change which project, section, or parent a task belongs to, use Todoist: Move Task - those fields are not updatable here.

Using the integration

On the automation canvas

Todoist nodes chain with every other node: a morning Todoist: List Tasks by Filter Query sweep can build an agenda comment on a standing task in Mattering Productivity, escalations can branch off overdue matches, and completions can flow both directions between Todoist and Mattering tasks.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can read agendas, add tasks, and close finished work through the same nodes your workflows use. Todoist: Quick Add Task (Natural Language) is the assistant-native entry point: the assistant writes the same sentence a person would type, and Todoist's parser does the structuring.

Quick add versus structured create

Todoist: Quick Add Task (Natural Language) sends one line through the same parser the Todoist apps use, extracting due date, project, labels, and priority from the text. Todoist: Create Task takes clean structured fields. Use quick add when the input is human phrasing (messages, form text, assistant output); use create when a workflow already has exact values.

Filter queries as the workflow engine

Todoist: List Tasks by Filter Query runs Todoist's filter language: today, overdue, date windows, labels, priorities, project scoping, and boolean combinations. It is the same language as saved filters in the app, which means power users can prototype the query in Todoist and paste it into the node.

Close and archive, not delete

Todoist: Close Task has Todoist: Reopen Task as its documented inverse, and Todoist: Archive Project has Todoist: Unarchive Project, so completion and retirement loops are reversible by construction. The five delete nodes (task, project, section, label, comment) are the only destructive operations and are flagged; prefer close and archive in automated flows.

Pagination and history

List nodes use the unified API's cursor pagination: results plus next_cursor, with a limit up to 200 per page. Todoist: List Completed Tasks queries by completion-date window (up to about three months per query) and is the engine for done-list reporting; its results arrive under an items key, the one documented deviation, shown honestly in the node's sample output.

Troubleshooting

Test Connection fails with a 401
The token is invalid, was reset, or picked up stray whitespace when pasted. Copy the current token from Settings > Integrations > Developer and update the credential; resetting the token in Todoist invalidates all previous copies.
A node rejects an id that worked in an old integration
That is the v1 migration. The unified API uses opaque string ids, and old numeric ids from REST v2-era integrations are rejected. Re-fetch current ids through Todoist: List Projects, Todoist: List Tasks, or their get twins, and update stored references; do not translate numeric ids by hand.
A filter query returns nothing or errors
Test the same query as a filter inside the Todoist app first: the node runs the identical language, so a query that works there works here. The usual culprits are misspelled label names, project names needing quoting, operators from memory rather than the filter docs, or trying to use the comma operator, which builds tabs in the app and is not supported in a single API filter.
Priorities behave backwards
Todoist's own docs disagree on direction: the create documentation says 1 is highest while the task object documentation says the API returns 4 for p1. On the wire, 4 means p1 (urgent) and 1 means p4 (normal), and these nodes follow that behavior. If a priority-driven branch matters, verify against one real task before trusting it.
Completed tasks are missing from List Completed Tasks
The completed list is windowed by completion date, with a maximum span of about three months per query. Query the window the completion actually falls in, and page with the cursor when a busy window overflows one page. Also note its results arrive under an items key, unlike the results key on other lists.
Close Task succeeded but the recurring task is still there
That is recurrence working: closing a recurring task completes the current occurrence and schedules the next one. Only removing the recurrence from the due string (via Todoist: Update Task) or deleting the task ends the series; a close never will.
Update or delete responses look empty
Several unified-API write endpoints return an empty body (JSON null) on success by design, and the delete, close, and reopen nodes surface exactly that. A 200 with null data is success, not failure; branch on status rather than on response content for these nodes.
Calls fail with a 429 rate limit
The unified API enforces per-token rate limits. Space out scheduled sweeps, use the filter-query node to fetch precisely the tasks a workflow needs instead of listing everything and filtering downstream, and let the workflow wait and retry after a 429.

Todoist is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products