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
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
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
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
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
No operations match.
See How connections work for access and permissions, or browse all integrations.