Docs / Workflows / Integrations / Todoist
Todoist
Read and manage Todoist tasks, projects, sections, comments, labels and saved filters, and start workflow jobs from Todoist events.
What you can do
Each Todoist integration’s page in OAIZ shows these uses, with its events and its read and write actions, under What you can do with Todoist.
- Follow-up tasks
- Create a task for each email that needs a follow-up.
- Morning list
- Send a morning list of today’s tasks.
- Task comments
- Add a comment to a task when its customer replies.
Connection scope
A Todoist connection works with one Todoist account and that account’s access. Its tools cover tasks, personal and workspace projects, sections, comments and files, labels and saved filters. Folders and workspace members exist only in Todoist workspaces, which are Todoist’s team accounts.
Changes made through the connection appear in Todoist as the connected user. A comment an agent posts shows that person as its author.
Agents that use the connection also receive the account’s project names with their folders and sections, its personal and shared label names, and the people in its shared projects and workspaces. Each carries its Todoist ID, except a shared label, which has only a name.
Connecting
Todoist connects through OAuth. In Integrations, choose Create, select Todoist and choose Connect with Todoist. Sign in to Todoist and approve the access. Todoist’s consent screen names the app oaiz. The connection belongs to the account that approves it.
The authorization requests data:read_write, data:delete, project:delete and backups:read.
Read actions
- List Tasks
- Read one page of active tasks, filtered by project, section, parent task, exact label name or task IDs.
- Get Task
- Read one active task by ID, with its content, description, labels, priority, due date, deadline and duration.
- Search Tasks
- Find active tasks that match a Todoist filter query, such as today & @work.
- List Completed Tasks
- Read one page of completed tasks in a date range, by completion date or by due date.
- Get Completed Task Stats
- Read recent daily and weekly completion counts, the lifetime total and karma. Weekly data depends on the Todoist plan.
- List Activities
- Read one page of the account’s activity log, filtered by object, change type, project, task, person or date range.
- Get User
- Read the connected account’s name, email, time zone, plan status and completion goals.
- List Projects
- Read one page of the active projects the account has joined, optionally in one workspace or folder.
- Get Project
- Read one project by ID.
- Search Projects
- Find active projects by name, ignoring case, with * as a wildcard.
- List Archived Projects
- Read one page of the account’s archived projects.
- List Project Collaborators
- Read one page of a project’s collaborators with their user IDs, names and emails.
- Get Project Permissions
- Read Todoist’s table of the actions each project and workspace role allows. It does not report the account’s own role on a project.
- List Folders
- Read one page of a workspace’s folders. Folders group workspace projects.
- Get Folder
- Read one folder by ID.
- List Workspaces
- List the workspaces the account belongs to. The list is empty for an account without a team workspace.
- Get Workspace
- Read one workspace’s name, plan and guest setting.
- List Workspace Users
- Read one page of members with their roles and emails, for one workspace or every workspace the account belongs to. Workspace guests cannot read members.
- List Sections
- Read one page of active sections, optionally in one project.
- Get Section
- Read one section by ID, including whether it is archived.
- Search Sections
- Find active sections by name, ignoring case, with * as a wildcard.
- List Comments
- Read one page of the comments on one task or one project.
- Get Comment
- Read one comment by ID, such as the comment in a comment event.
- List Labels
- Read one page of the account’s personal labels with their IDs.
- Get Label
- Read one personal label by ID.
- Search Labels
- Find personal labels by name, ignoring case, with * as a wildcard.
- List Shared Labels
- Read one page of label names on active tasks, including labels collaborators added in shared projects. Shared labels have a name and no ID.
- List Filters
- Read the account’s personal saved filters or one workspace’s shared filters.
- Get Filter
- Read one saved filter by ID, including its query.
Write actions
- Create Task
- Create a task from structured fields. A task without a project goes to the Inbox.
- Quick Add Task
- Create a task from one line of text that Todoist parses, with an optional first comment.
- Update Task
- Change the fields you supply on a task and keep the rest. Returns the updated task.
- Move Task
- Move a task to exactly one project, section or parent task.
- Complete Task
- Complete a task. A recurring task moves to its next date and stays open.
- Reopen Task
- Reopen a completed task.
- Delete Task
- Delete a task and its subtasks.
- Create Project
- Create a personal project or sub-project, or a project in a workspace.
- Update Project
- Change the project fields you supply, or move a workspace project into or out of a folder.
- Delete Project
- Permanently delete a project with its sub-projects, sections and tasks.
- Archive Project
- Archive a project and its sub-projects so they can be restored.
- Unarchive Project
- Restore an archived project. A restored sub-project returns as a top-level project.
- Join Project
- Join a workspace project by ID. The account then receives its notifications and stays a member until it leaves the project in Todoist.
- Create Folder
- Create a folder in a workspace.
- Update Folder
- Rename a folder.
- Delete Folder
- Delete a folder. Its projects leave the folder and stay in the workspace.
- Create Section
- Create a section in a project.
- Update Section
- Change a section’s name, description, position or collapsed state.
- Delete Section
- Permanently delete a section and all its tasks.
- Archive Section
- Archive a section so it can be restored.
- Unarchive Section
- Restore an archived section by ID.
- Create Comment
- Post a comment on one task or one project, with at most one attached file. Returns the new comment and its ID.
- Update Comment
- Replace a comment’s text.
- Delete Comment
- Permanently delete a comment.
- Add Comment Reaction
- Add the connected account’s emoji reaction to a comment.
- Remove Comment Reaction
- Remove the connected account’s own emoji reaction from a comment. Reactions from other people stay.
- Upload File
- Upload one OAIZ file to Todoist for use as a comment attachment.
- Delete File
- Delete a file the account uploaded, identified by the fileUrl Upload File returned.
- Create Label
- Create a personal label. The account’s plan and label limit can refuse it.
- Update Label
- Change a personal label’s name, color, position or favorite state.
- Delete Label
- Permanently delete a personal label.
- Rename Shared Label
- Rename a label on every active task that carries it.
- Remove Shared Label
- Remove a label from every active task that carries it. Other labels stay.
- Create Filter
- Save a named filter query for the account or for a workspace.
- Update Filter
- Change the filter fields you supply.
- Delete Filter
- Permanently delete a saved filter.
- Reorder Filters
- Set the order of selected saved filters. Each filter reports its own outcome.
Pages and identifiers
Most list and search tools return one page per call, 50 results by default. List Workspaces and List Filters return every result at once. The limit field accepts up to 200, or up to 100 for List Workspace Users. A page with more results returns nextCursor. Pass it as cursor with the same filters to read the next page. The last page has no nextCursor.
Actions take Todoist IDs from read actions, events or agent context. A task’s labels hold label names. A label ID from List Labels identifies the label itself and never goes into a task’s labels.
Tasks and scheduling
Create Task stores the fields you supply as written. Quick Add Task sends one line of text to Todoist’s parser, which reads its date and any project, label and priority markers, as the Todoist app does.
A due date can repeat, such as every weekday at 09:00 in dueString. A deadline is a separate date that never repeats. Todoist can refuse deadline and duration fields when the account’s plan does not include them.
Update Task leaves omitted fields unchanged. An empty description or labels list clears that field, and clearDue, clearDeadline, clearDuration and clearAssignee remove those values. Complete Task and Reopen Task return Todoist’s acknowledgement without the task’s new state. Get Task shows a recurring task’s next date.
History and saved filters
List Completed Tasks reads completed tasks by completion date, up to three calendar months per request, or by due date, up to six weeks. List Activities reads the account’s activity log of additions, edits, completions, moves and other changes to tasks, comments, projects and sections. Todoist keeps that log for a period set by the plan, so an empty page does not prove that nothing happened.
Search Tasks runs a query once and saves nothing. A saved filter is a named query that appears in Todoist. Create Filter saves one for the account or for a workspace whose plan supports shared filters. Workspace members share those filters, and marking one as a favorite stays personal.
Comments and files
A comment belongs to one task or one project. Comments on a project are separate from the comments on its tasks.
To attach a file, run Upload File and copy the returned fileUrl, fileName, fileType and resourceType into the attachment of Create Comment. The uploaded file is attached to nothing until a comment uses it. Upload File accepts files up to 25 MB, and the Todoist plan can set a lower limit. In a workflow, Upload File can take one file from the event that started the job, selected by file type or name when the event carries several.
Archiving, deleting and shared labels
Archive Project and Archive Section keep work recoverable through Unarchive Project and Unarchive Section. A personal project is archived only for the connected account. A workspace project is archived for every member.
Delete Project and Delete Section remove everything inside them and cannot be undone. A workspace project must be archived before deletion, and only a workspace admin can delete it.
Rename Shared Label and Remove Shared Label change the label on collaborators’ tasks in shared projects as well as the account’s own. Delete Label also removes a personal label from every active task that carries it. Completed tasks keep the name. Update Task changes the labels of one task.
Events
Event types use the e:todoist/ prefix. The following names identify the changes a job can match.
- Tasks
- item-added, item-updated, item-completed, item-uncompleted and item-deleted report creation, edits, completion, reopening and deletion. Their task data includes IDs, content, labels, priority and due information.
- Comments
- note-added, note-updated and note-deleted report comment changes. The comment identifies its task or project and carries its text and any attachment metadata.
- Projects
- project-added, project-updated, project-deleted, project-archived and project-unarchived report project changes and archive state.
- Sections
- section-added, section-updated, section-deleted, section-archived and section-unarchived report changes to a section within its project.
- Labels
- label-added, label-updated and label-deleted report changes to label definitions.
- Filters
- filter-added, filter-updated and filter-deleted report changes to saved filters, including their query.
- Reminders
- reminder-fired identifies the reminder, its task and the account receiving the notification.
Event data and task updates
Each event contains subscriberUserId, initiator, triggeredAt and deliveryId. The affected object is under task, comment, project, section, label, filter or reminder. triggeredAt is Todoist’s time for the change. deliveryId identifies the notification across delivery retries.
An item-updated event includes the current task. When Todoist supplies earlier fields, previousTask contains only the fields Todoist supplied. labelDiffAvailable is true when previous labels were supplied. In that case, labelsAdded and labelsRemoved list the changed label names.
Match the affected object’s ID when a workflow follows a particular task or project. For example, e:todoist/item-completed with task.projectId equal to a selected project can start a completion summary.
Label-triggered workflows
A workflow you build can hand a task to an agent when someone adds a chosen label, such as agent, and post the reply as a comment on that task.
The first job listens for e:todoist/item-updated with one AND group of two conditions. labelDiffAvailable Equals true comes first, then labelsAdded Contains agent. Its Agent or LLM Call action reads {{ properties.task.content }} and {{ properties.task.description }} and writes a reply. The job’s output event carries the task and the reply.
A second job listens for that output event and runs Create Comment, with taskId set to {{ properties.task.id }} and content set to the reply.
labelsAdded is absent from updates without previous labels, and a Contains condition on a missing field reports an error instead of a non-match. Testing labelDiffAvailable first skips those updates. Later edits to a task that already carries the label leave it out of labelsAdded, so those edits do not start the workflow again.
Disconnecting
Removing a Todoist connection asks Todoist to revoke its access token, then deletes both of its tokens from OAIZ. Todoist documents revocation for access tokens only, and the removal result says so. When Todoist does not confirm the revocation, the connection is still removed with a warning. When Todoist cannot process the request, removal stops so you can try again.
OAIZ’s Todoist app receives events for every connected account through one webhook, so removing one connection leaves other Todoist connections and their events in place. Todoist tasks, projects and comments stay unchanged.