{"openapi":"3.1.0","info":{"title":"Todoist (BYOK) API","version":"0.1.0","description":"Todoist (BYOK) lets an AI assistant read your own Todoist data through the Todoist API with a key you supply (personal API token). Read-only: 11 tools (get_user, list_projects, get_project, list_tasks, filter_tasks, get_task, list_completed_tasks, list_sections, list_labels, list_comments, list_project_collaborators). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-todoist.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-todoist/docs"},"termsOfService":"https://connectorbay.com/byok-todoist/terms"},"servers":[{"url":"https://byok-todoist.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-todoist/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_user":{"post":{"operationId":"get_user","summary":"Show the Todoist account the token belongs to: name, email, premium status, karma, daily and weekly goals, completed tas","description":"Show the Todoist account the token belongs to: name, email, premium status, karma, daily and weekly goals, completed task counts. Use for \"Which Todoist account is my token connected to and what is my karma\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_projects":{"post":{"operationId":"list_projects","summary":"List your active Todoist projects with color, sharing, favorite flag, parent project and view style. Returns one page; u","description":"List your active Todoist projects with color, sharing, favorite flag, parent project and view style. Returns one page; use cursor for more. Use for \"What projects do I have in Todoist\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only projects of this workspace (numeric ID).","title":"Workspace Id"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 200).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_project":{"post":{"operationId":"get_project","summary":"Get one Todoist project by ID with its name, color, description, sharing and view style. Use for \"Show the details of my","description":"Get one Todoist project by ID with its name, color, description, sharing and view style. Use for \"Show the details of my Todoist project 6XGgm6PHrGgMpCFX\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"ID of the project, a string such as '6XGgm6PHrGgMpCFX' (from list_projects).","maxLength":200,"title":"Project Id","type":"string"}},"required":["project_id"],"title":"get_projectArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tasks":{"post":{"operationId":"list_tasks","summary":"List your active (not completed) Todoist tasks, optionally for one project, section, parent task or label. Returns one p","description":"List your active (not completed) Todoist tasks, optionally for one project, section, parent task or label. Returns one page; use cursor for more. Use for \"What active tasks are in my Todoist project 6XGgm6PHrGgMpCFX\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tasks of this project ID.","title":"Project Id"},"section_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tasks of this section ID.","title":"Section Id"},"parent_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only sub-tasks of this task ID.","title":"Parent Id"},"label":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tasks carrying this label name, for example 'next_action'.","title":"Label"},"ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated task IDs to fetch, for example '6XGgmFVcrG5RRjVr,6fFPHV272WWh3gpW'.","title":"Ids"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 200).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_tasksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/filter_tasks":{"post":{"operationId":"filter_tasks","summary":"List active tasks matching a Todoist filter query such as 'today | overdue', '#Work & p1' or '@errands'. Returns one pag","description":"List active tasks matching a Todoist filter query such as 'today | overdue', '#Work & p1' or '@errands'. Returns one page; use cursor for more. Use for \"Which of my Todoist tasks are due today or overdue\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Todoist filter expression, for example 'today | overdue' or '#Work & p1' (up to 1024 characters).","maxLength":1024,"title":"Query","type":"string"},"lang":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Language code the filter is written in if not English, for example 'de'.","title":"Lang"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 200).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Cursor"}},"required":["query"],"title":"filter_tasksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_task":{"post":{"operationId":"get_task","summary":"Get one Todoist task by ID with its content, description, due date, labels, priority and completion state. Use for \"Show","description":"Get one Todoist task by ID with its content, description, due date, labels, priority and completion state. Use for \"Show Todoist task 6XGgmFVcrG5RRjVr\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"task_id":{"description":"ID of the task, a string such as '6XGgmFVcrG5RRjVr'.","maxLength":200,"title":"Task Id","type":"string"}},"required":["task_id"],"title":"get_taskArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_completed_tasks":{"post":{"operationId":"list_completed_tasks","summary":"List tasks completed within a date range, optionally for one project, with completion time. The range must be given; use","description":"List tasks completed within a date range, optionally for one project, with completion time. The range must be given; use cursor for more. Use for \"What Todoist tasks did I complete last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"since":{"description":"Start of the completion range, inclusive, ISO 8601 such as 2026-10-01T00:00:00Z.","maxLength":200,"title":"Since","type":"string"},"until":{"description":"End of the completion range, exclusive, ISO 8601 such as 2026-10-08T00:00:00Z.","maxLength":200,"title":"Until","type":"string"},"project_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tasks of this project ID.","title":"Project Id"},"section_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tasks of this section ID.","title":"Section Id"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many tasks to return per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Cursor"}},"required":["since","until"],"title":"list_completed_tasksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_sections":{"post":{"operationId":"list_sections","summary":"List the sections inside your Todoist projects, for one project or for all. Returns one page; use cursor for more. Use f","description":"List the sections inside your Todoist projects, for one project or for all. Returns one page; use cursor for more. Use for \"What sections does my Todoist project 6XGgm6PHrGgMpCFX have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only sections of this project ID; omit for sections of all projects.","title":"Project Id"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 200).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_sectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_labels":{"post":{"operationId":"list_labels","summary":"List your personal Todoist labels with color, order and favorite flag. Returns one page; use cursor for more. Use for \"W","description":"List your personal Todoist labels with color, order and favorite flag. Returns one page; use cursor for more. Use for \"What labels do I use in Todoist\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 200).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_labelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_comments":{"post":{"operationId":"list_comments","summary":"List comments on a Todoist task or project (give task_id or project_id). Returns one page; use cursor for more. Use for ","description":"List comments on a Todoist task or project (give task_id or project_id). Returns one page; use cursor for more. Use for \"What comments are on Todoist task 6XGgmFVcrG5RRjVr\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"task_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"ID of the task whose comments to list.","title":"Task Id"},"project_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"ID of the project whose comments to list.","title":"Project Id"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 200).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_commentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_project_collaborators":{"post":{"operationId":"list_project_collaborators","summary":"List the people who share a Todoist project with you: their user ID, name and email. Returns one page; use cursor for mo","description":"List the people who share a Todoist project with you: their user ID, name and email. Returns one page; use cursor for more. Use for \"Who collaborates on my Todoist project 6XGgm6PHrGgMpCFX\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"ID of the project, a string such as '6XGgm6PHrGgMpCFX' (from list_projects).","maxLength":200,"title":"Project Id","type":"string"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 200).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor copied from next_cursor of the previous answer to get the next page; leave empty for the first page.","title":"Cursor"}},"required":["project_id"],"title":"list_project_collaboratorsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}