Skip to content
Changelog

Report a bug

Todoist integration: operations for AI agents

Todoist connects to Type.com as an integration. This page lists the 200 operations documented for Claude and Codex in Type.com: 52 read, 107 write, 41 destructive.

About Todoist

Todoist API v1 REST routes and documented Sync capabilities, subject to account and Type access boundaries.

Categories: Productivity & Project Management

How to connect Todoist to Type.com

Connect
Configure provider-specific API target and bearer authentication setup.
Access
Organization connection: one shared account for the workspace.

To add the connection, follow the steps in Space connections.

Documented operations

200 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.

200 operations listed.

REST

  • Read

    All 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.

    GET /api/v1/workspaces/invitations/all

  • Read

    Archived Projects

    Return archived projects in a workspace. Workspace guests cannot list archived projects and receive a `FORBIDDEN` error. Results are paginated by `cursor` and `limit`.

    GET /api/v1/workspaces/{workspace_id}/projects/archived

  • Read

    Active Projects

    Returns all active workspace projects, including those visible but not joined by the user. _For guests, returns all joined workspace projects only._

    GET /api/v1/workspaces/{workspace_id}/projects/active

  • Read

    Tasks Completed By Completion Date

    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.

    GET /api/v1/tasks/completed/by_completion_date

  • Read

    Tasks Completed By Due 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.

    GET /api/v1/tasks/completed/by_due_date

  • Read

    Get Productivity Stats

    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

    GET /api/v1/tasks/completed/stats

  • Read

    Usage Billing Usage Summary

    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. A user who has never topped up reports zero for every field. `group_by=automation` adds `groups`: the same total, one entry per automation. Older usage without an automation id groups by its label.

    GET /api/v1/usage_billing/usage_summary

  • Read

    Usage Billing History

    List the caller's usage-billing ledger entries, newest first. Use `types` to filter the entries to list. A user who has never topped up gets an empty page. This is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.

    GET /api/v1/usage_billing/history

  • Read

    Usage Billing State

    Read the caller's usage-billing credit state for a product. A user who has never topped up reads as an empty wallet: `available_units` and `available_amount` are 0, `is_settled_low_balance` is true, and `usage_block_reason` is `insufficient_credit`. There is no separate "no account" answer, because both states send the user to the same top-up screen.

    GET /api/v1/usage_billing/state

  • Read

    Plan Details

    Lists details of the workspace's current plan and usage

    GET /api/v1/workspaces/plan_details

  • Read

    Invitations

    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.

    GET /api/v1/workspaces/invitations

  • Read

    Get Workspaces Users

    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._

    GET /api/v1/workspaces/users

  • Read

    Categories

    List curated template categories. Authentication is not required.

    GET /api/v1/templates/categories

  • Read

    Preview Project

    Preview a project's template graph. Requires `data:read` and project export permission. Set `resolve_dates=false` to preserve raw date strings for a template editor.

    GET /api/v1/templates/preview

  • Read

    Export As File

    Download a project as UTF-8 CSV. Requires `data:read` and project export permission. On v1.6+, dated tasks also get `DATE_TYPE` and `DATE_TIME` columns, and `TIMEZONE` holds the task's own timezone only for `fixed_datetime` dues. Older versions write the exporting user's timezone on every row. With `use_relative_dates=false`, non-recurring dues are ISO 8601 values.

    GET /api/v1/templates/file

  • Read

    Export As Url

    Publish a project as a shareable template URL. Requires `data:read_write` and project export permission. This stores a publicly accessible CSV artifact. No expiry is set on this URL. Pass it to `https://todoist.com/api/v1/import/project_from_url?t_url=` to share the template. On v1.6+, dated tasks also get `DATE_TYPE` and `DATE_TIME` columns, and `TIMEZONE` holds the task's own timezone only for `fixed_datetime` dues. Older versions write the exporting user's timezone on every row. With `use_relative_dates=false`, non-recurring dues are ISO 8601 values.

    GET /api/v1/templates/url

  • Read

    Preview Template

    Preview a project or setup template without importing it. Curated templates support anonymous access and use a valid `data:read` actor when available. Any `UT_` ID requires `data:read` and the saved template's existing visibility permissions. Raw date strings are supported only for project templates.

    GET /api/v1/templates/{template_id}/preview

  • Read

    Get Subscription Info

    Return the current user's subscription state.

    POST /api/v1/payments/get_subscription_info

  • Read

    Permissions

    Returns a list of all the available roles and the associated actions they can perform in a project.

    GET /api/v1/projects/permissions

  • Read

    Get Archived

    Get the user's archived projects.

    GET /api/v1/projects/archived

  • Read

    Search Projects

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

    GET /api/v1/projects/search

  • Read

    Search Sections

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

    GET /api/v1/sections/search

  • Read

    Get Project Collaborators

    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.

    GET /api/v1/projects/{project_id}/collaborators

  • Read

    Download Backup

    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.

    GET /api/v1/backups/download

  • Read

    Search Labels

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

    GET /api/v1/labels/search

  • Read

    Shared Labels

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

    GET /api/v1/labels/shared

  • Read

    Get Tasks By Filter

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

    GET /api/v1/tasks/filter

  • Read

    Get Location Reminder

    Return a single location reminder by ID.

    GET /api/v1/location_reminders/{reminder_id}

  • Read

    Get Location Reminders

    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.

    GET /api/v1/location_reminders

  • Read

    Id Mappings

    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.

    GET /api/v1/id_mappings/{obj_name}/{obj_ids}

  • Read

    Get Workspace

    Returns a workspace by ID.

    GET /api/v1/workspaces/{workspace_id}

  • Read

    Get Workspaces

    Returns all workspaces where the user is a member.

    GET /api/v1/workspaces

  • Read

    Get Activity Logs

    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.

    GET /api/v1/activities

  • Read

    Discover Template

    Get one template. A `UT_` ID requires `data:read`; invisible or missing IDs return 404.

    GET /api/v1/templates/{template_id}

  • Read

    Get Reminder

    Return a single reminder by ID.

    GET /api/v1/reminders/{reminder_id}

  • Read

    Discover Templates

    Discover templates or look up a bounded batch of IDs. Curated templates are anonymous. Personal/workspace sources and any `UT_` ID require `data:read`. Pages prioritize personal, workspace, then curated templates, and rank each page by the query. Keep all filters when continuing.

    GET /api/v1/templates

  • Read

    Get Reminders

    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.

    GET /api/v1/reminders

  • Read

    Get Project

    Returns a project object related to the given ID

    GET /api/v1/projects/{project_id}

  • Read

    Get Section

    Return the section for the given section ID

    GET /api/v1/sections/{section_id}

  • Read

    Get Comment

    Returns a single comment by ID

    GET /api/v1/comments/{comment_id}

  • Read

    Get Projects

    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.

    GET /api/v1/projects

  • Read

    Get Sections

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

    GET /api/v1/sections

  • Read

    Get Comments

    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.

    GET /api/v1/comments

  • Read

    Get Folder

    Return the folder for the given folder ID.

    GET /api/v1/folders/{folder_id}

  • Read

    Get Backups

    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.

    GET /api/v1/backups

  • Read

    Get Folders

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

    GET /api/v1/folders

  • Read

    Get Label

    Return a personal label by ID. Returns `NOT_FOUND` when the label does not exist or the ID is invalid.

    GET /api/v1/labels/{label_id}

  • Read

    Get Labels

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

    GET /api/v1/labels

  • Read

    Get Task

    Returns a single active (non-completed) task by ID

    GET /api/v1/tasks/{task_id}

  • Read

    Get Tasks

    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.

    GET /api/v1/tasks

  • Read

    User Info

    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`).

    GET /api/v1/user

  • Write

    Delete Invitation

    Deletes a workspace invitation. Only admins can delete invitations.

    POST /api/v1/workspaces/invitations/delete

  • Write

    Accept Invitation

    Accept a workspace invitation. Usable by authenticated users only.

    PUT /api/v1/workspaces/invitations/{invite_code}/accept

  • Write

    Reject Invitation

    Reject a workspace invitation. Usable by authenticated users only.

    PUT /api/v1/workspaces/invitations/{invite_code}/reject

  • Write

    Invite Workspace Users

    Invites users to a workspace by email.

    POST /api/v1/workspaces/{workspace_id}/users/invite

  • Write

    Preview User Template

    Stages and previews a project CSV sent as multipart `file` or a raw CSV body. Requires `data:read_write` because the upload is stored. The response includes the filename for a subsequent import and the graph for editing; project names come from the filename or the `X-File-Name` header for raw bodies.

    POST /api/v1/templates/user/preview

  • Write

    Import User Template From File

    Creates a personal template from CSV or a content graph. Requires `data:read_write`. With `content` unset, the request's file (either a multipart `file` or a previously-uploaded `uploaded_file_name`, or a raw CSV body) becomes the template's content. Send content graphs in an `application/json` body. With `content` set, an uploaded file is ignored and `uploaded_file_name` must be unset. Import creates a personal template; update it to associate a workspace.

    POST /api/v1/templates/user/import

  • Write

    Remove Comment Reaction

    Removes the authenticated user's reaction from a task or project comment. Removing a reaction the user has not added succeeds without changing the reactions. Other users' reactions are not affected.

    POST /api/v1/comments/{comment_id}/reactions/remove

  • Write

    Shared Labels Rename

    Rename the given shared label from all active tasks

    POST /api/v1/labels/shared/rename

  • Write

    Migrate Personal Token

    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.

    POST /api/v1/access_tokens/migrate_personal_token

  • Write

    Usage Billing Top Up

    In V1, create a hosted Stripe Checkout session to top up the authenticated user's personal Automations wallet. A wallet whose usage is billed on the user's Pro subscription needs a personal Stripe customer and an active personal Todoist Pro subscription. A wallet on its own compute subscription needs Pro of any kind, including Pro gifted by a Business workspace, but not Pro paid only through an app store. A user with no Stripe customer gets one before Checkout opens, unless they only have a legacy one. A refused top-up returns HTTP 400 with one of these error tags: - `USAGE_BILLING_PLAN_REQUIRED` (code `615`): the user doesn't have Pro. - `USAGE_BILLING_CURRENCY_MISMATCH` (code `616`): the currency isn't the one the user pays in, including an unsupported one. - `USAGE_BILLING_TOP_UP_BELOW_MINIMUM` (code `617`): the amount is below the minimum. - `USAGE_BILLING_TOP_UP_UNAVAILABLE` (code `605`): any other unmet prerequisite, such as a user with only a legacy Stripe customer.

    POST /api/v1/usage_billing/top_up

  • Write

    Join

    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

    POST /api/v1/workspaces/join

  • Write

    Remove Workspace User

    Removes a user from a workspace.

    DELETE /api/v1/workspaces/{workspace_id}/users/{user_id}

  • Write

    Update Workspace User

    Updates a workspace user's role.

    POST /api/v1/workspaces/{workspace_id}/users/{user_id}

  • Write

    Import Into Project From Template Id

    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.

    POST /api/v1/templates/import_into_project_from_template_id

  • Write

    Import Into Project From File

    A template can be imported in an existing project, or in a newly created one. Upload a file suitable to be passed as a template to be imported into a project.

    POST /api/v1/templates/import_into_project_from_file

  • Write

    Create Project From File

    A template can be imported in an existing project, or in a newly created one. Upload a file suitable to be passed as a template to be imported into a project.

    POST /api/v1/templates/create_project_from_file

  • Write

    Generate Description

    Generates an AI description from a project or saved template. Supply `project_id` or `template_id`. Requires `data:read_write`, access to the source and the AI template descriptions feature.

    POST /api/v1/templates/generate_description

  • Write

    Create User Template

    Creates a template from a project or a content graph. Requires `data:read_write`. `project_id` is always required. With `content` unset, its content is exported as-is. With `content` set, project_id is only used to check access, set the template's source project, and (with `for_workspace`) derive the workspace to associate the template with - the content graph is used for the template's content instead of an export of the project. If workspace membership repeatedly changes during saving, retry the same request after the 409 `WORKSPACE_TEMPLATE_MEMBERSHIP_CHANGED` response.

    POST /api/v1/templates/user

  • Write

    Use Template

    Create a project or a complete setup from a template. Requires `data:read_write`. Saved workspace templates can only be used in their associated workspace. Returns the created sync-style graph, with tasks in `items` and comments in `notes`.

    POST /api/v1/templates/{template_id}/use

  • Write

    Cancel Plan With Redirect To Stripe

    Start a hosted cancellation flow and return the redirect URL.

    POST /api/v1/payments/cancel_plan_with_redirect_to_stripe

  • Write

    Reactivate Plan

    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.

    POST /api/v1/payments/reactivate_plan

  • Write

    Create Project From Template

    Create a project from a template, returning only its ID and success status. Requires `data:read_write`. Setup templates are not supported. Workspace templates can only be imported into their associated workspace. Calendar defaults are applied to the project according to the destination plan.

    POST /api/v1/projects/from_template

  • Write

    Import Project Template

    Import a project template, returning tasks, comments, reminders and applied defaults. Requires `data:read_write` and permission to apply templates to the project. The project must be active and unfrozen. Workspace templates can only be imported into their associated workspace. Setup templates are rejected; use `/templates/{template_id}/use`. The `projects` array is empty.

    POST /api/v1/projects/{project_id}/import_template

  • Write

    Unarchive Project

    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.

    POST /api/v1/projects/{project_id}/unarchive

  • Write

    Unarchive Section

    Marks a section as active again.

    POST /api/v1/sections/{section_id}/unarchive

  • Write

    Add Comment Reaction

    Adds the authenticated user's reaction to a task or project comment and returns the updated comment. Adding a reaction the user has already added leaves the reactions unchanged. Returns an error if the comment's stored reactions would exceed 65,535 bytes.

    POST /api/v1/comments/{comment_id}/reactions

  • Write

    Archive Project

    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.

    POST /api/v1/projects/{project_id}/archive

  • Write

    Archive Section

    Marks a section as archived.

    POST /api/v1/sections/{section_id}/archive

  • Write

    Join

    _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.

    POST /api/v1/projects/{project_id}/join

  • Write

    Quick Add

    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).

    POST /api/v1/tasks/quick

  • Write

    Reopen Task

    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.

    POST /api/v1/tasks/{task_id}/reopen

  • Write

    Close Task

    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.

    POST /api/v1/tasks/{task_id}/close

  • Write

    Move Task

    Moves task to another project, section or parent.

    POST /api/v1/tasks/{task_id}/move

  • Write

    Update Notification Setting

    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.

    PUT /api/v1/notification_setting

  • Write

    Update Location Reminder

    Update an existing location reminder.

    POST /api/v1/location_reminders/{reminder_id}

  • Write

    Create Location Reminder

    Create a new location reminder for a task.

    POST /api/v1/location_reminders

  • Write

    Update Workspace

    Updates an existing workspace and returns it.

    POST /api/v1/workspaces/{workspace_id}

  • Write

    Create Workspace

    Creates a new workspace and returns it.

    POST /api/v1/workspaces

  • Write

    Update Reminder

    Update an existing reminder.

    POST /api/v1/reminders/{reminder_id}

  • Write

    Create Reminder

    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`.

    POST /api/v1/reminders

  • Write

    Update Project

    Updates a project and returns it.

    POST /api/v1/projects/{project_id}

  • Write

    Update Comment

    Update a comment by ID and returns its content

    POST /api/v1/comments/{comment_id}

  • Write

    Create Project

    Creates a new project and returns it

    POST /api/v1/projects

  • Write

    Create Section

    Create a new section

    POST /api/v1/sections

  • Write

    Create Comment

    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.

    POST /api/v1/comments

  • Write

    Update Folder

    Update an existing folder.

    POST /api/v1/folders/{folder_id}

  • Write

    Upload File

    Upload a file to Todoist. This endpoint accepts file uploads via two methods: 1. **Multipart form-data** (recommended): - Send the file as a form field with the actual file content - Optionally include `project_id` as another form field - The filename will be extracted from the Content-Disposition header 2. **Raw binary stream**: - Send the file content directly in the request body - Set `Content-Type` header to the file's MIME type - Set `X-File-Name` header with the desired filename - Optionally include `project_id` as a query parameter The optional `project_id` parameter can be used to apply workspace-specific upload limits when uploading to a workspace project.

    POST /api/v1/uploads

  • Write

    Create Folder

    Create a new folder in the given workspace.

    POST /api/v1/folders

  • Write

    Update Label

    Update a personal label. At least one mutable field must be provided. Passing `null` for an optional field keeps the existing value unchanged.

    POST /api/v1/labels/{label_id}

  • Write

    Email Get Or Create

    Get or create an email to a Todoist object, currently only projects and tasks are supported.

    PUT /api/v1/emails

  • Write

    Create Label

    Create a personal label. Premium limits apply to personal label creation. Free users who exceed the plan limit receive a premium-only error.

    POST /api/v1/labels

  • Write

    Create Task

    Create a new task.

    POST /api/v1/tasks

  • Destructive

    Shared Labels Remove

    Remove the given shared label from all active tasks

    POST /api/v1/labels/shared/remove

  • Destructive

    Update Logo

    Upload an image to be used as the workspace logo. Similar to a user’s avatar. If `delete` is set to true, it removes the logo completely and does not return any `logo_*` attribute.

    POST /api/v1/workspaces/logo

  • Destructive

    Update User Template

    Updates a template's metadata and, optionally, its content. Requires `data:read_write` and template edit permission. Omitted metadata stays unchanged. Supply `content` or `project_id` to replace the graph. A shared workspace template can be edited by its author or a workspace admin; restricted templates remain author-only, and only the author may change sharing. If workspace membership repeatedly changes during saving, retry the same request after the 409 `WORKSPACE_TEMPLATE_MEMBERSHIP_CHANGED` response.

    PUT /api/v1/templates/user/{template_id}

  • Destructive

    Delete Location Reminder

    Delete a location reminder by ID.

    DELETE /api/v1/location_reminders/{reminder_id}

  • Destructive

    Revoke Access Token Api

    Revoke the access tokens obtained via OAuth

    DELETE /api/v1/access_tokens

  • Destructive

    Delete Workspace

    Deletes a workspace.

    DELETE /api/v1/workspaces/{workspace_id}

  • Destructive

    Delete Reminder

    Delete a reminder by ID.

    DELETE /api/v1/reminders/{reminder_id}

  • Destructive

    Delete Project

    Deletes a project and all of its sections and tasks.

    DELETE /api/v1/projects/{project_id}

  • Destructive

    Delete Section

    Delete the section and all of its tasks

    DELETE /api/v1/sections/{section_id}

  • Destructive

    Update Section

    Update a section.

    POST /api/v1/sections/{section_id}

  • Destructive

    Delete Comment

    Delete a comment by ID

    DELETE /api/v1/comments/{comment_id}

  • Destructive

    Delete Folder

    Delete a folder. Projects in the folder will be moved out of it.

    DELETE /api/v1/folders/{folder_id}

  • Destructive

    Delete Filter

    Delete a personal filter. Only available on plans that include filters. Returns a not found error if the filter doesn't exist, was already deleted, or belongs to another user. Workspace filters can't be deleted with this endpoint.

    DELETE /api/v1/filters/{filter_id}

  • Destructive

    Delete Upload

    Delete an uploaded file. The file must belong to the authenticated user. Returns `FILE_NOT_FOUND` when the upload cannot be found.

    DELETE /api/v1/uploads

  • Destructive

    Delete Label

    Deletes a personal label. All instances of the label will be removed from tasks

    DELETE /api/v1/labels/{label_id}

  • Destructive

    Email Disable

    Disable the current email to a Todoist object

    DELETE /api/v1/emails

  • Destructive

    Revoke Token Rfc7009 Compliant

    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)

    POST /api/v1/revoke

  • Destructive

    Delete Task

    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.

    DELETE /api/v1/tasks/{task_id}

  • Destructive

    Update Task

    Updates an existing task.

    POST /api/v1/tasks/{task_id}

Sync

  • Read

    Sync resource data

    Read specified resource types using an incremental sync token. Resource types include labels, projects, items, notes, sections, filters, reminders, reminders_location, locations, user, live_notifications, collaborators, user_settings, notification_settings, user_plan_limits, completed_info, stats, workspaces, workspace_users, workspace_filters, view_options, project_view_options_defaults, role_actions, user_item_orders. Pass sync_token=* for a full sync and reuse the returned sync_token for incremental sync. resource_types accepts all to include all types, and a leading minus excludes a type (for example -projects). The workspace_users resource is not returned in full sync; retrieve it using the REST endpoint and request incremental updates. Collaborators and collaborator_states describe shared-project participants. Response fields include per-command sync_status, including individual errors and temporary-ID mappings; HTTP success does not mean every command succeeded.

    POST /api/v1/sync

  • Write

    Accept an invitation

    Accept an invitation. Arguments: invitation_id String Yes The invitation ID. invitation_secret String Yes The secret fetched from the live notification.

    POST /api/v1/sync

  • Write

    Delete a collaborator

    Delete a collaborator. Removes a user from a shared project; role permissions apply. Arguments: project_id String Yes The project to be affected. email String Yes The user email with whom the project was shared.

    POST /api/v1/sync

  • Write

    Delete an invitation

    Delete an invitation. Arguments: invitation_id String Yes The invitation to be deleted.

    POST /api/v1/sync

  • Write

    Add a filter

    Add a filter. Arguments: name String Yes The name of the filter. query String Yes The query to search for. Examples of searches can be found in the Todoist help page. description String No The description of the filter, as markdown. Longer values are truncated. color String No The color of the filter icon. Refer to the name column in the Colors guide for more info. item_order Integer No Filter’s order in the filter list (the smallest value should place the filter at the top). order_key String No Fractional-indexing order key for the new filter. When omitted, the backend generates a key placing the filter at the bottom of the list. If another filter already uses the requested key, the backend stores an adjusted key placing the filter immediately after that position; the corrected value is returned via sync. is_favorite Boolean No Whether the filter is a favorite (a true or false value).

    POST /api/v1/sync

  • Write

    Update multiple filter orders (deprecated)

    Update multiple filter orders. Arguments: id_order_mapping Object Yes A dictionary, where a filter ID is the key, and the order its value: filter_id: order .

    POST /api/v1/sync

  • Write

    Add a folder

    Add a folder. Arguments: name String Yes The name of the folder. workspace_id String Yes Real or temp ID of the workspace the folder belongs to. add_project_ids Array of String No IDs of workspace projects to move into the folder as part of creating it. default_order_key String No Fractional-indexing key for the workspace's shared default-ordering scope (workspace projects and folders together). When omitted, the backend generates a key placing the folder at the bottom of that scope. If another project or folder in the workspace already uses the requested key, the backend stores an adjusted key placing the folder immediately after that position; the corrected value is returned via sync. While clients are migrating, the legacy default_order integers of the workspace's projects and folders are renumbered to follow the key order, so clients that still sort by default_order see the same order. default_order Integer No Legacy integer position within the workspace's shared default-ordering scope. Superseded by default_order_key ; when both are omitted the folder is placed at the bottom of the scope. child_order Integer No The user-specific order of the folder, independent of the workspace's shared default ordering.

    POST /api/v1/sync

  • Write

    Update a folder

    Update a folder. Arguments: id String Yes The ID of the folder (could be a temp id). workspace_id String Yes Real or temp ID of the workspace the folder belongs to. name String No The name of the folder. default_order_key String No Fractional-indexing key for the workspace's shared default-ordering scope (workspace projects and folders together). When omitted, the current key is kept. If another project or folder in the workspace already uses the requested key, the backend stores an adjusted key placing the folder immediately after that position; the corrected value is returned via sync. While clients are migrating, the legacy default_order integers of the workspace's projects and folders are renumbered to follow the key order, so clients that still sort by default_order see the same order. When a workspace admin changes a key, the workspace's admin sorting is also marked as applied ( admin_sorting_applied ). add_project_ids Array of String No IDs of workspace projects to move into the folder. remove_project_ids Array of String No IDs of workspace projects to move out of the folder.

    POST /api/v1/sync

  • Write

    Add a task

    Add a task. Defaults to Inbox if no project is specified; label auto-parsing can create labels. Arguments: content String Yes The text of the task. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. description String No A description for the task. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. project_id String No The ID of the project to add the task to (a number or a temp id). By default the task is added to the user’s Inbox project. due Object No The due date of the task. See the Due dates section for more details. deadline Object No The deadline of the task. See the Deadlines section for more details. priority Integer No The priority of the task (a number between 1 and 4 , 4 for very urgent and 1 for natural). Note : Keep in mind that very urgent is the priority 1 on clients. So, p1 will return 4 in the API. parent_id String No The ID of the parent task. Set to null for root tasks. child_order Integer No The order of task. Defines the position of the task among all the tasks with the same parent. order_key String No Fractional-indexing order key for the new task. When omitted, the backend generates a key placing the task at the bottom of the list of siblings sharing the same project, section and parent task. If a sibling already uses the requested key, the backend stores an adjusted key placing the task immediately after that position; the corrected value is returned via sync. section_id String No The ID of the section. Set to null for tasks not belonging to a section. day_order Integer No The order of the task inside the Today or Next 7 days view. Must be a signed 32-bit integer between -2147483648 and 2147483647 ; smaller values place the task nearer the top. is_collapsed Boolean No Whether the task's sub-tasks are collapsed (a true or false value). labels Array of String No The task's labels (a list of names that may represent either personal or shared labels). assigned_by_uid String No The ID of user who assigns the current task. This makes sense for shared projects only. Accepts 0 or any user ID from the list of project collaborators. If this value is unset or invalid, it will be automatically setup to your uid. responsible_uid String No The ID of user who is responsible for accomplishing the current task. This makes sense for shared projects only. Accepts any user ID from the list of project collaborators or null or an empty string to unset. auto_reminder Boolean No When this option is enabled, the default reminder will be added to the new item if it has a due date with time set. See also the auto_reminder user option for more info about the default reminder. auto_parse_labels Boolean No When this option is enabled, the labels will be parsed from the task content and added to the task. In case the label doesn't exist, a new one will be created. duration Object No The task's duration. Includes a positive integer (greater than zero) for the amount of time the task will take, and the unit of time that the amount represents which must be either minute or day . Both the amount and unit must be defined.

    POST /api/v1/sync

  • Write

    Close task

    Close task. Arguments: id String Yes The ID of the item to close (a number or a temp id).

    POST /api/v1/sync

  • Write

    Complete task

    Complete task. Arguments: id String Yes Task ID to complete. date_completed Date No RFC3339-formatted date of completion of the task (in UTC). If not set, or more than 24 hours in the future, the server will set the value to the current timestamp. from_undo Boolean No If true , skips incrementing completion stats. Used when restoring task state after undoing a completion.

    POST /api/v1/sync

  • Write

    Move a task

    Move a task. Exactly one of parent_id, section_id or project_id must be set. Arguments: id String Yes The ID of the task. parent_id String No ID of the destination parent task. The task becomes the last child task of the parent task. section_id String No ID of the destination section. The task becomes the last root task of the section. project_id String No ID of the destination project. The task becomes the last root task of the project.

    POST /api/v1/sync

  • Write

    Reorder tasks (deprecated)

    Reorder tasks. Arguments: items Array of Objects Yes An array of objects to update. Each object contains two attributes: id of the item to update and child_order , the new order.

    POST /api/v1/sync

  • Write

    Uncomplete item

    Uncomplete item. Arguments: id String Yes Task ID to uncomplete

    POST /api/v1/sync

  • Write

    Update day orders (deprecated)

    Update day orders. Arguments: ids_to_orders Object Yes A mapping where each key is a task ID and each value is a day_order (a signed 32-bit integer between -2147483648 and 2147483647 ): item_id: day_order .

    POST /api/v1/sync

  • Write

    Add a personal label

    Add a personal label. Arguments: name String Yes The name of the label color String No The color of the label icon. Refer to the name column in the Colors guide for more info. item_order Integer No Label’s order in the label list (a number, where the smallest value should place the label at the top). order_key String No Fractional-indexing order key for the new label. When omitted, the backend generates a key placing the label at the bottom of the list. If another label already uses the requested key, the backend stores an adjusted key placing the label immediately after that position; the corrected value is returned via sync. is_favorite Boolean No Whether the label is a favorite (a true or false value).

    POST /api/v1/sync

  • Write

    Rename a shared label

    Rename a shared label. Arguments: name_old String Yes The current name of the label to modify. name_new String Yes The new name for the label.

    POST /api/v1/sync

  • Write

    Update a personal label

    Update a personal label. Arguments: id String Yes The ID of the label. name String No The name of the label. color String No The color of the label icon. Refer to the name column in the Colors guide for more info. item_order Integer No Label’s order in the label list. order_key String No Fractional-indexing order key. When omitted, the current key is kept. If another label already uses the requested key, the backend stores an adjusted key placing the label immediately after that position; the corrected value is returned via sync. is_favorite Boolean No Whether the label is a favorite (a true or false value).

    POST /api/v1/sync

  • Write

    Update multiple label orders (deprecated)

    Update multiple label orders. Arguments: id_order_mapping Object Yes A dictionary, where a label id is the key, and the item_order value.

    POST /api/v1/sync

  • Write

    Mark as read

    Mark as read. Arguments: ids Array of String Yes The IDs of the notifications.

    POST /api/v1/sync

  • Write

    Mark all as read

    Mark all as read. Marks all notifications read; no arguments are documented.

    POST /api/v1/sync

  • Write

    Mark as unread

    Mark as unread. Arguments: ids Array of String Yes The IDs of the notifications.

    POST /api/v1/sync

  • Write

    Set last known

    Set last known. Arguments: id String Yes The ID of the last known notification (a number or 0 or null to mark all read).

    POST /api/v1/sync

  • Write

    Add task or project comment

    Add task or project comment. Works for task or project comments; availability depends on plan. An attachment can reference a previously uploaded file or external URL; the separate upload endpoint requires multipart or binary input, which Type raw API does not support. Required arguments: item_id or project_id, and content; supports optional file_attachment and notification recipients.

    POST /api/v1/sync

  • Write

    Update task or project comment

    Update task or project comment. Works for task or project comments; availability depends on plan and attachments need separate upload handling. Required arguments: id and content; optional file_attachment.

    POST /api/v1/sync

  • Write

    Add a project

    Add a project. Arguments: name String Yes The name of the project (a string value). color String No The color of the project icon. Refer to the name column in the Colors guide for more info. icon String No Project icon name. Omit it or pass null for the default icon. Refer to the Project icons guide. parent_id String No The ID of the parent project. Set to null for root projects folder_id String No The ID of the folder, when creating projects in workspaces. Set to null for root projects child_order Integer No The order of the project. Defines the position of the project among all the projects with the same parent_id order_key String No Fractional-indexing order key for the new project. When omitted, the backend generates a key placing the project at the bottom of its parent's list. If a sibling under the same parent_id already uses the requested key, the backend stores an adjusted key placing the project immediately after that position; the corrected value is returned via sync. is_favorite Boolean No Whether the project is a favorite (a true or false value). view_style String No A string value (either list or board , default is list ). This determines the way the project is displayed within the Todoist clients. description String No Description for the project (up to 1024 characters). Only used for teams workspace_id String No Real or temp ID of the workspace the project should belong to is_invite_only Boolean No Indicates if the project is invite-only or if it should be visible for everyone in the workspace. If missing or null, the default value from the workspace is_invite_only_default will be used. Only used for teams status String No The status of the project. Possible values: PLANNED , IN_PROGRESS , PAUSED , COMPLETED , CANCELED . Only used for teams is_link_sharing_enabled Boolean No If False, the project is invite-only and people can't join by link. If true, the project is visible to anyone with a link, and anyone can join it. Only used for teams collaborator_role_default String No The role a user can have. Possible values: CREATOR , ADMIN , READ_WRITE , EDIT_ONLY , COMPLETE_ONLY . ( CREATOR is equivalent to admin and is automatically set at project creation; it can't be set to anyone later). Only used for teams access Object No Project access configuration with visibility ( "restricted" , "team" , or "public" ) and configuration object. For public projects, configuration includes hide_collaborator_details and disable_duplication booleans. Only used for teams is_project_insights_enabled Boolean No Whether Project Insights is enabled for this project. Defaults to true . Only used for teams

    POST /api/v1/sync

  • Write

    Archive a project

    Archive a project. Arguments: id String Yes ID of the project to archive (could be a temp id).

    POST /api/v1/sync

  • Write

    Change project role

    Change project role. Arguments: id String Yes ID of the project to change the role for (could be a temp id). user_id Int Yes ID of the user whose role to change. role String Yes New role for the user. Valid values: CREATOR , ADMIN , READ_WRITE , EDIT_ONLY , COMPLETE_ONLY . Note: Only the project creator can be assigned the CREATOR role.

    POST /api/v1/sync

  • Write

    Leave a project

    Leave a project. Arguments: project_id String Yes The ID ( v2_id ) of the project to leave. It only accepts v2_id as the id.

    POST /api/v1/sync

  • Write

    Move a project

    Move a project. Arguments: id String Yes The ID of the project (could be a temp id). parent_id String No The ID of the parent project (could be a temp id). If set to null, the project will be moved to the root.

    POST /api/v1/sync

  • Write

    Move a Project out of a Workspace

    Move a Project out of a Workspace. Arguments: project_id String Yes The ID of the project being moved back (can be a temp id). use_lro Boolean No If true, process as a Long Running Operation. Recommended , as it will become the default behavior in a future version.

    POST /api/v1/sync

  • Write

    Move a Project to a Workspace

    Move a Project to a Workspace. Arguments: project_id String Yes The ID of the project (can be a temp id). workspace_id String Yes The ID of the workspace the project will be moved into is_invite_only Boolean No If true the project will be restricted access, otherwise any workspace member could join it folder_id String No If supplied, the project and any child projects will be moved into this workspace folder use_lro Boolean No If true, process as a Long Running Operation. Recommended; will become the default behavior in a future version.

    POST /api/v1/sync

  • Write

    Reorder projects (deprecated)

    Reorder projects. Arguments: projects Array of Objects Yes An array of objects to update. Each object contains two attributes: id of the project to update and child_order , the new order.

    POST /api/v1/sync

  • Write

    Unarchive a project

    Unarchive a project. Arguments: id String Yes ID of the project to unarchive (could be a temp id).

    POST /api/v1/sync

  • Write

    Update a project

    Update a project. Arguments: id String Yes The ID of the project (could be temp id). name String No The name of the project (a string value). color String No The color of the project icon. Refer to the name column in the Colors guide for more info. icon String No Project icon name. Pass null to reset to the default icon. Refer to the Project icons guide. is_collapsed Boolean No Whether the project's sub-projects are collapsed (a true or false value). is_favorite Boolean No Whether the project is a favorite (a true or false value). view_style String No A string value (either list or board ). This determines the way the project is displayed within the Todoist clients. order_key String No Fractional-indexing order key. When omitted, the current key is kept. If a sibling under the same parent_id already uses the requested key, the backend stores an adjusted key placing the project immediately after that position; the corrected value is returned via sync. default_order_key String No Fractional-indexing key for the workspace's shared default-ordering scope (workspace projects and folders together). Only accepted for workspace projects; ignored for personal projects. When omitted, the current key is kept. If another project or folder in the workspace already uses the requested key, the backend stores an adjusted key placing the project immediately after that position; the corrected value is returned via sync. While clients are migrating, the legacy default_order integers of the workspace's projects and folders are renumbered to follow the key order, so clients that still sort by default_order see the same order. When a workspace admin changes a key, the workspace's admin sorting is also marked as applied ( admin_sorting_applied ). Only used for teams description String No Description for the project (up to 1024 characters). Only used for teams status String No The status of the project. Possible values: PLANNED , IN_PROGRESS , PAUSED , COMPLETED , CANCELED . Only used for teams is_link_sharing_enabled Boolean No If False, the project is invite-only and people can't join by link. If true, the project is visible to anyone with a link, and anyone can join it. Only used for teams collaborator_role_default String No The role a user can have. Possible values: CREATOR , ADMIN , READ_WRITE , EDIT_ONLY , COMPLETE_ONLY . ( CREATOR is equivalent to admin and is automatically set at project creation; it can't be set to anyone later). Defaults to READ_WRITE . Only used for teams access Object No Project access configuration with visibility ( "restricted" , "team" , or "public" ) and configuration object. For public projects, configuration includes hide_collaborator_details and disable_duplication booleans. Only used for teams is_project_insights_enabled Boolean No Whether Project Insights is enabled for this project. Only used for teams

    POST /api/v1/sync

  • Write

    Reject an invitation

    Reject an invitation. Arguments: invitation_id String Yes The invitation ID. invitation_secret String Yes The secret fetched from the live notification.

    POST /api/v1/sync

  • Write

    Add a reminder

    Add a reminder. Arguments: item_id String Yes The item ID for which the reminder is about. type String Yes The type of the reminder: relative for a time-based reminder specified in minutes from now, absolute for a time-based reminder with a specific time and date in the future, and location for a location-based reminder. notify_uid String No The user ID which should be notified of the reminder, typically the current user ID creating the reminder. due Object No The due date of the reminder. See the Due dates section for more details. Note that reminders only support due dates with time, since full-day reminders don't make sense. minute_offset Integer No The relative time in minutes before the due date of the item, in which the reminder should be triggered. Note, that the item should have a due date with time set in order to add a relative reminder. name String No An alias name for the location. loc_lat String No The location latitude. loc_long String No The location longitude. loc_trigger String No What should trigger the reminder: on_enter for entering the location, or on_leave for leaving the location. radius Integer No The radius around the location that is still considered as part of the location (in meters). is_urgent Boolean No Whether the reminder is an urgent reminder (default false ). Only supported for time-based reminders ( relative or absolute ).

    POST /api/v1/sync

  • Write

    Update a reminder

    Update a reminder. Arguments: id String Yes The ID of the reminder. notify_uid String No The user ID which should be notified of the reminder, typically the current user ID creating the reminder. type String No The type of the reminder: relative for a time-based reminder specified in minutes from now, absolute for a time-based reminder with a specific time and date in the future, and location for a location-based reminder. due Object No The due date of the reminder. See the Due dates section for more details. Note that reminders only support due dates with time, since full-day reminders don't make sense. minute_offset Integer No The relative time in minutes before the due date of the item, in which the reminder should be triggered. Note, that the item should have a due date with time set in order to add a relative reminder. name String No An alias name for the location. loc_lat String No The location latitude. loc_long String No The location longitude. loc_trigger String No What should trigger the reminder: on_enter for entering the location, or on_leave for leaving the location. radius Integer No The radius around the location that is still considered as part of the location (in meters). is_urgent Boolean No Whether the reminder is an urgent reminder (default false ). Only supported for time-based reminders ( relative or absolute ).

    POST /api/v1/sync

  • Write

    Add a section

    Add a section. Arguments: name String Yes The name of the section. project_id String Yes The ID of the parent project. description String No The description of the section. section_order Integer No The order of the section. Defines the position of the section among all the sections in the project. order_key String No Fractional-indexing order key for the new section. When omitted, the backend generates a key placing the section at the bottom of the project's list. If another section in the project already uses the requested key, the backend stores an adjusted key placing the section immediately after that position; the corrected value is returned via sync.

    POST /api/v1/sync

  • Write

    Archive a section

    Archive a section. Arguments: id String Yes Section ID to archive.

    POST /api/v1/sync

  • Write

    Move a section

    Move a section. Arguments: id String Yes The ID of the section. project_id String No ID of the destination project.

    POST /api/v1/sync

  • Write

    Reorder sections (deprecated)

    Reorder sections. Arguments: sections Array of Objects Yes An array of objects to update. Each object contains two attributes: id of the section to update and section_order , the new order.

    POST /api/v1/sync

  • Write

    Unarchive a section

    Unarchive a section. Arguments: id String Yes Section ID to unarchive

    POST /api/v1/sync

  • Write

    Share a project

    Share a project. Arguments: project_id String Yes The project to be shared. email String Yes The user email with whom to share the project. role String No The role of the new collaborator in the workspace project. If missing, the workspace collaborator_role_default will be used. Only used for teams

    POST /api/v1/sync

  • Write

    Update karma goals

    Update karma goals. Arguments: daily_goal Integer No The target number of tasks to complete per day. weekly_goal Integer No The target number of tasks to complete per week. ignore_days Integer No A list with the days of the week to ignore ( 1 for Monday and 7 for Sunday ). vacation_mode Integer No Marks the user as being on vacation (where 1 is true and 0 is false). karma_disabled Integer No Whether to disable the karma and goals measuring altogether (where 1 is true and 0 is false).

    POST /api/v1/sync

  • Write

    User productivity stats

    User productivity stats. Arguments: reminder_push Boolean No Set to true to send reminders as push notifications. reminder_desktop Boolean No Set to true to show reminders in desktop applications. reminder_email Boolean No Set to true to send reminders by email. completed_sound_desktop Boolean No Set to true to enable sound when a task is completed in Todoist desktop clients. completed_sound_mobile Boolean No Set to true to enable sound when a task is completed in Todoist mobile clients.

    POST /api/v1/sync

  • Write

    Add a workspace

    Add a workspace. Arguments: name String Yes The name of the workspace. description String No The description of the workspace (up to 1024 characters). is_link_sharing_enabled Boolean No Indicates if users are allowed to join the workspace using an invitation link. Default value is True. is_guest_allowed Boolean No Indicates if users from outside the workspace are allowed to join or be invited to workspace projects. Default value is True. domain_name String No The domain name of the workspace. domain_discovery Boolean No True if users with e-mail addresses in the workspace domain can join the workspace without an invitation. restrict_email_domains Boolean No True if only users with e-mail addresses in the workspace domain can join the workspace. properties Object No Configuration properties for the workspace. See Workspace Properties for detailed structure. default_collaborators Object No Default collaborators for new projects. Object with user_ids (array of integers) and predefined_group_ids (array of strings). If not provided or set to null then by default all workspace members are added as the default collaborators.

    POST /api/v1/sync

  • Write

    Delete workspace user

    Delete workspace user. Removes a user from a workspace; requires administrator privileges. Arguments: id String Yes Real or temp ID of the workspace user_email String Yes The email of the member to be deleted

    POST /api/v1/sync

  • Write

    Add a workspace filter

    Add a workspace filter. Arguments: workspace_id String or Integer Yes The ID of the workspace this filter belongs to. name String Yes The name of the workspace filter. query String Yes The query to search for. Examples of searches can be found in the Todoist help page. description String No The description of the workspace filter, as markdown. Longer values are truncated. color String No The color of the filter icon. Refer to the name column in the Colors guide for more info. item_order Integer No Filter's order in the filter list (the smallest value should place the filter at the top). order_key String No Fractional-indexing order key for the new filter. When omitted, the backend generates a key placing the filter at the top of the workspace's list. If another filter already uses the requested key, the backend stores an adjusted key placing the filter immediately after that position; the corrected value is returned via sync.

    POST /api/v1/sync

  • Write

    Update multiple workspace filter orders (deprecated)

    Update multiple workspace filter orders. Arguments: id_order_mapping Object Yes A dictionary, where a workspace filter ID is the key, and the order its value: filter_id: order . Key differences from personal filters: Workspace filters require membership in the associated workspace Changes propagate to all workspace members via sync events Permissions are checked through workspace membership rather than user ownership

    POST /api/v1/sync

  • Write

    Invite Users to a Workspace

    Invite Users to a Workspace. Invites users to workspace; role and plan limitations apply. Arguments: id String Yes ID of the workspace. email_list List of String Yes A list of emails to be invited to the workspace. role String No The role the user will be given if they accept the invite. Possible values are ADMIN , MEMBER , and GUEST . If not provided, the default value according to the plan will be used. For Starter plans, the default is ADMIN and for Business plans, the default is MEMBER.

    POST /api/v1/sync

  • Write

    Leave a workspace

    Leave a workspace. Arguments: id String Yes Real or temp ID of the workspace All workspace_users can leave a workspace by themselves.

    POST /api/v1/sync

  • Write

    Resend a Workspace Invitation

    Resend a Workspace Invitation. Arguments: id String Yes ID of the workspace the pending invitation belongs to. email String Yes Email address of the pending invitee whose invite should be resent.

    POST /api/v1/sync

  • Write

    Update a workspace

    Update a workspace. Arguments: id String Yes Real or temp ID of the workspace name String No The name of the workspace. description String No The description of the workspace (up to 1024 characters). is_collapsed Boolean No The collapsed state of the workspace for the current user is_link_sharing_enabled Boolean No Indicates if users are allowed to join the workspace using an invitation link. is_guest_allowed Boolean No Indicates if users from outside the workspace are allowed to join or be invited to workspace projects. Default value is True. invite_code String No Regenerate the invite_code for the workspace. Any non-empty string value will regenerate a new code, the provided value with this argument is not significant, only an indication to regenerate the code. domain_name String No The domain name of the workspace. domain_discovery Boolean No True if users with e-mail addresses in the workspace domain can join the workspace without an invitation. restrict_email_domains Boolean No True if only users with e-mail addresses in the workspace domain can join the workspace. properties Object No Configuration properties for the workspace. See Workspace Properties for detailed structure. default_collaborators Object No Default collaborators for new projects. Object with user_ids (array of integers) and predefined_group_ids (array of strings). If not provided or set to null then by default all workspace members are added as the default collaborators.

    POST /api/v1/sync

  • Write

    Change user role

    Change user role. Changes a user role; only workspace admins may perform it. Arguments: id String Yes Real or temp ID of the workspace user_email String Yes The new member's email role String Yes The role to be assigned to the new member. Valid values are GUEST , MEMBER and ADMIN .

    POST /api/v1/sync

  • Write

    Update user sidebar preference

    Update user sidebar preference. Arguments: workspace_id String Yes Real or temp ID of the workspace sidebar_preference String Yes The sidebar preference. Valid values are MANUAL , A_TO_Z , and Z_TO_A .

    POST /api/v1/sync

  • Destructive

    Locations

    Locations. Clears the locations list used for location reminders; no arguments are documented.

    POST /api/v1/sync

  • Destructive

    Delete a filter

    Delete a filter. Arguments: id String Yes The ID of the filter.

    POST /api/v1/sync

  • Destructive

    Update a filter

    Update a filter. An empty description clears the existing filter description. Arguments: id String Yes The ID of the filter. name String No The name of the filter query String No The query to search for. Examples of searches can be found in the Todoist help page. description String No The description of the filter, as markdown. Pass an empty string to clear it; omit the field to leave it unchanged. Longer values are truncated. color String No The color of the filter icon. Refer to the name column in the Colors guide for more info. item_order Integer No Filter’s order in the filter list (where the smallest value should place the filter at the top). order_key String No Fractional-indexing order key. When omitted, the current key is kept. If another filter already uses the requested key, the backend stores an adjusted key placing the filter immediately after that position; the corrected value is returned via sync. is_favorite Boolean No Whether the filter is a favorite (a true or false value).

    POST /api/v1/sync

  • Destructive

    Delete tasks

    Delete tasks. Deletes the task and all subtasks. Arguments: id String Yes ID of the task to delete.

    POST /api/v1/sync

  • Destructive

    Update a task

    Update a task. Cannot move or complete a task; setting duration to null removes it. Arguments: id String Yes The ID of the task. content String No The text of the task. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. description String No A description for the task. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. due Object No The due date of the task. See the Due dates section for more details. deadline Object No The deadline of the task. See the Deadlines section for more details. priority Integer No The priority of the task (a number between 1 and 4 , 4 for very urgent and 1 for natural). Note : Keep in mind that very urgent is the priority 1 on clients. So, p1 will return 4 in the API. is_collapsed Boolean No Whether the task's sub-tasks are collapsed (a true or false value). labels Array of String No The task's labels (a list of names that may represent either personal or shared labels). assigned_by_uid String No The ID of the user who assigned the task. This makes sense for shared projects only. Accepts 0 or any user ID from the list of project collaborators. If this value is unset or invalid, it will be automatically setup to your uid. responsible_uid String No The ID of the user who is responsible for accomplishing the task. This makes sense for shared projects only. Accepts any user ID from the list of project collaborators or null or an empty string to unset. day_order Integer No The order of the task inside the Today or Next 7 days view. Must be a signed 32-bit integer between -2147483648 and 2147483647 ; smaller values place the task nearer the top. duration Object No The task's duration. Must a positive integer (greater than zero) for the amount of time the task will take, and the unit of time that the amount represents which must be either minute or day . Both the amount and unit must be defined. The object should be set to null to remove the task's duration. order_key String No Fractional-indexing order key. When omitted, the current key is kept. If a sibling already uses the requested key, the backend stores an adjusted key placing the task immediately after that position; the corrected value is returned via sync.

    POST /api/v1/sync

  • Destructive

    Complete a recurring task

    Complete a recurring task. May reset subtasks if reset_subtasks is set. Arguments: id String Yes The ID of the item to update (a number or a temp id). due Object No The due date of the task. See the Due dates section for more details. is_forward Boolean No Set this argument to 1 for completion, or 0 for uncompletion (e.g., via undo). By default, this argument is set to 1 (completion). reset_subtasks Boolean No Set this property to 1 to reset subtasks when a recurring task is completed. By default, this property is not set (0), and subtasks will retain their existing status when the parent task recurs. reset_subtasks=1 resets subtasks on completion; default 0 retains their state.

    POST /api/v1/sync

  • Destructive

    Delete a personal label

    Delete a personal label. Arguments: id String Yes The ID of the label. cascade String No A string value, either all (default) or none . If no value or all is passed, the personal label will be removed and any instances of the label will also be removed from tasks (including tasks in shared projects). If none is passed, the personal label will be removed from the user's account but it will continue to appear on tasks as a shared label.

    POST /api/v1/sync

  • Destructive

    Delete shared label occurrences

    Delete shared label occurrences. Removes occurrences of a shared label. Arguments: name String Yes The name of the label to remove.

    POST /api/v1/sync

  • Destructive

    Delete task or project comment

    Delete task or project comment. Works for task or project comments; availability depends on plan. Required arguments: id.

    POST /api/v1/sync

  • Destructive

    Delete a project

    Delete a project. Deletes the project and all descendants; workspace project requires admin and prior archival. Arguments: id String Yes ID of the project to delete (could be a temp id).

    POST /api/v1/sync

  • Destructive

    Project View Options Defaults

    Project View Options Defaults. Requires project admin. View property settings use patch semantics and may clear saved settings. Arguments: project_id Yes The project ID to update defaults for view_mode No The default view mode: list , board , calendar , or table grouped_by No How to group tasks (see properties above) sorted_by No How to sort tasks (see properties above) sort_order No Sort direction: asc or desc show_completed_tasks No Whether to show completed tasks filtered_by No JSON string with filter criteria calendar_settings No Calendar-specific settings: layout is WEEK or MONTH ; optional visible_day_count is 1 , 3 , or 7 for the week layout; optional color is PRIORITY , LABEL , or PROJECT and defaults to PRIORITY property_settings No How the project's views show task properties, as a patch, as in view options

    POST /api/v1/sync

  • Destructive

    Delete a reminder

    Delete a reminder. Arguments: id String Yes The ID of the filter.

    POST /api/v1/sync

  • Destructive

    Delete a section

    Delete a section. Arguments: id String Yes ID of the section to delete.

    POST /api/v1/sync

  • Destructive

    Update a section

    Update a section. Setting description to null clears it. Arguments: id String Yes The ID of the section. name String No The name of the section. description String No The description of the section. Pass null to clear it; omit to leave it unchanged. order_key String No Fractional-indexing order key. When omitted, the current key is kept. If another section in the project already uses the requested key, the backend stores an adjusted key placing the section immediately after that position; the corrected value is returned via sync. is_collapsed Boolean No Whether the section's tasks are collapsed (a true or false value).

    POST /api/v1/sync

  • Destructive

    Update a user item order

    Update a user item order. A null order_key clears the task placement. Arguments: item_id String Yes The ID of the task to place. scope String Yes Which ordering to place it in. Only day is currently accepted. order_key String Yes Where to place it, as a fractional-indexing key. Pass null to clear the task's place in this ordering.

    POST /api/v1/sync

  • Destructive

    Update user's properties

    Update user's properties. Can clear the saved device or entire status. Arguments: current_password String Yes (if modifying email or password ) The user's current password. This must be provided if the request is modifying the user's password or email address and the user already has a password set (indicated by has_password in the user object). For amending other properties this is not required. email String No The user's email. full_name String No The user's name. password String No The user's updated password. Must contain at least 8 characters and not be a common or easily guessed password. timezone String No The user's timezone (a string value such as UTC , Europe/Lisbon , US/Eastern , Asia/Taipei ). start_page String No The user's default view on Todoist. The start page can be one of the following: inbox , teaminbox , today , next7days , project?id=1234 to open a project, label?name=abc to open a label, filter?id=1234 to open a personal filter or workspace_filter?id=1234 to open a workspace filter. start_day Integer No The first day of the week (between 1 and 7 , where 1 is Monday and 7 is Sunday ). next_week Integer No The day of the next week, that tasks will be postponed to (between 1 and 7 , where 1 is Monday and 7 is Sunday ). time_format Integer No Whether to use a 24h format such as 13:00 (if set to 0 ) when displaying time, or a 12h format such as 1:00pm (if set to 1 ). date_format Integer No Whether to use the DD-MM-YYYY date format (if set to 0 ), or the MM-DD-YYYY format (if set to 1 ). sort_order Integer No Whether to show projects in an oldest dates first order (if set to 0 , or a oldest dates last order (if set to 1 ). auto_reminder Integer No The default time in minutes for the automatic reminders set, whenever a due date has been specified for a task. urgent_reminder_device Object No The device to receive urgent reminder alarms. An object with device_platform ( ios or android ) and either device_id (the device's numeric ID as a string) or device_token (the push notification token). The device must already be registered for the user. When stored and returned, the object contains both identifiers. Send null (or an empty object {} ) to clear the current device. status Object No A partial update to the user's status. Omitted fields remain unchanged, including within effects and each effect's configuration. message is required when creating a status, including after expiration. A supplied active_until must be in the future. Send null to clear the entire status; omit status to leave it unchanged. See the update rules below. theme Integer No The currently selected Todoist theme (between 0 and 10 ). weekend_start_day Integer No The day used when a user chooses to schedule a task for the 'Weekend' (between 1 and 7, where 1 is Monday and 7 is Sunday). beta Boolean No Whether the user is included in the beta testing group. onboarding_completed Boolean No For first-party clients usage only. This attribute may be removed or changed without notice, so we strongly advise not to rely on it. onboarding_initiated Boolean No For first-party clients usage only. This attribute may be removed or changed without notice, so we strongly advise not to rely on it. onboarding_level String No For first-party clients usage only. The onboarding level ( pro , intermediate , beginner ). This attribute may be removed or changed without notice, so we strongly advise not to rely on it. onboarding_persona String No For first-party clients usage only. The onboarding persona ( analog , tasks , calendar , organic ). This attribute may be removed or changed without notice, so we strongly advise not to rely on it. onboarding_role String No For first-party clients usage only. The onboarding role ( leader , founder , ic ). This attribute may be removed or changed without notice, so we strongly advise not to rely on it. onboarding_skipped Boolean No For first-party clients usage only. This attribute may be removed or changed without notice, so we strongly advise not to rely on it. onboarding_started Boolean No For first-party clients usage only. This attribute may be removed or changed without notice, so we strongly advise not to rely on it. onboarding_team_mode Boolean No For first-party clients usage only. This attribute may be removed or changed without notice, so we strongly advise not to rely on it. onboarding_use_cases Array No For first-party clients usage only. JSON array of onboarding use cases ( personal , work , education , teamwork , solo , teamcreator , simple , teamjoiner ). This attribute may be removed or changed without notice, so we strongly advise not to rely on it. completed_guide_project_id String No For first-party clients usage only. Mark a Getting Started Guide project as completed by providing its project ID. This attribute may be removed or changed without notice, so we strongly advise not to rely on it. closed_guide_project_id String No For first-party clients usage only. Mark a Getting Started Guide project as closed (dismissed) by providing its project ID. This attribute may be removed or changed without notice, so we strongly advise not to rely on it. getting_started_guide_projects String No For first-party clients usage only. JSON array of Getting Started guide projects with completion tracking. Each project contains project_id , onboarding_use_case , completed , and closed status. This attribute may be removed or changed without notice, so we strongly advise not to rely on it. Status updates Within status , supplied objects merge by field. Explicit null removes an optional field or effect: for example, emoji: null removes the emoji and active_until: null removes expiration. Required fields, such as message , cannot be removed with null . effects: {} preserves all existing effects. effects: null removes all effects while retaining the status. effects: {"pause_notifications": null} removes only notification pausing. effects: {"pause_notifications": {}} enables notification pausing with default configuration if absent, or preserves its configuration if already enabled. For example, this update changes the message and removes notification pausing, while preserving the emoji, expiration, and any other effects: { "type" : "user_update" , "uuid" : "97ef7fd8-1199-4f9c-a23d-028098359c04" , "args" : { "status" : { "message" : "Back soon" , "effects" : { "pause_notifications" : null } } } } An expired status is treated as absent. Creating a status requires a message and does not inherit expired fields or effects. Defaults apply only to newly created statuses, effects, or configuration objects. Unknown incoming fields are ignored; unknown stored fields are preserved unless their containing effect or the entire status is explicitly cleared. Invalid updates leave the stored status unchanged. Error codes Error Tag Description PASSWORD_REQUIRED The command attempted to modify password or email , but no value was provided for current_password . AUTHENTICATION_ERROR The value for current_password was incorrect. PASSWORD_TOO_SHORT The value for password was shorter than the minimum 8 characters. COMMON_PASSWORD The value for password was matched against a common password list and rejected. PASSWORD_CONTAINS_EMAIL The value for password was matched against the user's email address or a part of the address. INVALID_EMAIL The value for email was not a valid email address. BAD_REQUEST The value for urgent_reminder_device was invalid (missing or malformed device_platform , device_id , or device_token ). ERROR_DEVICE_NOT_FOUND The device specified in urgent_reminder_device is not registered for this user. USER_STATUS_EXPIRED The active_until of status was not in the future. SERVICE_UNAVAILABLE Another operation is changing the user's status. Retry after error_extra.retry_after seconds.

    POST /api/v1/sync

  • Destructive

    Delete view option

    Delete view option. Arguments: view_type Enum Yes Type of the view customization to delete. today for the today view, upcoming for the upcoming view, assigned_to_me for the assigned to me view, project for a project, label for a label, or filter for a filter. object_id String No ID of the object referred to by view_type , required when view_type is project , label , filter or workspace_filter .

    POST /api/v1/sync

  • Destructive

    Set a view option

    Set a view option. Can replace ordering arrays or clear property settings. Arguments: view_type Enum Yes Type of the view customization to be set. today for the today view, upcoming for the upcoming view, assigned_to_me for the assigned to me view, project for a project, label for a label, filter for a personal filter or workspace_filter for a team filter. object_id String No ID of the object referred to by view_type , required when view_type is project , label , filter or workspace_filter . filtered_by String No Search query. Examples of searches can be found in the Todoist help page. grouped_by Enum No Grouping criteria. One of assignee , added_date , due_date , deadline , label , priority , project , or workspace . sorted_by Enum No Sorting criteria. One of alphabetically , assignee , added_date , due_date , deadline , label , priority , project , workspace , or manual . sort_order Enum No Sorting order. asc for ascending, desc for descending. show_completed_tasks Boolean No Whether completed tasks should be shown automatically in this view customization. view_mode Enum No The mode in which to render tasks. One of list , board , calendar , or table . deadline String No A search query for this view customization. Examples of deadline searches can be found in the Todoist help page. calendar_settings JSON No The settings for the calendar when view_mode is set to calendar . layout is WEEK or MONTH ; optional visible_day_count is 1 , 3 , or 7 for the week layout; optional color is PRIORITY , LABEL , or PROJECT and defaults to PRIORITY . property_settings JSON No The property settings (see above), as a patch: objects merge into the saved ones, arrays such as order replace them, and null removes its path ( {"properties": {"due": {"width": null}}} resets one width); {} changes nothing, and property_settings: null clears them all. Settings that are invalid, or over 32 KiB once merged, are ignored.

    POST /api/v1/sync

  • Destructive

    Delete a workspace

    Delete a workspace. Workspace deletion requires administrator privileges. Arguments: id String Yes The ID of the workspace

    POST /api/v1/sync

  • Destructive

    Delete a workspace filter

    Delete a workspace filter. Arguments: id String Yes The ID of the workspace filter.

    POST /api/v1/sync

  • Destructive

    Update a workspace filter

    Update a workspace filter. An empty description clears the existing workspace filter description. Arguments: id String Yes The ID of the workspace filter. name String No The name of the workspace filter. query String No The query to search for. Examples of searches can be found in the Todoist help page. description String No The description of the workspace filter, as markdown. Pass an empty string to clear it; omit the field to leave it unchanged. Longer values are truncated. color String No The color of the filter icon. Refer to the name column in the Colors guide for more info. item_order Integer No Filter's order in the filter list (where the smallest value should place the filter at the top). order_key String No Fractional-indexing order key. When omitted, the current key is kept. If another filter already uses the requested key, the backend stores an adjusted key placing the filter immediately after that position; the corrected value is returned via sync. is_favorite Boolean No Whether the filter is a favorite for the user (a true or false value).

    POST /api/v1/sync

  • Destructive

    Set default project ordering (deprecated)

    Set default project ordering. Replaces the default order of every listed project and folder and can move projects between folders. Arguments: workspace_id String Yes Real or temp ID of the workspace. projects Array of Objects Yes An array of objects to update. Each object contains id of the project, default_order (the new order), and optionally folder_id (moves the project into that folder as part of the reorder; null moves it to the workspace root). folders Array of Objects Yes An array of objects to update. Each object contains id of the folder to update and default_order , the new order.

    POST /api/v1/sync

See How connections work for access and permissions, or browse all integrations.