Search documentation

Search for a topic, a control, or an event type.

    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.