Connection
- Authentication: API key (Personal API token).
Log in to the Todoist web app (todoist.com) → click your avatar at the top-left → Settings → Integrations → Developer tab → Copy API token. The token acts with your full Todoist account — there are no scopes to choose. “Issue a new API token” on the same tab revokes the old one.See Todoist’s documentation.
Read actions (9)
| Action | Description |
|---|---|
filter_tasks | List active tasks matching a Todoist filter query, e.g. “today | overdue”, “p1 & #Work”, “@waiting”, “due before: next week”. Arguments: query (string, required, max 1024 chars); lang (string, IETF tag of the language the query is written in, e.g. “fr”, when not English); cursor, limit (1-200). |
get_task | Retrieve one active task: content, description, project, section, labels, priority, due date, deadline, duration and assignee. |
list_comments | List the comments of a task or of a project. Provide exactly one of task_id or project_id. Optional: cursor, limit (1-200). |
list_completed_tasks | List tasks completed within a time window of at most 3 months — their ids are what reopen_task accepts. Arguments: since and until (strings, RFC 3339 date-times, e.g. “2026-09-01T00:00:00Z”; since inclusive, until exclusive; both required). Optional: project_id, section_id, parent_id, filter_query (string, Todoist filter syntax, max 1024 chars), filter_lang (string, IETF tag), cursor, limit. Answers { items, next_cursor }. |
list_labels | List the personal labels of the connected user — their names are what labels accepts on create_task/update_task. Optional: cursor, limit (1-200). |
list_project_collaborators | List the collaborators of a shared project (id, name, email) — their ids, sent as integers, are what assignee_id accepts on create_task/update_task. Optional: cursor, limit (1-200). |
list_projects | List the active projects of the connected user (the Inbox included) — their ids are what project_id accepts. Answers { results, next_cursor }; pass next_cursor as cursor for the next page. Optional: cursor, limit (1-200). Also a cheap way to check the connection works. |
list_sections | List the active sections, optionally of one project — their ids are what section_id accepts. Optional: project_id, cursor, limit (1-200). |
list_tasks | List active (not completed) tasks; every given filter narrows the list. Optional: project_id, section_id, parent_id (subtasks of a task), label (a label name), ids (comma-separated task ids), cursor, limit (1-200). Answers { results, next_cursor }. |
Write actions (7)
| Action | Description |
|---|---|
close_task | Complete a task, like ticking it in the app: a regular task and its subtasks move to history; a recurring task is rescheduled to its next occurrence. Arguments: task_id (string, required). |
create_comment | Add a comment to a task or a project. Arguments: content (string, required, Markdown, max 15000 chars); exactly one of task_id or project_id (string). |
create_project | Create a project. Arguments: name (string, required); description (string); parent_id (string, id of a parent project to create a sub-project); color (string, one of berry_red, red, orange, yellow, olive_green, lime_green, green, mint_green, teal, sky_blue, light_blue, blue, grape, violet, lavender, magenta, salmon, charcoal, grey, taupe); is_favorite (boolean); view_style (string: “list”, “board” or “calendar”). |
create_section | Create a section in a project. Arguments: name (string, required); project_id (string, required — from list_projects); description (string); order (integer, position in the project). |
create_task | Create a task (in the Inbox when no project_id). Arguments: content (string, required — the task title); description (string); project_id, section_id, parent_id (strings — ids from list_projects, list_sections, list_tasks); labels (array of label NAME strings, e.g. [“waiting”]); priority (integer 1-4, 4 = most urgent, shown as p1 in the app); ONE of due_string (string in natural language, e.g. “tomorrow at 10am”, “every monday”), due_date (string “YYYY-MM-DD”) or due_datetime (string RFC 3339, e.g. “2026-10-01T09:00:00Z”); due_lang (string, language of due_string, e.g. “fr”); deadline_date (string “YYYY-MM-DD”); duration (positive integer) together with duration_unit (“minute” or “day”); assignee_id (integer — a collaborator id from list_project_collaborators sent as a bare number, e.g. 1234567, not a string; shared projects only). |
reopen_task | Reopen a completed task (its completed parent tasks and sections are restored too). Arguments: task_id (string, required). |
update_task | Update a task; only the given fields change (moving it to another project or section is not supported). Arguments: task_id (string, required); content (string); description (string); labels (array of label NAME strings — replaces the whole list); priority (integer 1-4, 4 = most urgent); due_string (string, natural language, e.g. “next friday”; “no date” removes the due date), due_date (string “YYYY-MM-DD”) or due_datetime (string RFC 3339); due_lang (string); deadline_date (string “YYYY-MM-DD”); duration (positive integer) together with duration_unit (“minute” or “day”); assignee_id (integer — collaborator id from list_project_collaborators as a bare number, not a string). |