Todoist

Revoke the access tokens obtained via OAuth via DELETE /api/v1/access_tokens

Delete a comment by ID via DELETE /api/v1/comments/{comment_id}

Disable the current email to a Todoist object via DELETE /api/v1/emails

Delete a folder. Projects in the folder will be moved out of it. via DELETE /api/v1/folders/{folder_id}

Deletes a personal label. All instances of the label will be removed from tasks via DELETE /api/v1/labels/{label_id}

Delete a location reminder by ID. via DELETE /api/v1/location_reminders/{reminder_id}

Deletes a project and all of its sections and tasks. via DELETE /api/v1/projects/{project_id}

Delete a reminder by ID. via DELETE /api/v1/reminders/{reminder_id}

Delete the section and all of its tasks via DELETE /api/v1/sections/{section_id}

Delete a task and all of its subtasks. Returns `NOT_FOUND` when the task does not exist and `FORBIDDEN` when the authenticated user cannot modify the task. via DELETE /api/v1/tasks/{task_id}

Delete an uploaded file. The file must belong to the authenticated user. Returns `FILE_NOT_FOUND` when the upload cannot be found. via DELETE /api/v1/uploads

Deletes a workspace. via DELETE /api/v1/workspaces/{workspace_id}

Removes a user from a workspace. via DELETE /api/v1/workspaces/{workspace_id}/users/{user_id}

Get activity logs. Returns a paginated list of activity events for the user. Events can be filtered by object type (project, item, note, section), event type, and other criteria. Uses cursor-based pagination for efficient navigation through results. via GET /api/v1/activities

Todoist creates a backup archive of users' data on a daily basis. Backup archives can also be accessed from the web app (Todoist Settings -> Backups). This endpoint accepts the `backups:read` scope, the `data:read_write` scope, or a personal API token. The `backups:read` scope bypasses MFA and only grants access to `GET /api/v1/backups`. When using `data:read_write` or a personal API token for an account with MFA enabled, the MFA token is required. via GET /api/v1/backups

Download a backup archive. This endpoint requires the `data:read_write` scope. The `backups:read` scope only grants access to `GET /api/v1/backups`. Validates that the requested backup belongs to the authenticated user and redirects to a signed CloudFront URL that expires after one minute. via GET /api/v1/backups/download

Get all comments for a given task or project. Exactly one of `task_id` or `project_id` arguments is required. Providing neither or both will return an error. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/comments

Returns a single comment by ID via GET /api/v1/comments/{comment_id}

Get all folders for a workspace. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/folders

Return the folder for the given folder ID. via GET /api/v1/folders/{folder_id}

Translates IDs from v1 to v2 or vice versa. IDs are not unique across object types, hence the need to specify the object type. When V1 ids are provided, the function will return the corresponding V2 ids, if they exist, and vice versa. When no objects are found, an empty list is returned. via GET /api/v1/id_mappings/{obj_name}/{obj_ids}

Get all user labels. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/labels

Return a personal label by ID. Returns `NOT_FOUND` when the label does not exist or the ID is invalid. via GET /api/v1/labels/{label_id}

Search user labels by name. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/labels/search

Returns a set of unique strings containing [shared labels](https://www.todoist.com/help/articles/introduction-to-labels-dSo2eE#h_01HE1NNWMV8MCXNVF10GT13ZEX) from active tasks. via GET /api/v1/labels/shared

Get all active location reminders. Optionally filter by `task_id` to return only location reminders for a specific task. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/location_reminders

Return a single location reminder by ID. via GET /api/v1/location_reminders/{reminder_id}

Get all active user projects, optionally filtered by folder or workspace. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/projects

Get the user's archived projects. via GET /api/v1/projects/archived

Returns a project object related to the given ID via GET /api/v1/projects/{project_id}

Get all collaborators for a given project. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/projects/{project_id}/collaborators

Returns a list of all the available roles and the associated actions they can perform in a project. via GET /api/v1/projects/permissions

Search active user projects by name. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/projects/search

Get all active reminders. Optionally filter by `task_id` to return only reminders for a specific task. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/reminders

Return a single reminder by ID. via GET /api/v1/reminders/{reminder_id}

Get all active sections for the user, optionally filtered by project. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/sections

Return the section for the given section ID via GET /api/v1/sections/{section_id}

Search active sections by name, optionally filtered by project. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/sections/search

Get all active tasks for the user. All provided parameters are used to narrow down the list of tasks. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/tasks

Returns a single active (non-completed) task by ID via GET /api/v1/tasks/{task_id}

Retrieves a list of completed tasks strictly limited by the specified completion date range (up to 3 months). It can retrieve completed items: - From all the projects the user has joined in a workspace - From all the projects of the user - That match many [supported filters](https://todoist.com/help/articles/introduction-to-filters-V98wIH) By default, the response is limited to a page containing a maximum of 50 items (configurable using `limit`). Subsequent pages of results can be fetched by using the `next_cursor` value from the response as the `cursor` value for the next request. via GET /api/v1/tasks/completed/by_completion_date

Retrieves a list of completed items strictly limited by the specified due date range (up to 6 weeks). It can retrieve completed items: - From within a project, section, or parent item - From all the projects the user has joined in a workspace - From all the projects of the user - That match many [supported filters](https://todoist.com/help/articles/introduction-to-filters-V98wIH) By default, the response is limited to a page containing a maximum of 50 items (configurable using `limit`). Subsequent pages of results can be fetched by using the `next_cursor` value from the response as the `cursor` value for the next request. via GET /api/v1/tasks/completed/by_due_date

Get comprehensive productivity statistics for the authenticated user. This endpoint is used to display information about the [Karma system](https://www.todoist.com/help/articles/introduction-to-karma-OgWkWy). Returns detailed completion statistics including: - Daily completion counts with per-project breakdowns for the last 7 days - Weekly completion counts with per-project breakdowns for the last 4 weeks - Total completed task count - Karma score, trend, graph data, and update history - Goal settings (daily/weekly goals, ignore days, vacation mode) - Streak information (current, last, and maximum daily and weekly streaks) - Project color mappings for visualization via GET /api/v1/tasks/completed/stats

Get all tasks matching the filter. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/tasks/filter

Get a template for a project as a CSV file via GET /api/v1/templates/file

Get a template for a project as a shareable URL. The URL can then be passed to `https://todoist.com/api/v1/import/project_from_url?t_url=<url>` to make a shareable template. via GET /api/v1/templates/url

List the caller's usage-billing ledger entries, newest first. Use `types` to filter the entries to list. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination. via GET /api/v1/usage_billing/history

Read the caller's usage-billing credit state for a product. via GET /api/v1/usage_billing/state

Total the caller's settled usage over a window. `/history` is a ledger with one row per movement, so a total spanning more than one page cannot come from it. This answers the one question the UI asks of the whole ledger at once: how many runs, and what they cost. Only settled usage counts. `void`, `expiry` and `chargeback` draw the balance down as well, but they reverse a grant rather than report usage. via GET /api/v1/usage_billing/usage_summary

Get information about the currently authenticated user. This is the OIDC userinfo endpoint. OAuth tokens of any product audience are accepted as long as they carry the `user:read` scope (implied by `data:read`). via GET /api/v1/user

Returns all workspaces where the user is a member. via GET /api/v1/workspaces

Returns a workspace by ID. via GET /api/v1/workspaces/{workspace_id}

Returns all active workspace projects, including those visible but not joined by the user. _For guests, returns all joined workspace projects only._ via GET /api/v1/workspaces/{workspace_id}/projects/active

Return archived projects in a workspace. Workspace guests cannot list archived projects and receive a `FORBIDDEN` error. Results are paginated by `cursor` and `limit`. via GET /api/v1/workspaces/{workspace_id}/projects/archived

Return a list of user emails who have a pending invitation to a workspace. The list is not paginated. All workspace members can access this list. via GET /api/v1/workspaces/invitations

Return a list containing details of all pending invitation to a workspace. This list is not paginated. All workspace members can access this list. via GET /api/v1/workspaces/invitations/all

Lists details of the workspace's current plan and usage via GET /api/v1/workspaces/plan_details

Returns all workspace_users for a given workspace if workspace_id is provided. Otherwise, returns all workspace_users for all workspaces that the requesting user is part of. _Not accessible by guests._ via GET /api/v1/workspaces/users

Tokens obtained via the old email/password authentication method can be migrated to the new OAuth access token. Migrating your users' personal tokens will allow users to see your app in their Todoist Settings page and give them the ability to manage their app authorization. A successful response has `200 OK` status and `application/json` Content-Type. via POST /api/v1/access_tokens/migrate_personal_token

Creates a new comment on a project or task and returns it. Exactly one of `task_id` or `project_id` arguments is required. Providing neither or both will return an error. via POST /api/v1/comments

Update a comment by ID and returns its content via POST /api/v1/comments/{comment_id}

Create a new folder in the given workspace. via POST /api/v1/folders

Update an existing folder. via POST /api/v1/folders/{folder_id}

Create a personal label. Premium limits apply to personal label creation. Free users who exceed the plan limit receive a premium-only error. via POST /api/v1/labels

Update a personal label. At least one mutable field must be provided. Passing `null` for an optional field keeps the existing value unchanged. via POST /api/v1/labels/{label_id}

Remove the given shared label from all active tasks via POST /api/v1/labels/shared/remove

Rename the given shared label from all active tasks via POST /api/v1/labels/shared/rename

Create a new location reminder for a task. via POST /api/v1/location_reminders

Update an existing location reminder. via POST /api/v1/location_reminders/{reminder_id}

Start a hosted cancellation flow and return the redirect URL. via POST /api/v1/payments/cancel_plan_with_redirect_to_stripe

Return the current user's subscription state. via POST /api/v1/payments/get_subscription_info

Reactivate a previously canceled subscription. Returns the fresh `SubscriptionInfo` after reactivation so callers can avoid a follow-up fetch. Raises `NO_CANCELABLE_SUBSCRIPTION` if there is no active subscription to reactivate. via POST /api/v1/payments/reactivate_plan

Creates a new project and returns it via POST /api/v1/projects

Updates a project and returns it. via POST /api/v1/projects/{project_id}

Marks a project as archived. For personal projects, this will archive it just for the initiating user (leaving it visible to any other collaborators). For workspace projects, this will archive it for all workspace users, removing it from view. via POST /api/v1/projects/{project_id}/archive

_Only used for workspaces_ This endpoint is used to join a workspace project by a workspace_user and is only usable by the workspace user. via POST /api/v1/projects/{project_id}/join

Marks a previously archived project as active again. For personal projects, this will make the project visible again for the initiating user. For workspace projects, this will make the project visible again for all applicable workspace users. via POST /api/v1/projects/{project_id}/unarchive

Create a new reminder for a task. For **relative** reminders, provide `minute_offset` (minutes before the task's due time). For **absolute** reminders, provide a `due` dictionary with a specific date/time. Supported `due` keys are `date` or `string`, with optional `lang`, `timezone`, and `is_recurring`. via POST /api/v1/reminders

Update an existing reminder. via POST /api/v1/reminders/{reminder_id}

Revoke an access token according to RFC 7009 OAuth Token Revocation. This endpoint accepts form-encoded data and follows the OAuth 2.0 Token Revocation specification. The client must authenticate using HTTP Basic authentication with their client credentials. Authentication is performed via the Authorization header with the format: Authorization: Basic base64(client_id:client_secret) via POST /api/v1/revoke

Create a new section via POST /api/v1/sections

Update a section. via POST /api/v1/sections/{section_id}

Marks a section as archived. via POST /api/v1/sections/{section_id}/archive

Marks a section as active again. via POST /api/v1/sections/{section_id}/unarchive

Create a new task. via POST /api/v1/tasks

Updates an existing task. via POST /api/v1/tasks/{task_id}

Closes a task. The command performs in the same way as our official clients: Regular tasks are marked complete and moved to history, along with their subtasks. Tasks with [recurring due dates](https://todoist.com/help/articles/introduction-to-recurring-dates-YUYVJJAV) will be scheduled to their next occurrence. via POST /api/v1/tasks/{task_id}/close

Moves task to another project, section or parent. via POST /api/v1/tasks/{task_id}/move

Reopens a task. Any ancestor tasks or sections will also be marked as uncomplete and restored from history. The reinstated tasks and sections will appear at the end of the list within their parent, after any previously active tasks. via POST /api/v1/tasks/{task_id}/reopen

Add a new task using Quick Add with natural language processing. Quick Add allows creating tasks with rich metadata using natural language text. This endpoint uses the same parsing engine as Todoist's official clients, supporting dates, projects, labels, priorities, assignees, and more in a single text string. ## Basic Syntax Overview - **Due dates**: Natural language like `today`, `tomorrow at 5pm`, `next Monday` - **Projects**: `#ProjectName` (use `#My\\ Project` for names with spaces) - **Sections**: `/SectionName` (requires a project to be specified) - **Labels**: `@labelname` (multiple labels supported) - **Priority**: `p1` to `p4`, `P1` to `P4`, or `!!1` to `!!4` - **Assignees**: `+Name` (requires a project to be specified) - **Deadlines**: `{date expression}` (e.g., `{tomorrow}`, `{in 3 days}`) - **Reminders**: `!30m` (30 min before), `!1h` (1 hour before), `!0mb` (at due time), `!14:00` (absolute time), `!30 min before` (verbose, English only) - **Descriptions**: ` // description text` (must be at the end) ## Examples - `"Buy milk today at 5pm #Shopping @groceries p1"` - `"Team meeting next Monday at 10am #Work +JohnDoe !30m"` - `"Review PR {Friday} // Check the new authentication flow"` - `"Submit report tomorrow #Work /Urgent @important // Include Q3 metrics"` ## Important Notes - Natural language date parsing supports multiple languages based on account settings - If parsing fails for any element, the task is still created (with unparsed text remaining in the content) - Use the `meta` parameter to see detailed parsing results for debugging For comprehensive documentation including all supported date formats, language support, and advanced syntax, see the [Quick Add help article](https://www.todoist.com/help/articles/use-task-quick-add-in-todoist-va4Lhpzz). via POST /api/v1/tasks/quick

Import a saved template into an existing project. The target project must exist and must not be frozen. The response includes the imported objects so clients can update local state immediately. via POST /api/v1/templates/import_into_project_from_template_id

In V1, create a hosted Stripe Checkout session to top up the authenticated user's personal Automations wallet. The user must have a personal Stripe customer and an active personal Todoist Pro subscription. A Business or workspace subscription alone does not qualify. A Business member who also has personal Todoist Pro tops up their personal wallet. If the personal Stripe customer or personal Todoist Pro prerequisite is not met, the endpoint returns HTTP 400 with error tag `USAGE_BILLING_TOP_UP_UNAVAILABLE` and error code `605`. via POST /api/v1/usage_billing/top_up

Creates a new workspace and returns it. via POST /api/v1/workspaces

Updates an existing workspace and returns it. via POST /api/v1/workspaces/{workspace_id}

Updates a workspace user's role. via POST /api/v1/workspaces/{workspace_id}/users/{user_id}

Invites users to a workspace by email. via POST /api/v1/workspaces/{workspace_id}/users/invite

Deletes a workspace invitation. Only admins can delete invitations. via POST /api/v1/workspaces/invitations/delete

Join a workspace via link or via workspace ID, if the user can auto-join the workspace by domain. ## Joining by Domain This is possible if: - The user is verified - The user has a user e-mail belonging to a domain that is set as a domain name for a workspace - That workspace has the auto-join by domain feature enabled via POST /api/v1/workspaces/join

Get or create an email to a Todoist object, currently only projects and tasks are supported. via PUT /api/v1/emails

Update a notification delivery preference. The API accepts the legacy `dont_notify` flag and stores the inverse as the user's delivery preference for the requested notification type and channel. via PUT /api/v1/notification_setting

Accept a workspace invitation. Usable by authenticated users only. via PUT /api/v1/workspaces/invitations/{invite_code}/accept

Reject a workspace invitation. Usable by authenticated users only. via PUT /api/v1/workspaces/invitations/{invite_code}/reject