Todoist Tasks & Projects
Plain verbs for a Todoist to-do list: add tasks in natural language ("Call Ana tomorrow 3pm p1 #Sales"), pull today's or overdue work with Todoist filter queries, reschedule, move, complete or reopen tasks, and see what got done this week. Projects, sections and task comments are covered too.
Connect this API to an AI agent Browse all specs
What you can do with Todoist Tasks & Projects via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /api/v1/tasks |
listTasks | List open tasks, optionally in one project, section or label |
| POST | /api/v1/tasks |
createTask | Create a task with explicit project, due date and priority |
| GET | /api/v1/tasks/filter |
filterTasks | Find tasks with a Todoist filter, e.g. today | overdue |
| GET | /api/v1/tasks/{task_id} |
getTask | Get one task with its due date, priority and labels |
| POST | /api/v1/tasks/{task_id} |
updateTask | Change a task's text, due date, priority or labels |
| POST | /api/v1/tasks/quick |
quickAddTask | Add a task from one line of natural language |
| POST | /api/v1/tasks/{task_id}/close |
closeTask | Mark a task done (recurring tasks move to the next date) |
| POST | /api/v1/tasks/{task_id}/reopen |
reopenTask | Reopen a completed task |
| POST | /api/v1/tasks/{task_id}/move |
moveTask | Move a task to another project, section or parent task |
| GET | /api/v1/tasks/completed/by_completion_date |
listCompletedTasks | List tasks completed in a date range |
| GET | /api/v1/projects |
listProjects | List your active projects |
| POST | /api/v1/projects |
createProject | Create a project |
| GET | /api/v1/projects/{project_id} |
getProject | Get one project's name, color and view style |
| GET | /api/v1/sections |
listSections | List the sections in a project |
| GET | /api/v1/comments |
listComments | List the comments on a task or project |
| POST | /api/v1/comments |
addComment | Add a comment to a task or project |
Authentication
todoist_token
Bearer token — sent as Authorization: Bearer <token>
Todoist personal API token (or an OAuth access token), sent as Authorization: Bearer <token>.
How to get a credential
- Sign in to Todoist on the web.
- Open Settings > Integrations > Developer.
- Copy the API token. It acts as your Todoist user, with full access to your tasks and projects.
- Teams building a shared app can instead create an app in the Todoist App Management Console and use OAuth with the scopes below.
Permissions used
| OAuth scope | Operations |
|---|---|
data:read |
listTasks, filterTasks, getTask, listCompletedTasks, listProjects, getProject, listSections, listComments |
data:read_write |
quickAddTask, createTask, updateTask, closeTask, reopenTask, moveTask, createProject, addComment (and everything above) |
A personal API token already has all of these.
Common errors
| Status | Meaning | Fix |
|---|---|---|
| 401 | Token missing or reset | Copy the token again from Settings > Integrations > Developer. |
| 403 | No access to that project, or the OAuth token lacks data:read_write |
Use a project you are a member of, or re-authorize with the write scope. |
| 400 | Bad argument | Check ids, the filter query syntax and date fields (due_date YYYY-MM-DD, due_datetime RFC 3339). |
| 429 | Rate limit | Limits are per user; wait a little and retry with fewer calls. |
Store the token as a VX Agents credential (Bearer token).
Usage guide
Setup
- Copy your Todoist API token (Settings > Integrations > Developer) into a VX Agents Bearer credential. It acts as you, with access to all your projects.
- Optional: pin
project_idonlistTasks/createTaskto the project the agent should work in (ids fromlistProjects). Without it, new tasks land in the Inbox.
Plan the day
filterTaskswith a Todoist filterquery, e.g.today | overdue,#Work & p1,@waiting,assigned to: me,7 days. UselistTasks(byproject_id,section_id,label) for a plain list. Both page withcursor(limitup to 200).getTaskfor one task's description,due,priority,labelsanddeadline.- To add a task, prefer
quickAddTaskwith one line of text:Send invoice to Ana tomorrow 9am #Billing @finance p2. The response shows how Todoist parsed it. UsecreateTaskwhen you have structured fields (content,project_id,section_id,due_stringordue_date,priority,labels,deadline_date). - To reschedule or edit,
updateTaskwith only the changed fields (e.g.due_string: "next monday"). To file it elsewhere,moveTaskwith exactly one ofproject_id,section_idorparent_id. closeTaskcompletes a task (a recurring task jumps to its next date instead);reopenTaskundoes it.- Weekly review:
listCompletedTaskswithsinceanduntil(ISO 8601, at most 3 months apart), optionally perproject_id. listProjects,getProject,createProjectandlistSections(byproject_id) organise the structure;listComments/addComment(withtask_idorproject_id) hold notes and updates.
Good to know
- Ids are strings. Times are UTC ISO 8601;
due_stringaccepts natural language in the user's language (due_lang). - Shared projects: tasks you close, move or comment on are visible to collaborators, and comments can notify people (
uids_to_notify). Confirm before changing tasks other people own, closing tasks in shared projects, or creating projects. - Deleting tasks, projects or comments is not part of this spec.
- A 429 response means the per-user rate limit was hit: slow down and retry.
Source: Todoist API v1 reference (https://developer.todoist.com/api/v1/), checked 2026-10-20.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Todoist Tasks & Projects” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.