Todoist

1. Overview

Todoist is a leading task management and productivity application that helps users organize their work and life. It allows for the creation of tasks, sub-tasks, projects, and setting deadlines, all accessible across multiple platforms.

With the GoInsight Todoist node, you can seamlessly integrate task management into your automated workflows. This allows you to programmatically manage the entire lifecycle of your tasks, including:

• Task Management: Create, retrieve, update, and delete tasks.
• Task State Control: Close (complete), reopen, and move tasks between projects or sections.
• Project Information: Fetch a complete list of your projects to use their IDs in other operations.

2. Prerequisites

Before using this node, you must have a valid Todoist account. You will need to generate an API token from your Todoist settings to authenticate your requests.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Task and Project.

Operation Details

Create a Task

Creates a new task in Todoist. Supports natural language due dates ('tomorrow'), priority levels (1-4), labels, and assignment to projects/sections/users. If project_id is empty, task is added to Inbox. Use AdditionalFields for advanced options like sub-tasks (parent_id), time-blocking (duration), or hard deadlines (deadline_date). Returns complete task object with generated ID.

Idempotency: This action does NOT check for duplicates. Calling it multiple times with the same parameters will create multiple identical tasks. If you need to avoid duplicates, first use 'Get Many Tasks' to check if a similar task already exists.

API Version: Uses Todoist REST API v1 endpoint (/api/v1/tasks). Note: Todoist has deprecated Sync API v9 and REST v2, migrated to REST API v1 for stability.

Input Parameters:

• Content: Task title/content. Required. Example: 'Review Q1 financial report' , 'Call John about project update'.

Options:

• Description: Task description with additional details or notes. Supports Markdown formatting. Example: '## Agenda
• Point 1
• Point 2'.
• ProjectId: String ID of the project to add the task to. If omitted or empty, the task will be added to the user's Inbox. How to get ProjectId: call 'Get Many Projects' and use the id field; or from the Todoist web URL https://todoist.com/app/project/{project_id} (the trailing segment is the project id).
• SectionId: String ID of the section within the project to organize the task. Leave empty to add to project root. How to get SectionId: inspect the section in Todoist web/app and copy its ID from URL/context, or read section metadata from Todoist API responses.
• DueString: Human-readable due date in natural language. Examples: 'tomorrow', 'next Monday', 'Feb 10'. The API will parse it into a structured due date. Defaults to English; for other languages set 'due_lang' in AdditionalFields (e.g. zh). Supported codes include en, de, ja, pl, pt_BR, ru, es, sv, fr, zh, it, ko, nl, tr.
• Priority: Task priority level: 1 (highest/urgent), 2 (high), 3 (medium), 4 (low). Omit or leave 0 for Todoist default priority (4). Use 1-4 to set explicitly.
• Labels: Array of label names (strings) to categorize the task. Example: ['work', 'urgent']. Labels must already exist; if a name does not exist, the API typically returns 400 with a label-related error; create labels first in Todoist or via a label-creation action.
• AssigneeId: String ID of the user to assign this task to (for shared projects). Leave empty for personal tasks or to assign to yourself. How to get AssigneeId: use project collaborators from Todoist (e.g. 'Get Project Collaborators' or equivalent) and use the collaborator user id; or check project members in Todoist settings.
• AdditionalFields: Optional dictionary for advanced parameters: 'parent_id' (string, create sub-task), 'order' (int, position in list), 'due_date' (string YYYY-MM-DD), 'due_datetime' (string RFC3339 UTC, e.g. '2024-12-25T15:30:00Z'), 'due_lang' (string, language code like 'en', 'zh'), 'duration' (int, task duration amount), 'duration_unit' (string, 'minute' or 'day'), 'deadline_date' (string YYYY-MM-DD, hard deadline). Example: {'parent_id': '6XGgmFVcrG5RRjVr', 'duration': 30, 'duration_unit': 'minute'}.

Output:

• Task (object): The created task object returned by Todoist POST /api/v1/tasks.
• OriginalStatusCode (number): Original HTTP status code from Todoist API (e.g., 200, 400, 403, 404, 429, 500). 0 if request was not sent (parameter validation failed).
• StatusCode (number): Standardized status code: 200 for success or when the API returned an error payload (check ErrorMessage; e.g. rate limit after retries), -1 for parameter validation errors, 500 for network/system errors or request timeout.
• ErrorMessage (string): Error detail when the task was not created or the API reported failure (check together with StatusCode and OriginalStatusCode; e.g. rate limit after retries may set ErrorMessage while StatusCode remains 200). Empty when the task was created successfully.

Delete a Task

Permanently deletes a task from Todoist by its task ID. WARNING: This action cannot be undone. The task will be removed from all projects, sections, and any parent-child relationships. Sub-tasks are not automatically deleted. Use 'Close Task' instead if you want to mark task as completed while keeping it in history. Returns Deleted (bool) indicating success.

API Version: Uses Todoist REST API v1 endpoint (/api/v1/tasks/{id}). Note: Todoist has deprecated Sync API v9 and REST v2, migrated to REST API v1 for stability.

Input Parameters:

• TaskId: String ID of the task to delete. Required. Obtain from 'Get Many Tasks', 'Get a Task', or task creation response. Example: '6XGgm6PHrGgMpCFX'. WARNING: Deletion is permanent and cannot be undone.

Output:

• Deleted (bool): Boolean indicating whether the task was successfully deleted. True for success, False for errors. WARNING: Deletion is permanent and cannot be undone.
• OriginalStatusCode (number): Original HTTP status code from Todoist API (e.g., 204 for success, 400, 403, 404, 429, 500). 0 if request was not sent (parameter validation failed).
• StatusCode (number): Tool-level status code. 200=request reached Todoist and response was processed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/JSON-parse error (may retry).
• ErrorMessage (string): Detailed error message when StatusCode is not 200. Empty string indicates successful operation.

Get Many Tasks

Retrieves all active tasks from Todoist with advanced filtering and pagination. Supports filtering by project, section, parent task, label name, or specific task IDs. Uses cursor-based pagination (limit: 1-200, default: 50). Returns task metadata including content, priority, labels, due dates, and hierarchy. For custom filter queries, use the 'Get Tasks By Filter' action instead.

API Version: Uses Todoist REST API v1 endpoint (/api/v1/tasks). Note: Todoist has deprecated Sync API v9 and REST v2, migrated to REST API v1 for stability.

Options:

• ProjectId: Filter tasks by project ID. Returns all tasks from this project. Obtain from 'Get Many Projects' action or project URL. Example: '6XGgm6PHrGgMpCFX'
• SectionId: Filter tasks by section ID. Returns all tasks from this section within a project. Obtain SectionId from Todoist project view URL or section metadata in Todoist UI/API responses. Example: '6fFPHV272WWh3gpW'
• ParentId: Filter tasks by parent task ID. Returns all sub-tasks of the specified parent task. Useful for hierarchical task structures. Example: '6fFPHRxcmVqm4C84'
• Label: Filter tasks by label name (not ID). Case-sensitive. Returns all tasks with this label. Example: 'urgent', 'work', 'personal'. To get multiple labels, call this action multiple times.
• Ids: Retrieve specific tasks by their IDs. Comma-separated list of task IDs. Useful for batch retrieval. Example: '6XGgmFVcrG5RRjVr,6fFPHV272WWh3gpW'. Maximum recommended: 50 IDs per request.
• Cursor: Pagination cursor for fetching the next page of results. Leave empty for the first page. Obtained from the 'NextCursor' field in the previous response. This is an opaque string that should be passed as-is.
• Limit: Number of tasks to return per page. Valid range: 1-200. Default: 50. Recommended: Use 50-100 for balanced performance. Higher values reduce API calls but increase response size and processing time.

Output:

• Tasks (object-array): Return the task array object.
• NextCursor (string): Pagination cursor for fetching the next page. Empty string means no more pages available. Pass this value to the 'Cursor' input parameter to fetch the next page of results.
• HasMore (bool): Whether there are more tasks available beyond the current page. True if additional pages exist, False if this is the last page.
• OriginalStatusCode (number): Upstream HTTP status code from Todoist for diagnostics (e.g., 200/4xx/5xx). 0 means no usable upstream response was available (local validation failure, network/timeout, or response JSON parse failure).
• StatusCode (number): Tool-level status code. 200=request reached Todoist and response was processed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/JSON-parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get a Task

Retrieves a single active (non-completed) task by ID from Todoist. Returns complete task details including content, priority, labels, due dates, hierarchy, and metadata. Use cases: task detail display, status checking, validation before updates. Note: Only returns active tasks; completed tasks will return 404 error. Supports optional public key for accessing shared tasks.

API endpoint: Uses GET https://api.todoist.com/api/v1/tasks/{id} (Todoist unified REST API). Do not use https://api.todoist.com/rest/v2/tasks/{id}: Todoist returns HTTP 410 Gone with a body such as "API Error (410): This endpoint is deprecated." and instructs clients to migrate to /api/v1/ endpoints. See https://developer.todoist.com/

Input Parameters:

• TaskId: String ID of the task to retrieve. Obtain from 'Get Many Tasks' action, task URL, or previous task creation. Example: '6XGgmFVcrG5RRjVr'. Note: This retrieves only active (non-completed) tasks.

Options:

• PublicKey: Optional public access key for shared-task context. This tool still requires OAuth AccessToken and does not support unauthenticated calls. Leave empty for normal private-task access. Example: 'abc123xyz456'

Output:

• Task (object): Single task object from Todoist GET /api/v1/tasks/{id} (unified API; same field family as Get Many Tasks). Core fields: id, user_id, content, description, project_id, section_id, parent_id, child_order, priority, labels (array of strings), checked, added_at, updated_at, completed_at, due, duration, deadline, and related fields. Not returned: No url field; build from id if needed (for example https://todoist.com/showTask?id={id}). Note: Only active tasks are returned; completed tasks typically yield 404.
• OriginalStatusCode (number): The original HTTP status code from Todoist API. Default 0 means the request did not reach upstream (e.g., parameter validation failed, network timeout). Common values: 200=Success, 404=Task not found, 401=Unauthorized. Use for debugging.
• StatusCode (number): Standardized status code: 200 for success or when the API returned an error payload (check ErrorMessage; e.g. rate limit after retries), -1 for parameter validation errors, 500 for network/system errors or request timeout.
• ErrorMessage (string): Error detail when the task was not returned or the API reported failure (check together with StatusCode and OriginalStatusCode; e.g. rate limit after retries may set ErrorMessage while StatusCode remains 200). Empty when the request succeeded.

Close a Task

Closes (completes) a task in Todoist. Behavior: Regular tasks are marked complete and moved to history (including all subtasks). Recurring tasks are completed for current occurrence and automatically scheduled to next occurrence. This is the same behavior as completing a task in Todoist's official clients. Returns Closed (bool) indicating success. Use 'Reopen Task' to undo this action.

API Version: Uses Todoist REST API v1 endpoint (/api/v1/tasks/{id}/close). Note: Todoist has deprecated Sync API v9 and REST v2, migrated to REST API v1 for stability.

Input Parameters:

• TaskId: String ID of the task to close (mark as completed). Required. Obtain from 'Get Many Tasks', 'Get a Task', or task creation response. Example: '6XGgmFVcrG5RRjVr'. Regular tasks are marked complete and moved to history (including subtasks). Recurring tasks are scheduled to their next occurrence.

Output:

• Closed (bool): Boolean indicating whether the task was successfully closed (marked as completed). True for success, False for errors. Regular tasks are moved to history, recurring tasks are scheduled to next occurrence.
• OriginalStatusCode (number): Original HTTP status code from Todoist API (e.g., 204 for success, 400, 403, 404, 429, 500). 0 if request was not sent (parameter validation failed).
• StatusCode (number): Tool-level status code. 200=request reached Todoist and response was processed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/JSON-parse error (may retry).
• ErrorMessage (string): Detailed error message when StatusCode is not 200. Empty string indicates successful operation.

Reopen a Task

Reopens (uncompletes) a completed task in Todoist. The task is restored from history to the active task list. Any ancestor tasks or sections are also marked as uncomplete and restored. Important: Reinstated tasks and sections appear at the end of their parent list, after any previously active tasks. This is the reverse operation of 'Close Task'. Returns Reopened (bool) indicating success.

API Version: Uses Todoist REST API v1 endpoint (/api/v1/tasks/{id}/reopen). Note: Todoist has deprecated Sync API v9 and REST v2, migrated to REST API v1 for stability.

Input Parameters:

• TaskId: String ID of the completed task to reopen (mark as uncomplete). Required. Obtain from 'Get Many Tasks', 'Get a Task', or task history. Example: '6XGgmFVcrG5RRjVr'. Reopened task and any ancestor tasks/sections are restored from history and appear at the end of their parent list.

Output:

• Reopened (bool): Boolean indicating whether the task was successfully reopened (marked as uncomplete). True for success, False for errors. Reopened task and any ancestor tasks/sections are restored from history and appear at the end of their parent list.
• OriginalStatusCode (number): Original HTTP status code from Todoist API (e.g., 204 for success, 400, 403, 404, 429, 500). 0 if request was not sent (parameter validation failed).
• StatusCode (number): Tool-level status code. 200=request reached Todoist and response was processed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/JSON-parse error (may retry).
• ErrorMessage (string): Detailed error message when StatusCode is not 200. Empty string indicates successful operation.

Update a Task

Updates an existing task in Todoist. All fields except task_id are optional - only provided fields are updated, omitted fields remain unchanged. Supports natural language due dates ('tomorrow'), priority levels (1-4), labels, and assignment. Pass null for assignee_id to unassign. Use AdditionalFields to update advanced options like precise dates (due_date/due_datetime), duration, or hard deadlines. Pass null values in AdditionalFields to clear those fields.

API endpoint: Uses POST https://api.todoist.com/api/v1/tasks/{id} (Todoist unified REST API; v1 task update uses POST with JSON body). Do not use https://api.todoist.com/rest/v2/tasks/{id}: Todoist returns HTTP 410 Gone with a body such as "API Error (410): This endpoint is deprecated." and instructs clients to migrate to /api/v1/ endpoints. See https://developer.todoist.com/

Input Parameters:

• TaskId: String ID of the task to update. Required. Obtain from 'Get Many Tasks', 'Get a Task', or task creation response. Example: '6XGgmFVcrG5RRjVr'.

Options:

• Content: Updated task title/content. Omit or leave empty to keep unchanged. Example: 'Review Q1 financial report (UPDATED)'.
• Description: Updated task description with additional details. Supports Markdown formatting. Omit to keep unchanged. Example: '## Updated Notes
• New point added
• Revised timeline'.
• DueString: Updated due date in natural language. Examples: 'tomorrow', 'next Monday', 'Feb 15'. Omit to keep unchanged. Use 'DueLang' in AdditionalFields to specify parsing language.
• Priority: Updated priority level: 1 (highest/urgent), 2 (high), 3 (medium), 4 (low/default). Omit to keep unchanged. Must be integer 1-4.
• Labels: Updated array of label names (strings). Example: ['work', 'urgent']. Omit to keep unchanged. Pass empty array [] to clear all labels. Labels must exist in user's account.
• AssigneeId: Updated string ID of user to assign task to (for shared projects). Omit or leave empty to keep unchanged. Pass null to unassign (clear assignee).
• AdditionalFields: Optional dictionary for advanced parameters: 'due_date' (string YYYY-MM-DD, omit or null to keep/clear), 'due_datetime' (string RFC3339 UTC), 'due_lang' (string, language code like 'en', 'zh'), 'duration' (int, task duration amount, null to clear), 'duration_unit' (string, 'minute' or 'day', null to clear), 'deadline_date' (string YYYY-MM-DD, hard deadline, null to clear). Example: {'due_date': '2026-02-20', 'duration': null} to update date and clear duration.

Output:

• Task (object): The updated task object returned by Todoist API.
• OriginalStatusCode (number): Upstream HTTP status code from Todoist for diagnostics (e.g., 200/204/4xx/5xx). 0 means no usable upstream response was available (local validation failure, network/timeout, or response JSON parse failure).
• StatusCode (number): Tool-level status code. 200=request reached Todoist and response was processed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/JSON-parse error (may retry).
• ErrorMessage (string): Error detail for upstream business/API failures and local failures. Empty string means operation succeeded. Note: ErrorMessage can be non-empty even when StatusCode is 200.

Get Many Projects

Retrieves all active (non-archived) projects from Todoist with pagination support. Use cases: project listing, synchronization, backup workflows. Supports cursor-based pagination (limit: 1-200, default: 50). Returns project metadata including name, color, hierarchy, sharing status, and view preferences. For archived projects, use the separate 'Get Archived Projects' action.

API Version: Uses Todoist REST API v1 endpoint (/api/v1/projects). Note: Todoist has deprecated Sync API v9 and REST v2, migrated to REST API v1 for stability.

Options:

• Cursor: Pagination cursor for fetching the next page of results. Leave empty for the first page. Obtained from the 'NextCursor' field in the previous response. This is an opaque string that should be passed as-is. Example: 'eyJwYWdlIjoyfQ=='
• Limit: Number of projects to return per page. Valid range: 1-200. Default: 50. Recommended: Use 50-100 for balanced performance. Higher values reduce API calls but increase response size and processing time.

Output:

• Projects (object-array): Array of project objects. Each project contains: Core fields: - id (string): Unique project ID - name (string): Project name - color (string): Color identifier (e.g., 'berry_red', 'blue', 'charcoal') - parent_id (string|null): Parent project ID for nested projects, null for top-level - order (number): Display order position - comment_count (number): Number of comments on the project - is_shared (boolean): Whether the project is shared with collaborators - is_favorite (boolean): Whether marked as favorite - is_inbox_project (boolean): Whether this is the user's inbox project - is_team_inbox (boolean): Whether this is a team inbox - view_style (string): View style ('list' or 'board') - url (string): Web URL to access the project Note: Only active (non-archived) projects are returned.
• NextCursor (string): Pagination cursor for fetching the next page. Empty string means no more pages available. Pass this value to the 'Cursor' input parameter to fetch the next page of results.
• HasMore (bool): Whether there are more projects available beyond the current page. True if additional pages exist, False if this is the last page.
• OriginalStatusCode (number): Upstream HTTP status code from Todoist for diagnostics (e.g., 200/4xx/5xx). 0 means no usable upstream response was available (local validation failure, network/timeout, or response JSON parse failure).
• StatusCode (number): Tool-level status code. 200=request reached Todoist and response was processed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/JSON-parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through creating a simple workflow to add a new task to your Todoist inbox.

The workflow will consist of: Start -> Create a Task -> Answer.

1. Add the Tool Node

• In the workflow canvas, click the + button to add a new node.
• Select the "Tools" tab in the pop-up panel.
• Find and select "Todoist" from the list of tools.
• From the list of supported operations for Todoist, click on "Create a Task" to add the node to your canvas.

2. Configure the Node

• Click on the newly added "Create a Task" node to open its configuration panel on the right.
• Credentials: In the credentials field at the top, click the dropdown menu and select your pre-configured Todoist credential.
• Parameters: Fill in the required input parameters for the action.
  • Content: This is the title of your task. Enter a descriptive name, for example, Follow up with the design team.
  • Description (Optional): You can add more details about the task here, such as Discuss the new mockups for the landing page.
  • DueString (Optional): To set a deadline, you can use human-readable text like tomorrow at 4pm or every Friday.

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas will disappear.
• Click the "Run Test" button in the top-right corner of the canvas to execute the workflow.
• After a successful run, you can click the logs icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the task was created successfully.

After completing these steps, your workflow is fully configured. Every time you run it, a new task will be created in your Todoist account.

6. FAQs

Q: Why am I getting a 401 Unauthorized error?

A: This error typically means there is an issue with your API token. Please check the following:

• Ensure the API token entered in your GoInsight credential is correct and has not expired.
• Verify that the token has the necessary permissions to perform the requested actions (e.g., task:add, data:read_write).

Q: How can I find the ID for a specific project or section?

A: You can use the Get Many Projects operation to retrieve a list of all your projects along with their corresponding IDs. You can build a simple workflow to run this operation and view the output in the logs to find the ID you need for other operations like Create a Task.

7. Official Documentation

For more in-depth information about the Todoist API, please refer to the Todoist Official API Documentation.