{ "openapi": "3.1.0", "info": { "title": "Todoist API", "version": "1", "x-logo": { "url": "https://developer.todoist.com/images/td_logo-4f2a90df.svg" }, "description": "# Developing with Todoist\n\nThanks for your interest in developing apps with Todoist. In this section\nwe will provide an overview of the API we offer and cover some common topics for\napplication development using them.\n\nYou can use our API for free, but depending on your Todoist account plan (or that of the authenticated user), some\nfeatures may be restricted.\n\nPlease consider subscribing to the [Todoist API mailing\nlist](https://groups.google.com/a/doist.com/g/todoist-api) to get important updates.\n\n## Our API\n\nOur API uses an approach that should be familiar to anyone with experience\ncalling [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs.\n\nWe also have a special endpoint called `/sync`, which is used by our\nfirst-party clients to keep the data updated locally without having to make many\nseparate requests to the API. Anyone can use it, and some actions will only be\navailable via `/sync`. The format is unconventional compared to current API standards,\nbut it is our main driver for first-party apps.\n\n## Our SDKs\n\nOur Python and JavaScript SDKs streamline working with the Todoist API, and\ncan be installed from the main package registries for each ecosystem.\n\nFor instructions, examples, and reference documentation, visit their pages:\n\n- [Todoist Python SDK](https://doist.github.io/todoist-api-python/)\n- [Todoist TypeScript SDK](https://doist.github.io/todoist-sdk-typescript/)\n\n## Resource IDs and optimistic updates\n\nOur first-party clients use optimistic updates so newly-created resources\n(tasks, projects, etc.) are usable in the UI before the server has confirmed\nthem. During that window, the resource is referenced by a **client-side\nplaceholder ID** with a `tmp-` prefix \u2014 for example\n`tmp-UUID-XXXX-UnixMillis`. Once the sync with Todoist completes, the client\nreplaces the placeholder with the real server-assigned ID.\n\n**Placeholder IDs are not valid server-side resource identifiers.** If you\npass a `tmp-`-prefixed ID to a REST endpoint, the request will fail with a\nvalidation error (for example `Non-base32 digit found`) because the API only\naccepts base32-encoded or numeric IDs (depending on the resource).\n\nIf your integration receives a resource ID from a client context (e.g. a UI\nextension payload or a browser event fired right after task creation), you\nshould:\n\n1. **Detect placeholder IDs early** \u2014 any ID starting with `tmp-` has not\n yet synced.\n2. **Wait for sync to complete before calling the REST API.** First-party\n clients expose the real ID once the next `/sync` round-trip returns\n (see the [`temp_id_mapping`](#tag/Sync/Overview/Temporary-resource-ID)\n field in the Sync API response).\n3. **Retry your API call with the confirmed ID** once available. If you\n cannot wait, surface the delay to the end user rather than calling the\n REST API with the placeholder.\n\nNote that this client-side `tmp-`-prefixed placeholder is distinct from the\n`temp_id` used in Sync API commands \u2014 the latter is a developer-supplied\nUUID that the server resolves inside a single `/sync` request. See the\n[Sync API's Temporary resource ID documentation](#tag/Sync/Overview/Temporary-resource-ID)\nfor details on `temp_id` and `temp_id_mapping`.\n\n## Integrations\n\nIntegrations can be created and updated [here](https://app.todoist.com/app/settings/integrations/app-management).\n\nOnce done, they can also be submitted for evaluation and inclusion in [our\nofficial integrations list](https://www.todoist.com/integrations). This not\nonly serves as an opportunity to market your integration to our audience, but\nwill also serve as a way to help users get set up and familiar with your app quickly.\n\nFor more information on how to submit your integration for evaluation, refer to our [Marketing your integration page](https://www.todoist.com/help/articles/marketing-your-todoist-integration-B6C5sCKkn).\n\n## Brand usage\n\nWhen creating with the Todoist platform, you may reference Todoist to describe\nwhat your app does, but you must keep it clearly distinct from Doist's official\nproducts.\n\n- **Naming:** \"Todoist\" cannot be the primary name of your app. Use a format\n that signals independence, such as \"x for Todoist\" or \"x with Todoist\".\n- **Disclaimer:** Your application description must state that it is \"not\n created by, affiliated with, or supported by Doist.\"\n- **Logo and branding:** Any use of Todoist's marks must comply with our\n [brand guidelines](https://doist.com/brand-assets/todoist-logo.zip), which are\n available for download.\n- **Legal compliance:** By using Todoist branding you agree to follow our brand\n guidelines and [Terms of Service](https://doist.com/terms-of-service).\n\nFor detailed questions about using the Todoist marks, contact\n[press@doist.com](mailto:press@doist.com).\n\nLost? [Reach out to us](https://www.todoist.com/contact/login?returnTo=%2Fcontact) anytime.\n" }, "paths": { "/api/v1/workspaces/invitations/delete": { "post": { "tags": [ "Workspace" ], "summary": "Delete Invitation", "description": "Deletes a workspace invitation. Only admins can delete invitations.", "operationId": "delete_invitation_api_v1_workspaces_invitations_delete_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_52bab197" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceInvitationView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/invitations/all": { "get": { "tags": [ "Workspace" ], "summary": "All Invitations", "description": "Return a list containing details of all pending invitation to a workspace.\n\nThis list is not paginated. All workspace members can access this list.", "operationId": "all_invitations_api_v1_workspaces_invitations_all_get", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "integer", "description": "ID of the workspace.", "examples": [ 123456 ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceInvitationView" }, "title": "Response All Invitations Api V1 Workspaces Invitations All Get" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/invitations/{invite_code}/accept": { "put": { "tags": [ "Workspace" ], "summary": "Accept Invitation", "description": "Accept a workspace invitation. Usable by authenticated users only.", "operationId": "accept_invitation_api_v1_workspaces_invitations__invite_code__accept_put", "parameters": [ { "name": "invite_code", "in": "path", "required": true, "schema": { "type": "string", "description": "An opaque string representing an invite code. This invitation code is sent to a user via email and is exclusive for the user.", "examples": [ "26d332457f16dc67f18385194be148f62c2b4317" ], "title": "Invite Code" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceInvitationView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/invitations/{invite_code}/reject": { "put": { "tags": [ "Workspace" ], "summary": "Reject Invitation", "description": "Reject a workspace invitation. Usable by authenticated users only.", "operationId": "reject_invitation_api_v1_workspaces_invitations__invite_code__reject_put", "parameters": [ { "name": "invite_code", "in": "path", "required": true, "schema": { "type": "string", "description": "An opaque string representing an invite code. This invitation code is sent to a user via email and is exclusive for the user.", "examples": [ "26d332457f16dc67f18385194be148f62c2b4317" ], "title": "Invite Code" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceInvitationView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/{workspace_id}/projects/archived": { "get": { "tags": [ "Workspace" ], "summary": "Archived Projects", "description": "Return archived projects in a workspace.\n\nWorkspace guests cannot list archived projects and receive a `FORBIDDEN`\nerror. Results are paginated by `cursor` and `limit`.", "operationId": "archived_projects_api_v1_workspaces__workspace_id__projects_archived_get", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "description": "ID of the workspace whose archived projects should be listed.", "examples": [ 123456 ], "title": "Workspace Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "The number of archived workspace projects to return in a page.", "examples": [ 50 ], "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ProjectsResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/{workspace_id}/projects/active": { "get": { "tags": [ "Workspace" ], "summary": "Active Projects", "description": "Returns all active workspace projects, including those visible but not joined by the user.\n\n_For guests, returns all joined workspace projects only._", "operationId": "active_projects_api_v1_workspaces__workspace_id__projects_active_get", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "description": "ID of the workspace whose active projects should be listed.", "examples": [ 123456 ], "title": "Workspace Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "The number of active workspace projects to return in a page.", "examples": [ 50 ], "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ProjectsResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/{workspace_id}/users/invite": { "post": { "tags": [ "Workspace" ], "summary": "Invite Workspace Users", "description": "Invites users to a workspace by email.", "operationId": "invite_workspace_users_api_v1_workspaces__workspace_id__users_invite_post", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "ID of the workspace", "examples": [ 123456 ], "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_108b7f01" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteWorkspaceUsersResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/labels/shared/remove": { "post": { "tags": [ "Labels" ], "summary": "Shared Labels Remove", "description": "Remove the given shared label from all active tasks", "operationId": "shared_labels_remove_api_v1_labels_shared_remove_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_0680de45" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/labels/shared/rename": { "post": { "tags": [ "Labels" ], "summary": "Shared Labels Rename", "description": "Rename the given shared label from all active tasks", "operationId": "shared_labels_rename_api_v1_labels_shared_rename_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_6ec83bd4" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks/completed/by_completion_date": { "get": { "tags": [ "Tasks" ], "summary": "Tasks Completed By Completion Date", "description": "Retrieves a list of completed tasks strictly limited by the specified completion\ndate range (up to 3 months).\n\nIt can retrieve completed items:\n\n- From all the projects the user has joined in a workspace\n- From all the projects of the user\n- That match many [supported\n filters](https://todoist.com/help/articles/introduction-to-filters-V98wIH)\n\nBy default, the response is limited to a page containing a maximum of 50 items\n(configurable using `limit`).\n\nSubsequent pages of results can be fetched by using the `next_cursor` value from the\nresponse as the `cursor` value for the next request.", "operationId": "tasks_completed_by_completion_date_api_v1_tasks_completed_by_completion_date_get", "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "Start of the completion date range, inclusive.", "examples": [ "2025-02-01T00:00:00Z" ], "title": "Since" } }, { "name": "until", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "End of the completion date range, exclusive.", "examples": [ "2025-02-28T23:59:59Z" ], "title": "Until" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Workspace ID to limit completed tasks to.", "examples": [ 123456 ], "title": "Workspace Id" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID to limit completed tasks to.", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } }, { "name": "section_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Section ID to limit completed tasks to.", "examples": [ "6fFPHV272WWh3gpW" ], "title": "Section Id" } }, { "name": "parent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent task ID to limit completed subtasks to.", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Parent Id" } }, { "name": "filter_query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ], "description": "Todoist filter query to limit completed tasks.", "examples": [ "#Work & overdue" ], "title": "Filter Query" } }, { "name": "filter_lang", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Language code used to parse `filter_query`.", "examples": [ "en" ], "title": "Filter Lang" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum number of completed tasks to return.", "examples": [ 50 ], "default": 50, "title": "Limit" } }, { "name": "public_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "description": "Public project access key.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, { "type": "null" } ], "title": "Public Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksCompletedDateResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks/completed/by_due_date": { "get": { "tags": [ "Tasks" ], "summary": "Tasks Completed By Due Date", "description": "Retrieves a list of completed items strictly limited by the specified due date range\n(up to 6 weeks).\n\nIt can retrieve completed items:\n\n- From within a project, section, or parent item\n- From all the projects the user has joined in a workspace\n- From all the projects of the user\n- That match many [supported\n filters](https://todoist.com/help/articles/introduction-to-filters-V98wIH)\n\nBy default, the response is limited to a page containing a maximum of 50 items\n(configurable using `limit`).\n\nSubsequent pages of results can be fetched by using the `next_cursor` value from the\nresponse as the `cursor` value for the next request.", "operationId": "tasks_completed_by_due_date_api_v1_tasks_completed_by_due_date_get", "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "Start of the due date range, inclusive.", "examples": [ "2025-02-01T00:00:00Z" ], "title": "Since" } }, { "name": "until", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "End of the due date range, exclusive.", "examples": [ "2025-02-28T23:59:59Z" ], "title": "Until" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Workspace ID to limit completed tasks to.", "examples": [ 123456 ], "title": "Workspace Id" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID to limit completed tasks to.", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } }, { "name": "section_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Section ID to limit completed tasks to.", "examples": [ "6fFPHV272WWh3gpW" ], "title": "Section Id" } }, { "name": "parent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent task ID to limit completed subtasks to.", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Parent Id" } }, { "name": "filter_query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ], "description": "Todoist filter query to limit completed tasks.", "examples": [ "#Work & overdue" ], "title": "Filter Query" } }, { "name": "filter_lang", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Language code used to parse `filter_query`.", "examples": [ "en" ], "title": "Filter Lang" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum number of completed tasks to return.", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksCompletedDateResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks/completed/stats": { "get": { "tags": [ "User" ], "summary": "Get Productivity Stats", "description": "Get comprehensive productivity statistics for the authenticated user.\nThis endpoint is used to display information about the\n[Karma system](https://www.todoist.com/help/articles/introduction-to-karma-OgWkWy).\n\nReturns detailed completion statistics including:\n\n- Daily completion counts with per-project breakdowns for the last 7 days\n- Weekly completion counts with per-project breakdowns for the last 4 weeks\n- Total completed task count\n- Karma score, trend, graph data, and update history\n- Goal settings (daily/weekly goals, ignore days, vacation mode)\n- Streak information (current, last, and maximum daily and weekly streaks)\n- Project color mappings for visualization", "operationId": "get_productivity_stats_api_v1_tasks_completed_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductivityStatsResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/access_tokens/migrate_personal_token": { "post": { "tags": [ "Authorization" ], "summary": "Migrate Personal Token", "description": "Tokens obtained via the old email/password authentication method can be\nmigrated to the new OAuth access token. Migrating your users' personal tokens\nwill allow users to see your app in their Todoist Settings page and give them\nthe ability to manage their app authorization.\n\nA successful response has `200 OK` status and `application/json` Content-Type.", "operationId": "migrate_personal_token_api_v1_access_tokens_migrate_personal_token_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_999fd79a" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_MigratePersonalTokenResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/usage_billing/usage_summary": { "get": { "tags": [ "Billing" ], "summary": "Usage Billing Usage Summary", "description": "Total the caller's settled usage over a window.\n\n`/history` is a ledger with one row per movement, so a total spanning more\nthan one page cannot come from it. This answers the one question the UI asks\nof the whole ledger at once: how many runs, and what they cost.\n\nOnly settled usage counts. `void`, `expiry` and `chargeback` draw the balance\ndown as well, but they reverse a grant rather than report usage.", "operationId": "usage_billing_usage_summary_api_v1_usage_billing_usage_summary_get", "parameters": [ { "name": "product", "in": "query", "required": false, "schema": { "type": "string", "description": "Product whose usage to total.", "examples": [ "automations" ], "default": "automations", "title": "Product" } }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Count one kind of work only, for example `automation_run`. More than one kind settles against the same balance, so a per-run average over all of them mixes runs with chat messages. Omit to total every category.", "examples": [ "automation_run" ], "title": "Category" } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start of the window, inclusive. Omit to start at the account's first event. A value with no offset is read as UTC, which is what `created_at` in `/history` reports.", "examples": [ "2026-07-15T00:00:00Z" ], "title": "Since" } }, { "name": "until", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End of the window, exclusive. Omit to run to now. A value with no offset is read as UTC.", "examples": [ "2026-08-15T00:00:00Z" ], "title": "Until" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_UsageSummaryResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/usage_billing/history": { "get": { "tags": [ "Billing" ], "summary": "Usage Billing History", "description": "List the caller's usage-billing ledger entries, newest first.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for\ndetails on using cursor-based pagination.", "operationId": "usage_billing_history_api_v1_usage_billing_history_get", "parameters": [ { "name": "product", "in": "query", "required": false, "schema": { "type": "string", "description": "Product whose ledger to read.", "examples": [ "automations" ], "default": "automations", "title": "Product" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_HistoryResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/usage_billing/top_up": { "post": { "tags": [ "Billing" ], "summary": "Usage Billing Top Up", "description": "In V1, create a hosted Stripe Checkout session to top up the authenticated user's personal Automations wallet.\n\nThe user must have a personal Stripe customer and an active personal Todoist Pro subscription. A Business or\nworkspace subscription alone does not qualify. A Business member who also has personal Todoist Pro tops up their\npersonal wallet.\n\nIf the personal Stripe customer or personal Todoist Pro prerequisite is not met, the endpoint returns HTTP 400 with\nerror tag `USAGE_BILLING_TOP_UP_UNAVAILABLE` and error code `605`.", "operationId": "usage_billing_top_up_api_v1_usage_billing_top_up_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_b48755ce" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_TopUpResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/usage_billing/state": { "get": { "tags": [ "Billing" ], "summary": "Usage Billing State", "description": "Read the caller's usage-billing credit state for a product.", "operationId": "usage_billing_state_api_v1_usage_billing_state_get", "parameters": [ { "name": "product", "in": "query", "required": false, "schema": { "type": "string", "description": "Product whose credit state to read.", "examples": [ "automations" ], "default": "automations", "title": "Product" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_CreditStateResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/plan_details": { "get": { "tags": [ "Workspace" ], "summary": "Plan Details", "description": "Lists details of the workspace's current plan and usage", "operationId": "plan_details_api_v1_workspaces_plan_details_get", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "integer", "description": "ID of the workspace.", "examples": [ 123456 ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_PlanDetailsResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/invitations": { "get": { "tags": [ "Workspace" ], "summary": "Invitations", "description": "Return a list of user emails who have a pending invitation to a workspace.\n\nThe list is not paginated. All workspace members can access this list.", "operationId": "invitations_api_v1_workspaces_invitations_get", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "integer", "description": "ID of the workspace.", "examples": [ 123456 ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "description": "Email of the invitation.", "examples": [ "example@email.org" ] }, "title": "Response Invitations Api V1 Workspaces Invitations Get" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/users": { "get": { "tags": [ "Workspace" ], "summary": "Get Workspaces Users", "description": "Returns all workspace_users for a given workspace if workspace_id is\nprovided. Otherwise, returns all workspace_users for all workspaces that\nthe requesting user is part of.\n\n_Not accessible by guests._", "operationId": "get_workspaces_users_api_v1_workspaces_users_get", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "ID of the workspace to list users for.", "examples": [ 123456 ], "title": "Workspace Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum number of workspace users to return.", "examples": [ 50 ], "default": 100, "title": "Limit" } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "id", "name" ], "type": "string", "description": "Order workspace users by ID, or by name with the requesting user first. Name sorting requires workspace_id.", "examples": [ "name" ], "default": "id", "title": "Sort" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_UsersResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/join": { "post": { "tags": [ "Workspace" ], "summary": "Join", "description": "Join a workspace via link or via workspace ID, if the user can auto-join\nthe workspace by domain.\n\n## Joining by Domain\nThis is possible if:\n- The user is verified\n- The user has a user e-mail belonging to a domain that is set\n as a domain name for a workspace\n- That workspace has the auto-join by domain feature enabled", "operationId": "join_api_v1_workspaces_join_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_fe5aa153" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUserView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/logo": { "post": { "tags": [ "Workspace" ], "summary": "Update Logo", "description": "Upload an image to be used as the workspace logo. Similar to a user\u2019s\navatar. If `delete` is set to true, it removes the logo completely and does\nnot return any `logo_*` attribute.", "operationId": "update_logo_api_v1_workspaces_logo_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_update_logo_api_v1_workspaces_logo_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSyncView" }, { "type": "null" } ], "title": "Response Update Logo Api V1 Workspaces Logo Post" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/{workspace_id}/users/{user_id}": { "delete": { "tags": [ "Workspace" ], "summary": "Remove Workspace User", "description": "Removes a user from a workspace.", "operationId": "remove_workspace_user_api_v1_workspaces__workspace_id__users__user_id__delete", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "ID of the workspace", "examples": [ 123456 ], "title": "Workspace Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer", "exclusiveMaximum": 18446744073709551616, "exclusiveMinimum": 0, "description": "ID of the workspace user", "examples": [ 123456 ], "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveWorkspaceUserResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Workspace" ], "summary": "Update Workspace User", "description": "Updates a workspace user's role.", "operationId": "update_workspace_user_api_v1_workspaces__workspace_id__users__user_id__post", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "ID of the workspace", "examples": [ 123456 ], "title": "Workspace Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer", "exclusiveMaximum": 18446744073709551616, "exclusiveMinimum": 0, "description": "ID of the workspace user", "examples": [ 123456 ], "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_51341cd2" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUserView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/templates/import_into_project_from_template_id": { "post": { "tags": [ "Templates" ], "summary": "Import Into Project From Template Id", "description": "Import a saved template into an existing project.\n\nThe target project must exist and must not be frozen. The response includes\nthe imported objects so clients can update local state immediately.", "operationId": "import_into_project_from_template_id_api_v1_templates_import_into_project_from_template_id_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_925d2d9b" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectImportResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/templates/import_into_project_from_file": { "post": { "tags": [ "Templates" ], "summary": "Import Into Project From File", "description": "A template can be imported in an existing project, or in a newly created one.\n\nUpload a file suitable to be passed as a template to be imported into a project.", "operationId": "import_into_project_from_file_api_v1_templates_import_into_project_from_file_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_import_into_project_from_file_api_v1_templates_import_into_project_from_file_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectImportResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "x-codeSamples": [ { "lang": "curl", "source": "\n$ curl https://api.todoist.com/api/v1/templates/import_into_project_from_file \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -F project_id=6XGgm6PHrGgMpCFX \\\n -F file=@example.csv\n" } ] } }, "/api/v1/templates/create_project_from_file": { "post": { "tags": [ "Templates" ], "summary": "Create Project From File", "description": "A template can be imported in an existing project, or in a newly created one.\n\nUpload a file suitable to be passed as a template to be imported into a project.", "operationId": "create_project_from_file_api_v1_templates_create_project_from_file_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_create_project_from_file_api_v1_templates_create_project_from_file_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectImportCreateResponseWithObjects" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "x-codeSamples": [ { "lang": "curl", "source": "\n$ curl https://api.todoist.com/api/v1/templates/create_project_from_file \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -F name=My Project \\\n -F file=@example.csv\n" } ] } }, "/api/v1/templates/file": { "get": { "tags": [ "Templates" ], "summary": "Export As File", "description": "Get a template for a project as a CSV file", "operationId": "export_as_file_api_v1_templates_file_get", "parameters": [ { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "description": "String ID of the project to export as a template.", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } }, { "name": "use_relative_dates", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to export due dates as relative dates.", "examples": [ true ], "default": true, "title": "Use Relative Dates" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/templates/url": { "get": { "tags": [ "Templates" ], "summary": "Export As Url", "description": "Get a template for a project as a shareable URL.\n\nThe URL can then be passed to `https://todoist.com/api/v1/import/project_from_url?t_url=`\nto make a shareable template.", "operationId": "export_as_url_api_v1_templates_url_get", "parameters": [ { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "description": "String ID of the project to export as a template URL.", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } }, { "name": "use_relative_dates", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to export due dates as relative dates.", "examples": [ true ], "default": true, "title": "Use Relative Dates" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileURLResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/payments/cancel_plan_with_redirect_to_stripe": { "post": { "tags": [ "Billing" ], "summary": "Cancel Plan With Redirect To Stripe", "description": "Start a hosted cancellation flow and return the redirect URL.", "operationId": "cancel_plan_with_redirect_to_stripe_api_v1_payments_cancel_plan_with_redirect_to_stripe_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_e4b32da9" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_BillingPortalUrlResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/payments/get_subscription_info": { "post": { "tags": [ "Billing" ], "summary": "Get Subscription Info", "description": "Return the current user's subscription state.", "operationId": "get_subscription_info_api_v1_payments_get_subscription_info_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionInfo" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/payments/reactivate_plan": { "post": { "tags": [ "Billing" ], "summary": "Reactivate Plan", "description": "Reactivate a previously canceled subscription.\n\nReturns the fresh `SubscriptionInfo` after reactivation so callers can\navoid a follow-up fetch. Raises `NO_CANCELABLE_SUBSCRIPTION` if there is\nno active subscription to reactivate.", "operationId": "reactivate_plan_api_v1_payments_reactivate_plan_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionInfo" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/projects/permissions": { "get": { "tags": [ "Projects" ], "summary": "Permissions", "description": "Returns a list of all the available roles and the associated actions they can\nperform in a project.", "operationId": "permissions_api_v1_projects_permissions_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleToActionMappingView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/projects/archived": { "get": { "tags": [ "Projects" ], "summary": "Get Archived", "description": "Get the user's archived projects.", "operationId": "get_archived_api_v1_projects_archived_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_AnyProjectSyncViewResponse_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/projects/search": { "get": { "tags": [ "Projects" ], "summary": "Search Projects", "description": "Search active user projects by name.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "search_projects_api_v1_projects_search_get", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Search query to match project names. Matching is case-insensitive. Queries are matched literally unless `*` (wildcard) is included. Use `\\*` for literal asterisk and `\\\\` for literal backslash.", "examples": [ "Inbox", "Client *", "Q* 2026", "Draft\\*" ], "title": "Query" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_AnyProjectSyncViewResponse_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/sections/search": { "get": { "tags": [ "Sections" ], "summary": "Search Sections", "description": "Search active sections by name, optionally filtered by project.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "search_sections_api_v1_sections_search_get", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Search query to match section names. Matching is case-insensitive. Queries are matched literally unless `*` (wildcard) is included. Use `\\*` for literal asterisk and `\\\\` for literal backslash.", "examples": [ "To Do", "Week *", "Q* 2026", "Draft\\*" ], "title": "Query" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the project to search sections from. If omitted or null, search sections from all projects.", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_SectionSyncView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/projects/{project_id}/collaborators": { "get": { "tags": [ "Projects" ], "summary": "Get Project Collaborators", "description": "Get all collaborators for a given project.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "get_project_collaborators_api_v1_projects__project_id__collaborators_get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the project", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } }, { "name": "public_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "description": "Public project access key.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, { "type": "null" } ], "title": "Public Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_Collaborator_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/projects/{project_id}/unarchive": { "post": { "tags": [ "Projects" ], "summary": "Unarchive Project", "description": "Marks a previously archived project as active again. For personal projects, this\nwill make the project visible again for the initiating user. For workspace projects,\nthis will make the project visible again for all applicable workspace users.", "operationId": "unarchive_project_api_v1_projects__project_id__unarchive_post", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the project", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnyProjectSyncViewResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/sections/{section_id}/unarchive": { "post": { "tags": [ "Sections" ], "summary": "Unarchive Section", "description": "Marks a section as active again.", "operationId": "unarchive_section_api_v1_sections__section_id__unarchive_post", "parameters": [ { "name": "section_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the section", "examples": [ "6fFPHV272WWh3gpW" ], "title": "Section Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/projects/{project_id}/archive": { "post": { "tags": [ "Projects" ], "summary": "Archive Project", "description": "Marks a project as archived. For personal projects, this will archive it just for\nthe initiating user (leaving it visible to any other collaborators). For workspace\nprojects, this will archive it for all workspace users, removing it from view.", "operationId": "archive_project_api_v1_projects__project_id__archive_post", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the project", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnyProjectSyncViewResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/sections/{section_id}/archive": { "post": { "tags": [ "Sections" ], "summary": "Archive Section", "description": "Marks a section as archived.", "operationId": "archive_section_api_v1_sections__section_id__archive_post", "parameters": [ { "name": "section_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the section", "examples": [ "6fFPHV272WWh3gpW" ], "title": "Section Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/projects/{project_id}/join": { "post": { "tags": [ "Projects" ], "summary": "Join", "description": "_Only used for workspaces_\n\nThis endpoint is used to join a workspace project by a workspace_user and\nis only usable by the workspace user.", "operationId": "join_api_v1_projects__project_id__join_post", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the workspace project to join.", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_GetDataV2Response" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/backups/download": { "get": { "tags": [ "Backups" ], "summary": "Download Backup", "description": "Download a backup archive.\n\nThis endpoint requires the `data:read_write` scope. The `backups:read`\nscope only grants access to `GET /api/v1/backups`.\n\nValidates that the requested backup belongs to the authenticated user and\nredirects to a signed CloudFront URL that expires after one minute.", "operationId": "download_backup_api_v1_backups_download_get", "parameters": [ { "name": "file", "in": "query", "required": true, "schema": { "type": "string", "description": "Backup file name returned in a backup download URL.", "examples": [ "12345678901234567890123456789012.zip" ], "title": "File" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/labels/search": { "get": { "tags": [ "Labels" ], "summary": "Search Labels", "description": "Search user labels by name.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "search_labels_api_v1_labels_search_get", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Search query to match label names. Matching is case-insensitive. Queries are matched literally unless `*` (wildcard) is included. Use `\\*` for literal asterisk and `\\\\` for literal backslash.", "examples": [ "urgent", "priority-*", "*-review", "5\\*" ], "title": "Query" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_LabelRestView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/labels/shared": { "get": { "tags": [ "Labels" ], "summary": "Shared Labels", "description": "Returns a set of unique strings containing [shared\nlabels](https://www.todoist.com/help/articles/introduction-to-labels-dSo2eE#h_01HE1NNWMV8MCXNVF10GT13ZEX)\nfrom active tasks.", "operationId": "shared_labels_api_v1_labels_shared_get", "parameters": [ { "name": "omit_personal", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to exclude the user's personal labels from the shared label names.", "examples": [ false ], "default": false, "title": "Omit Personal" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_str_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks/filter": { "get": { "tags": [ "Tasks" ], "summary": "Get Tasks By Filter", "description": "Get all tasks matching the filter.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "get_tasks_by_filter_api_v1_tasks_filter_get", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Filter by any [supported filter](https://todoist.com/help/articles/introduction-to-filters-V98wIH). Multiple filters (using the comma `,` operator) are not supported.", "examples": [ "today | overdue" ], "title": "Query" } }, { "name": "lang", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IETF language tag defining what language filter is written in, if differs from default English", "examples": [ "en", "de", "fr" ], "title": "Lang" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_ItemSyncView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks/quick": { "post": { "tags": [ "Tasks" ], "summary": "Quick Add", "description": "Add a new task using Quick Add with natural language processing.\n\nQuick Add allows creating tasks with rich metadata using natural language text.\nThis endpoint uses the same parsing engine as Todoist's official clients,\nsupporting dates, projects, labels, priorities, assignees, and more in a single\ntext string.\n\n## Basic Syntax Overview\n\n- **Due dates**: Natural language like `today`, `tomorrow at 5pm`, `next Monday`\n- **Projects**: `#ProjectName` (use `#My\\\\ Project` for names with spaces)\n- **Sections**: `/SectionName` (requires a project to be specified)\n- **Labels**: `@labelname` (multiple labels supported)\n- **Priority**: `p1` to `p4`, `P1` to `P4`, or `!!1` to `!!4`\n- **Assignees**: `+Name` (requires a project to be specified)\n- **Deadlines**: `{date expression}` (e.g., `{tomorrow}`, `{in 3 days}`)\n- **Reminders**: `!30m` (30 min before), `!1h` (1 hour before), `!0mb` (at due time),\n `!14:00` (absolute time), `!30 min before` (verbose, English only)\n- **Descriptions**: ` // description text` (must be at the end)\n\n## Examples\n\n- `\"Buy milk today at 5pm #Shopping @groceries p1\"`\n- `\"Team meeting next Monday at 10am #Work +JohnDoe !30m\"`\n- `\"Review PR {Friday} // Check the new authentication flow\"`\n- `\"Submit report tomorrow #Work /Urgent @important // Include Q3 metrics\"`\n\n## Important Notes\n\n- Natural language date parsing supports multiple languages based on account settings\n- If parsing fails for any element, the task is still created (with unparsed text\n remaining in the content)\n- Use the `meta` parameter to see detailed parsing results for debugging\n\nFor comprehensive documentation including all supported date formats, language\nsupport, and advanced syntax, see the\n[Quick Add help article](https://www.todoist.com/help/articles/use-task-quick-add-in-todoist-va4Lhpzz).", "operationId": "quick_add_api_v1_tasks_quick_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_40158d1f" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Quick Add Api V1 Tasks Quick Post" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks/{task_id}/reopen": { "post": { "tags": [ "Tasks" ], "summary": "Reopen Task", "description": "Reopens a task.\n\nAny ancestor tasks or sections will also be marked as uncomplete and\nrestored from history.\n\nThe reinstated tasks and sections will appear at the end of the list within\ntheir parent, after any previously active tasks.", "operationId": "reopen_task_api_v1_tasks__task_id__reopen_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks/{task_id}/close": { "post": { "tags": [ "Tasks" ], "summary": "Close Task", "description": "Closes a task.\n\nThe command performs in the same way as our official clients:\n\nRegular tasks are marked complete and moved to history, along with their\nsubtasks. Tasks with [recurring due\ndates](https://todoist.com/help/articles/introduction-to-recurring-dates-YUYVJJAV)\nwill be scheduled to their next occurrence.", "operationId": "close_task_api_v1_tasks__task_id__close_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks/{task_id}/move": { "post": { "tags": [ "Tasks" ], "summary": "Move Task", "description": "Moves task to another project, section or parent.", "operationId": "move_task_api_v1_tasks__task_id__move_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID of the task to move", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_02786f52" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/notification_setting": { "put": { "tags": [ "User" ], "summary": "Update Notification Setting", "description": "Update a notification delivery preference.\n\nThe API accepts the legacy `dont_notify` flag and stores the inverse as the\nuser's delivery preference for the requested notification type and channel.", "operationId": "update_notification_setting_api_v1_notification_setting_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_604e3e52" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "additionalProperties": { "type": "boolean" }, "type": "object" }, "type": "object", "title": "Response Update Notification Setting Api V1 Notification Setting Put", "description": "Notification delivery preferences keyed by notification type.", "examples": [ { "user_left_project": { "notify_push": true, "notify_email": true } } ] } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/location_reminders/{reminder_id}": { "delete": { "tags": [ "Location reminders" ], "summary": "Delete Location Reminder", "description": "Delete a location reminder by ID.", "operationId": "delete_location_reminder_api_v1_location_reminders__reminder_id__delete", "parameters": [ { "name": "reminder_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the location reminder", "examples": [ "6XGgmFQrx44wfGHr" ], "title": "Reminder Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Location reminders" ], "summary": "Get Location Reminder", "description": "Return a single location reminder by ID.", "operationId": "get_location_reminder_api_v1_location_reminders__reminder_id__get", "parameters": [ { "name": "reminder_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the location reminder", "examples": [ "6XGgmFQrx44wfGHr" ], "title": "Reminder Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationLocationSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Location reminders" ], "summary": "Update Location Reminder", "description": "Update an existing location reminder.", "operationId": "update_location_reminder_api_v1_location_reminders__reminder_id__post", "parameters": [ { "name": "reminder_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the location reminder", "examples": [ "6XGgmFQrx44wfGHr" ], "title": "Reminder Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_9c2f879b" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationLocationSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/location_reminders": { "post": { "tags": [ "Location reminders" ], "summary": "Create Location Reminder", "description": "Create a new location reminder for a task.", "operationId": "create_location_reminder_api_v1_location_reminders_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_4c96330f" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationLocationSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Location reminders" ], "summary": "Get Location Reminders", "description": "Get all active location reminders.\n\nOptionally filter by `task_id` to return only location reminders for a specific task.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination)\nfor details on using cursor-based pagination.", "operationId": "get_location_reminders_api_v1_location_reminders_get", "parameters": [ { "name": "task_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Task Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_NotificationLocationSyncView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/access_tokens": { "delete": { "tags": [ "Authorization" ], "summary": "Revoke Access Token Api", "description": "Revoke the access tokens obtained via OAuth", "operationId": "revoke_access_token_api_api_v1_access_tokens_delete", "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The unique Client ID of the Todoist application that you registered.", "examples": [ "0123456789abcdef" ], "title": "Client Id" } }, { "name": "client_secret", "in": "query", "required": true, "schema": { "type": "string", "description": "The unique Client Secret of the Todoist application that you registered.", "examples": [ "abcdef0123456789abcdef0123456789" ], "title": "Client Secret" } }, { "name": "access_token", "in": "query", "required": true, "schema": { "type": "string", "description": "Access token obtained from OAuth authentication.", "examples": [ "0123456789abcdef0123456789abcdef01234567" ], "title": "Access Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/id_mappings/{obj_name}/{obj_ids}": { "get": { "tags": [ "Ids" ], "summary": "Id Mappings", "description": "Translates IDs from v1 to v2 or vice versa.\n\nIDs are not unique across object types, hence the need to specify the object type.\n\nWhen V1 ids are provided, the function will return the corresponding V2\nids, if they exist, and vice versa.\n\nWhen no objects are found, an empty list is returned.", "operationId": "id_mappings_api_v1_id_mappings__obj_name___obj_ids__get", "parameters": [ { "name": "obj_name", "in": "path", "required": true, "schema": { "enum": [ "sections", "tasks", "comments", "reminders", "location_reminders", "projects" ], "type": "string", "description": "Object type for the IDs to translate.", "examples": [ "tasks" ], "title": "Obj Name" } }, { "name": "obj_ids", "in": "path", "required": true, "schema": { "type": "string", "description": "A comma-separated list of IDs", "examples": [ "6VfWjjjFg2xqX6Pa", "918273645", "6VfWjjjFg2xqX6Pa,6WMVPf8Hm8JP6mC8" ], "title": "Obj Ids" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IDMappingsMultipleResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces/{workspace_id}": { "delete": { "tags": [ "Workspace" ], "summary": "Delete Workspace", "description": "Deletes a workspace.", "operationId": "delete_workspace_api_v1_workspaces__workspace_id__delete", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "ID of the workspace", "examples": [ 123456 ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Workspace" ], "summary": "Get Workspace", "description": "Returns a workspace by ID.", "operationId": "get_workspace_api_v1_workspaces__workspace_id__get", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "ID of the workspace", "examples": [ 123456 ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Workspace Api V1 Workspaces Workspace Id Get" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Workspace" ], "summary": "Update Workspace", "description": "Updates an existing workspace and returns it.", "operationId": "update_workspace_api_v1_workspaces__workspace_id__post", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "description": "ID of the workspace", "examples": [ 123456 ], "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_b628cfc1" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Workspace Api V1 Workspaces Workspace Id Post" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/workspaces": { "get": { "tags": [ "Workspace" ], "summary": "Get Workspaces", "description": "Returns all workspaces where the user is a member.", "operationId": "get_workspaces_api_v1_workspaces_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Response Get Workspaces Api V1 Workspaces Get" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Workspace" ], "summary": "Create Workspace", "description": "Creates a new workspace and returns it.", "operationId": "create_workspace_api_v1_workspaces_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_e1a528d7" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Create Workspace Api V1 Workspaces Post" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/activities": { "get": { "tags": [ "Activity" ], "summary": "Get Activity Logs", "description": "Get activity logs.\n\nReturns a paginated list of activity events for the user. Events can be filtered by object\ntype (project, item, note, section), event type, and other criteria. Uses cursor-based\npagination for efficient navigation through results.", "operationId": "get_activity_logs_api_v1_activities_get", "parameters": [ { "name": "object_type", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "project", "item", "note", "section" ], "type": "string" }, { "type": "null" } ], "description": "The type of object to filter activities by. Must be one of \"project\", \"item\" (task), \"note\" (comment), or \"section\". When specified with `object_id`, returns activities for that specific object.", "examples": [ "item" ], "title": "Object Type" } }, { "name": "object_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ], "description": "The ID of the specific object to get activities for. Must be used together with `object_type`. For example, to get activities for a specific task, set `object_type=item` and `object_id=`.", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Object Id" } }, { "name": "parent_project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ], "description": "Filter activities to only those belonging to the specified project. Returns activities for the project itself and all its tasks and comments.", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Parent Project Id" } }, { "name": "parent_item_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ], "description": "Filter activities to only those belonging to the specified task. Returns activities for the task itself and all its comments.", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Parent Item Id" } }, { "name": "include_parent_object", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When `true` and `object_id` is specified, also include activities for the parent object. For example, when filtering by a specific task, also include activities for its parent project.", "examples": [ false ], "default": false, "title": "Include Parent Object" } }, { "name": "include_child_objects", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When `true` and `object_id` is specified, also include activities for all child objects. For example, when filtering by a project, also include activities for all its tasks and comments.", "examples": [ false ], "default": false, "title": "Include Child Objects" } }, { "name": "initiator_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": "integer" } }, { "type": "null" } ], "description": "Filter activities to only those initiated by the specified user ID(s). Accepts either a single user ID or a list of user IDs. Useful for shared projects to see who made which changes.", "examples": [ 123456 ], "title": "Initiator Id" } }, { "name": "initiator_id_null", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by whether the activity has an initiator. When `true`, returns only activities with no initiator (your own activities). When `false`, returns only activities initiated by collaborators.", "examples": [ false ], "title": "Initiator Id Null" } }, { "name": "event_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by a simple event type (e.g., \"added\", \"deleted\", \"completed\"). Returns events of this type across ALL object types that support it. Valid types: \"added\", \"deleted\", \"updated\", \"archived\", \"unarchived\", \"completed\", \"uncompleted\", \"shared\", \"left\", \"moved\". Prefix the value with `!` to negate the filter and return all events EXCEPT this type (e.g., \"!deleted\"). For more precise filtering by both object type and event type, use `object_event_types` instead.", "examples": [ "added", "deleted", "completed", "updated", "!deleted" ], "title": "Event Type" } }, { "name": "ensure_last_state", "in": "query", "required": false, "schema": { "type": "boolean", "description": "**Deprecated** - This parameter has no implementation and will be removed in a future version.", "examples": [ false ], "default": false, "title": "Ensure Last State" } }, { "name": "object_event_types", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Advanced filtering for specific object type and event type combinations. Format: `[\"object_type:event_type\"]`. Examples: `[\"item:deleted\"]` for deleted tasks, `[\"item:\"]` for all task events, `[\":deleted\"]` for all delete events across all types, `[\"item:deleted\", \"note:added\"]` for multiple filters. Valid event types: \"added\", \"deleted\", \"updated\", \"completed\", \"uncompleted\", \"archived\", \"unarchived\", \"shared\", \"left\", \"moved\". This is the recommended way to filter events.", "examples": [ [ "item:deleted" ], [ "item:", "note:added" ], [ ":deleted" ] ], "title": "Object Event Types" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, { "type": "null" } ], "description": "Filter activities by workspace. Accepts a single workspace ID, a list of workspace IDs, or `null` to filter for personal projects (projects not belonging to any workspace). Use `[null, 123]` to include both personal projects and workspace 123. When not set, returns activities from all workspaces and personal projects.", "examples": [ 123456 ], "title": "Workspace Id" } }, { "name": "annotate_notes", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When `true`, includes additional information about comments in the `extra_data` field, such as the content of the comment.", "examples": [ false ], "default": false, "title": "Annotate Notes" } }, { "name": "annotate_parents", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When `true`, includes additional information about parent objects in the `extra_data` field, such as the name of the parent project or task.", "examples": [ false ], "default": false, "title": "Annotate Parents" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "description": "Pagination cursor for fetching the next page of results. Use the value returned in the `next_cursor` field from a previous response.", "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter activities to only those that occurred on or after this date. Must be in ISO 8601 format (e.g. '2026-01-01T00:00:00Z'). When specified, overrides the default pagination behavior and allows custom date ranges.", "examples": [ "2026-01-01", "2026-01-01T00:00:00Z" ], "title": "Date From" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter activities to only those that occurred before this date (exclusive upper bound). Must be in ISO 8601 format (e.g. '2026-02-01T00:00:00Z'). When specified, overrides the default pagination behavior and allows custom date ranges.", "examples": [ "2026-02-01T00:00:00Z" ], "title": "Date To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_ActivityEvents_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "x-codeSamples": [ { "lang": "curl", "source": "\n# Get all deleted tasks\n$ curl --get https://api.todoist.com/api/v1/activities \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -d object_event_types='[\"item:deleted\"]'\n", "label": "Filter deleted tasks" }, { "lang": "curl", "source": "\n# Get all task events (added, deleted, completed, uncompleted, etc.)\n$ curl --get https://api.todoist.com/api/v1/activities \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -d object_event_types='[\"item:\"]'\n", "label": "All task events" }, { "lang": "curl", "source": "\n# Get all deleted events (tasks, projects, notes)\n$ curl --get https://api.todoist.com/api/v1/activities \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -d object_event_types='[\":deleted\"]'\n", "label": "All deleted events" }, { "lang": "curl", "source": "\n# Get deleted tasks and added notes\n$ curl --get https://api.todoist.com/api/v1/activities \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -d object_event_types='[\"item:deleted\", \"note:added\"]'\n", "label": "Multiple event types" } ] } }, "/api/v1/reminders/{reminder_id}": { "delete": { "tags": [ "Reminders" ], "summary": "Delete Reminder", "description": "Delete a reminder by ID.", "operationId": "delete_reminder_api_v1_reminders__reminder_id__delete", "parameters": [ { "name": "reminder_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the reminder", "examples": [ "6XGgmFQrx44wfGHr" ], "title": "Reminder Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Reminders" ], "summary": "Get Reminder", "description": "Return a single reminder by ID.", "operationId": "get_reminder_api_v1_reminders__reminder_id__get", "parameters": [ { "name": "reminder_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the reminder", "examples": [ "6XGgmFQrx44wfGHr" ], "title": "Reminder Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Reminders" ], "summary": "Update Reminder", "description": "Update an existing reminder.", "operationId": "update_reminder_api_v1_reminders__reminder_id__post", "parameters": [ { "name": "reminder_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the reminder", "examples": [ "6XGgmFQrx44wfGHr" ], "title": "Reminder Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_0d5e560b" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/reminders": { "post": { "tags": [ "Reminders" ], "summary": "Create Reminder", "description": "Create a new reminder for a task.\n\nFor **relative** reminders, provide `minute_offset` (minutes before the task's due time).\nFor **absolute** reminders, provide a `due` dictionary with a specific date/time.\nSupported `due` keys are `date` or `string`, with optional `lang`, `timezone`,\nand `is_recurring`.", "operationId": "create_reminder_api_v1_reminders_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_958e83bd" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Reminders" ], "summary": "Get Reminders", "description": "Get all active reminders.\n\nOptionally filter by `task_id` to return only reminders for a specific task.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination)\nfor details on using cursor-based pagination.", "operationId": "get_reminders_api_v1_reminders_get", "parameters": [ { "name": "task_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Task Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_NotificationSyncView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/projects/{project_id}": { "delete": { "tags": [ "Projects" ], "summary": "Delete Project", "description": "Deletes a project and all of its sections and tasks.", "operationId": "delete_project_api_v1_projects__project_id__delete", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the project", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Projects" ], "summary": "Get Project", "description": "Returns a project object related to the given ID", "operationId": "get_project_api_v1_projects__project_id__get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the project", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnyProjectSyncViewResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Projects" ], "summary": "Update Project", "description": "Updates a project and returns it.", "operationId": "update_project_api_v1_projects__project_id__post", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the project", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_cb8d28ec" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnyProjectSyncViewResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/sections/{section_id}": { "delete": { "tags": [ "Sections" ], "summary": "Delete Section", "description": "Delete the section and all of its tasks", "operationId": "delete_section_api_v1_sections__section_id__delete", "parameters": [ { "name": "section_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the section", "examples": [ "6fFPHV272WWh3gpW" ], "title": "Section Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Sections" ], "summary": "Get Section", "description": "Return the section for the given section ID", "operationId": "get_section_api_v1_sections__section_id__get", "parameters": [ { "name": "section_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the section", "examples": [ "6fFPHV272WWh3gpW" ], "title": "Section Id" } }, { "name": "public_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "description": "Public project access key.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, { "type": "null" } ], "title": "Public Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Sections" ], "summary": "Update Section", "description": "Update a section.", "operationId": "update_section_api_v1_sections__section_id__post", "parameters": [ { "name": "section_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the section", "examples": [ "6fFPHV272WWh3gpW" ], "title": "Section Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_163067b4" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/comments/{comment_id}": { "delete": { "tags": [ "Comments" ], "summary": "Delete Comment", "description": "Delete a comment by ID", "operationId": "delete_comment_api_v1_comments__comment_id__delete", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the comment", "examples": [ "6XGgmFQrx44wfGHr" ], "title": "Comment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Comments" ], "summary": "Get Comment", "description": "Returns a single comment by ID", "operationId": "get_comment_api_v1_comments__comment_id__get", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the comment", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Comment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Comments" ], "summary": "Update Comment", "description": "Update a comment by ID and returns its content", "operationId": "update_comment_api_v1_comments__comment_id__post", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the comment", "examples": [ "6XGgmFQrx44wfGHr" ], "title": "Comment Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_61d93e0e" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/NoteSyncView" }, { "type": "null" } ], "title": "Response Update Comment Api V1 Comments Comment Id Post" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/projects": { "post": { "tags": [ "Projects" ], "summary": "Create Project", "description": "Creates a new project and returns it", "operationId": "create_project_api_v1_projects_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_207bf8bc" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnyProjectSyncViewResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Projects" ], "summary": "Get Projects", "description": "Get all active user projects, optionally filtered by folder or workspace.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "get_projects_api_v1_projects_get", "parameters": [ { "name": "folder_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "description": "Numeric ID of the folder.", "examples": [ 1234 ] }, { "type": "null" } ], "description": "Filter projects to only those in this folder. If provided, workspace_id is ignored.", "title": "Folder Id" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "description": "Numeric ID of the workspace.", "examples": [ 123456 ] }, { "type": "null" } ], "description": "Filter projects to only those in this workspace. Ignored if folder_id is also provided.", "title": "Workspace Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_AnyProjectSyncViewResponse_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/sections": { "post": { "tags": [ "Sections" ], "summary": "Create Section", "description": "Create a new section", "operationId": "create_section_api_v1_sections_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_134c19e9" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Sections" ], "summary": "Get Sections", "description": "Get all active sections for the user, optionally filtered by project.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "get_sections_api_v1_sections_get", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the project to get sections from. If omitted or null, get sections from all projects.", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } }, { "name": "public_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "description": "Public project access key.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, { "type": "null" } ], "title": "Public Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_SectionSyncView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/comments": { "post": { "tags": [ "Comments" ], "summary": "Create Comment", "description": "Creates a new comment on a project or task and returns it.\n\nExactly one of `task_id` or `project_id` arguments is required. Providing\nneither or both will return an error.", "operationId": "create_comment_api_v1_comments_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_28d2b1b0" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "x-codeSamples": [ { "lang": "curl", "source": "\n$ cat > /tmp/note.json\n{\n \"task_id\": \"6X6WMMqgq2PWxjCX\",\n \"content\": \"Need one bottle of milk\",\n \"attachment\": {\n \"resource_type\": \"file\",\n \"file_url\": \"https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf\",\n \"file_type\": \"application/pdf\",\n \"file_name\": \"File.pdf\"\n }\n}\n^C\n\n$ curl \"https://api.todoist.com/api/v1/comments\" \\\n -X POST \\\n --data @/tmp/note.json \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Request-Id: $(uuidgen)\" \\\n -H \"Authorization: Bearer $token\"\n" } ] }, "get": { "tags": [ "Comments" ], "summary": "Get Comments", "description": "Get all comments for a given task or project.\n\nExactly one of `task_id` or `project_id` arguments is required. Providing\nneither or both will return an error.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "get_comments_api_v1_comments_get", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the project", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } }, { "name": "task_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Task Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } }, { "name": "public_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "description": "Public project access key.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, { "type": "null" } ], "title": "Public Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_NoteSyncView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/folders/{folder_id}": { "delete": { "tags": [ "Folders" ], "summary": "Delete Folder", "description": "Delete a folder. Projects in the folder will be moved out of it.", "operationId": "delete_folder_api_v1_folders__folder_id__delete", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "ID of the folder to delete.", "examples": [ 1234 ], "title": "Folder Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Folders" ], "summary": "Get Folder", "description": "Return the folder for the given folder ID.", "operationId": "get_folder_api_v1_folders__folder_id__get", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "ID of the folder to return.", "examples": [ 1234 ], "title": "Folder Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Folders" ], "summary": "Update Folder", "description": "Update an existing folder.", "operationId": "update_folder_api_v1_folders__folder_id__post", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "ID of the folder to update.", "examples": [ 1234 ], "title": "Folder Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_09503d19" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/backups": { "get": { "tags": [ "Backups" ], "summary": "Get Backups", "description": "Todoist creates a backup archive of users' data on a daily basis. Backup\narchives can also be accessed from the web app (Todoist Settings ->\nBackups).\n\nThis endpoint accepts the `backups:read` scope, the `data:read_write`\nscope, or a personal API token. The `backups:read` scope bypasses MFA and\nonly grants access to `GET /api/v1/backups`. When using `data:read_write`\nor a personal API token for an account with MFA enabled, the MFA token is\nrequired.", "operationId": "get_backups_api_v1_backups_get", "parameters": [ { "name": "mfa_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MFA token required when using a `data:read_write` token for an account with MFA enabled.", "examples": [ "123456" ], "title": "Mfa Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/_BackupResponse" }, "title": "Response Get Backups Api V1 Backups Get" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/uploads": { "delete": { "tags": [ "Uploads" ], "summary": "Delete Upload", "description": "Delete an uploaded file.\n\nThe file must belong to the authenticated user. Returns `FILE_NOT_FOUND`\nwhen the upload cannot be found.", "operationId": "delete_upload_api_v1_uploads_delete", "parameters": [ { "name": "file_url", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "URL of the uploaded file to delete.", "examples": [ "https://files.todoist.com/abc123/by/1234567/as/file.pdf" ], "title": "File Url" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "const": "ok", "type": "string", "title": "Response Delete Upload Api V1 Uploads Delete" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Uploads" ], "summary": "Upload File", "description": "Upload a file to Todoist.\n\nThis endpoint accepts file uploads via two methods:\n\n1. **Multipart form-data** (recommended):\n - Send the file as a form field with the actual file content\n - Optionally include `project_id` as another form field\n - The filename will be extracted from the Content-Disposition header\n\n2. **Raw binary stream**:\n - Send the file content directly in the request body\n - Set `Content-Type` header to the file's MIME type\n - Set `X-File-Name` header with the desired filename\n - Optionally include `project_id` as a query parameter\n\nThe optional `project_id` parameter can be used to apply workspace-specific\nupload limits when uploading to a workspace project.", "operationId": "upload_file_api_v1_uploads_post", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_file_api_v1_uploads_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResult" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "x-codeSamples": [ { "lang": "curl", "source": "\n$ curl https://api.todoist.com/api/v1/uploads \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -F file=@/path/to/file.pdf\n" }, { "lang": "curl", "source": "\n$ curl https://api.todoist.com/api/v1/uploads \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -H \"Content-Type: application/pdf\" \\\n -H \"X-File-Name: document.pdf\" \\\n --data-binary @/path/to/file.pdf\n" } ] } }, "/api/v1/folders": { "post": { "tags": [ "Folders" ], "summary": "Create Folder", "description": "Create a new folder in the given workspace.", "operationId": "create_folder_api_v1_folders_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_c04ca410" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Folders" ], "summary": "Get Folders", "description": "Get all folders for a workspace.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "get_folders_api_v1_folders_get", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "integer", "description": "ID of the workspace to list folders for.", "examples": [ 123456 ], "title": "Workspace Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_FolderSyncView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/labels/{label_id}": { "delete": { "tags": [ "Labels" ], "summary": "Delete Label", "description": "Deletes a personal label. All instances of the label will be removed from tasks", "operationId": "delete_label_api_v1_labels__label_id__delete", "parameters": [ { "name": "label_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "String ID of the label", "examples": [ "2147509004" ], "title": "Label Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Labels" ], "summary": "Get Label", "description": "Return a personal label by ID.\n\nReturns `NOT_FOUND` when the label does not exist or the ID is invalid.", "operationId": "get_label_api_v1_labels__label_id__get", "parameters": [ { "name": "label_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "String ID of the label", "examples": [ "2147509004" ], "title": "Label Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelRestView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Labels" ], "summary": "Update Label", "description": "Update a personal label.\n\nAt least one mutable field must be provided. Passing `null` for an optional\nfield keeps the existing value unchanged.", "operationId": "update_label_api_v1_labels__label_id__post", "parameters": [ { "name": "label_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "String ID of the label", "examples": [ "2147509004" ], "title": "Label Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_9c41452d" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelRestView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/emails": { "delete": { "tags": [ "Emails" ], "summary": "Email Disable", "description": "Disable the current email to a Todoist object", "operationId": "email_disable_api_v1_emails_delete", "parameters": [ { "name": "obj_type", "in": "query", "required": true, "schema": { "anyOf": [ { "$ref": "#/components/schemas/EmailObjectType" }, { "$ref": "#/components/schemas/EmailObjectTypePre9221" } ], "description": "Type of Todoist object whose email should be disabled.", "examples": [ "project", "project_comments", "task" ], "title": "Obj Type" } }, { "name": "obj_id", "in": "query", "required": true, "schema": { "type": "string", "description": "String ID of the Todoist object.", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Obj Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_StatusOkResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "put": { "tags": [ "Emails" ], "summary": "Email Get Or Create", "description": "Get or create an email to a Todoist object,\ncurrently only projects and tasks are supported.", "operationId": "email_get_or_create_api_v1_emails_put", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_0dc72dfd" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_EmailResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/labels": { "post": { "tags": [ "Labels" ], "summary": "Create Label", "description": "Create a personal label.\n\nPremium limits apply to personal label creation. Free users who exceed the\nplan limit receive a premium-only error.", "operationId": "create_label_api_v1_labels_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_38bb43e2" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelRestView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Labels" ], "summary": "Get Labels", "description": "Get all user labels.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "get_labels_api_v1_labels_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_LabelRestView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/revoke": { "post": { "tags": [ "Authorization" ], "summary": "Revoke Token Rfc7009 Compliant", "description": "Revoke an access token according to RFC 7009 OAuth Token Revocation.\n\nThis endpoint accepts form-encoded data and follows the OAuth 2.0 Token Revocation specification.\nThe client must authenticate using HTTP Basic authentication with their client credentials.\n\nAuthentication is performed via the Authorization header with the format:\nAuthorization: Basic base64(client_id:client_secret)", "operationId": "revoke_token_rfc7009_compliant_api_v1_revoke_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_8e7e8a3c" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks/{task_id}": { "delete": { "tags": [ "Tasks" ], "summary": "Delete Task", "description": "Delete a task and all of its subtasks.\n\nReturns `NOT_FOUND` when the task does not exist and `FORBIDDEN` when the\nauthenticated user cannot modify the task.", "operationId": "delete_task_api_v1_tasks__task_id__delete", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Tasks" ], "summary": "Get Task", "description": "Returns a single active (non-completed) task by ID", "operationId": "get_task_api_v1_tasks__task_id__get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Task Id" } }, { "name": "public_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "description": "Public project access key.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, { "type": "null" } ], "title": "Public Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "Tasks" ], "summary": "Update Task", "description": "Updates an existing task.", "operationId": "update_task_api_v1_tasks__task_id__post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ], "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_829067ab" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/tasks": { "post": { "tags": [ "Tasks" ], "summary": "Create Task", "description": "Create a new task.", "operationId": "create_task_api_v1_tasks_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_37565102" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemSyncView" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } }, "get": { "tags": [ "Tasks" ], "summary": "Get Tasks", "description": "Get all active tasks for the user.\n\nAll provided parameters are used to narrow down the list of tasks.\n\nThis is a paginated endpoint. See the [Pagination guide](#tag/Pagination) for details on using cursor-based pagination.", "operationId": "get_tasks_api_v1_tasks_get", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the project to get tasks from", "examples": [ "6XGgm6PHrGgMpCFX" ], "title": "Project Id" } }, { "name": "section_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the section to get tasks from", "examples": [ "6fFPHV272WWh3gpW" ], "title": "Section Id" } }, { "name": "parent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "String ID of the parent task to get sub-tasks from", "examples": [ "6fFPHRxcmVqm4C84" ], "title": "Parent Id" } }, { "name": "label", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter tasks by label name.", "examples": [ "next_action" ], "title": "Label" } }, { "name": "ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A list of the task IDs to retrieve, this should be a comma separated list", "examples": [ "6XGgmFVcrG5RRjVr,6fFPHV272WWh3gpW" ], "title": "Ids" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": "^[0-9a-zA-Z_-]+\\.[0-9a-zA-Z_-]+$", "description": "An opaque string used as the cursor for pagination. Must be used with the same parameters from the previous request", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0, "description": "The number of objects to return in a page", "examples": [ 50 ], "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList_ItemSyncView_" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/api/v1/user": { "get": { "tags": [ "User" ], "summary": "User Info", "description": "Get information about the currently authenticated user.\n\nThis is the OIDC userinfo endpoint. OAuth tokens of any product audience\nare accepted as long as they carry the `user:read` scope (implied by\n`data:read`).", "operationId": "user_info_api_v1_user_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserJSON" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } } }, "components": { "schemas": { "APIColorID": { "anyOf": [ { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, { "type": "integer", "enum": [ 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49 ] } ], "examples": [ "charcoal" ] }, "AcquisitionSource": { "type": "string", "const": "high_paid_channel" }, "ActionView": { "properties": { "name": { "type": "string", "title": "Name", "description": "Permission action name.", "examples": [ "UPDATE_ITEM" ] } }, "type": "object", "required": [ "name" ], "title": "ActionView" }, "ActivityEvents": { "properties": { "object_type": { "$ref": "#/components/schemas/ActivityObjectType", "description": "The type of object this activity relates to. Valid values are `\"project\"`, `\"item\"`, `\"note\"`, or `\"section\"`.", "examples": [ "item" ] }, "object_id": { "anyOf": [ { "type": "string", "description": "The unique identifier of the object this activity relates to (project, item, note, or section ID).", "examples": [ "6XGgmFVcrG5RRjVr" ] }, { "type": "string" } ], "title": "Object Id" }, "v2_object_id": { "type": "string", "title": "V2 Object Id", "description": "String ID of the object this activity relates to.", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "event_type": { "type": "string", "title": "Event Type", "description": "The type of event that occurred. Valid values are: `\"added\"` (object was created), `\"deleted\"` (object was removed), `\"updated\"` (object was modified), `\"archived\"` (object was archived), `\"unarchived\"` (object was restored from archive), `\"completed\"` (task was completed), `\"uncompleted\"` (task was marked as incomplete), `\"shared\"` (project was shared with a user), `\"left\"` (user left a shared project), `\"moved\"` (task was moved between projects or between sections).", "examples": [ "completed" ] }, "event_date": { "type": "string", "format": "date-time", "title": "Event Date", "description": "The timestamp when this activity occurred.", "examples": [ "2025-02-12T12:00:00Z" ] }, "id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Id", "description": "The internal unique identifier for this activity log entry.", "examples": [ 123456789 ] }, "parent_project_id": { "anyOf": [ { "type": "string", "description": "The ID of the project that contains the object this activity relates to. For project activities, this is the project itself. For item and note activities, this is the project containing the item or note.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, { "type": "null" } ], "title": "Parent Project Id" }, "v2_parent_project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "V2 Parent Project Id", "description": "String ID of the parent project for this activity.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "parent_item_id": { "anyOf": [ { "type": "string", "description": "For note (comment) activities, the ID of the item (task) that the note is attached to. `null` for project and item activities.", "examples": [ "6XGgmFVcrG5RRjVr" ] }, { "type": "null" } ], "title": "Parent Item Id" }, "v2_parent_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "V2 Parent Item Id", "description": "String ID of the parent task for comment activities.", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "initiator_id": { "anyOf": [ { "type": "string", "description": "The ID of the user who is responsible for the event, which only makes sense in shared projects, items and notes, and is `null` for non-shared objects.", "examples": [ "123456" ] }, { "type": "null" } ], "title": "Initiator Id" }, "extra_data_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Extra Data Id", "description": "Internal ID for the extra activity data row.", "examples": [ 123456789 ] }, "extra_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Extra Data", "description": "This object contains at least the `name` of the project, or the `content` of an item or comment, and optionally the `last_name` if a project was renamed, the `last_content` if an item or note was renamed, the `due_date` and `last_due_date` if an item's due date changed, the `responsible_uid` and `last_responsible_uid` if an item's responsible uid changed, the `description` and `last_description` if an item's description changed, the `priority` and `last_priority` if an item's priority changed, the `deadline` and `last_deadline` if an item's deadline changed, the `duration`, `last_duration`, `duration_unit`, and `last_duration_unit` if an item's duration changed, the `source_project_id` and `destination_project_id` if a task was moved between projects, the `section_id` on completion snapshots and section-move events, the `last_section_id` on section-move events indicating the previous section, and the `client` that caused the logging of the event", "examples": [ { "content": "Buy milk" } ] } }, "type": "object", "required": [ "object_type", "object_id", "v2_object_id", "event_type", "event_date" ], "title": "ActivityEvents" }, "ActivityObjectType": { "type": "string", "enum": [ "project", "item", "note", "section" ] }, "AnyProjectSyncViewResponse": { "anyOf": [ { "$ref": "#/components/schemas/PersonalProjectSyncView" }, { "$ref": "#/components/schemas/WorkspaceProjectSyncView" } ], "title": "Project object", "description": "Can be either a personal or a workspace project." }, "Body_02786f52": { "properties": { "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id", "description": "ID of the project to move the task to", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "section_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Section Id", "description": "ID of the section to move the task to", "examples": [ "6fFPHV272WWh3gpW" ] }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "ID of the parent task to move the task under", "examples": [ "6fFPHRxcmVqm4C84" ] } }, "type": "object", "title": "Body" }, "Body_0680de45": { "properties": { "name": { "type": "string", "title": "Name", "description": "Shared label name to remove from matching tasks.", "examples": [ "waiting" ] } }, "type": "object", "required": [ "name" ], "title": "Body" }, "Body_09503d19": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Updated folder name. Passing null or omitting this field will leave it unchanged.", "examples": [ "Design" ] }, "default_order": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Default Order", "description": "Updated default position of the folder. Passing null or omitting this field will leave it unchanged.", "examples": [ 1 ] } }, "type": "object", "title": "Body" }, "Body_0d5e560b": { "properties": { "minute_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Minute Offset", "description": "Minutes before due time to trigger (for relative reminders).", "examples": [ 30 ] }, "due": { "anyOf": [ { "$ref": "#/components/schemas/ReminderDueAttribute" }, { "type": "null" } ], "description": "Due date dictionary for absolute reminders.", "examples": [ { "date": "2025-02-12T09:00:00", "lang": "en", "timezone": "Europe/Madrid" } ] }, "service": { "anyOf": [ { "$ref": "#/components/schemas/ReminderServiceType", "description": "Notification service type: 'email', 'push'.", "examples": [ "email" ] }, { "$ref": "#/components/schemas/Undefined" } ], "title": "Service" }, "is_urgent": { "$ref": "#/components/schemas/UpdateReminderIsUrgentAttribute" } }, "type": "object", "title": "Body" }, "Body_0dc72dfd": { "properties": { "obj_type": { "$ref": "#/components/schemas/EmailObjectType", "description": "Type of Todoist object to create an email for.", "examples": [ "project", "project_comments", "task" ] }, "obj_id": { "type": "string", "title": "Obj Id", "description": "String ID of the Todoist object.", "examples": [ "6XGgm6PHrGgMpCFX" ] } }, "type": "object", "required": [ "obj_type", "obj_id" ], "title": "Body" }, "Body_108b7f01": { "properties": { "email_list": { "anyOf": [ { "items": { "type": "string", "format": "email" }, "type": "array" }, { "type": "null" } ], "title": "Email List", "description": "List of user emails to invite to the workspace.", "examples": [ [ "teammate@example.com" ] ] }, "role": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceRole" }, { "type": "null" } ], "description": "Role assigned to invited users.", "examples": [ "MEMBER" ] } }, "type": "object", "title": "Body" }, "Body_134c19e9": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the new section.", "examples": [ "Groceries" ] }, "project_id": { "type": "string", "title": "Project Id", "description": "ID of the project to add the section to", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "order": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Order", "description": "Position of the new section in the project", "examples": [ 12 ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the new section.", "examples": [ "Tasks for the launch plan" ] } }, "type": "object", "required": [ "name", "project_id" ], "title": "Body" }, "Body_163067b4": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Updated section name. Passing null or omitting this field will leave it unchanged.", "examples": [ "Groceries" ] }, "section_order": { "anyOf": [ { "type": "integer", "maximum": 2147483647.0, "minimum": -2147483648.0 }, { "type": "null" } ], "title": "Section Order", "description": "Updated position of the section in the project. Passing null or omitting this field will leave it unchanged.", "examples": [ 12 ] }, "is_collapsed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Collapsed", "description": "Updated collapsed state of the section. Passing null or omitting this field will leave it unchanged.", "examples": [ true ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Updated section description. Pass null to clear the value. Omit this field to keep it unchanged.", "examples": [ "Tasks for the launch plan" ] } }, "type": "object", "title": "Body" }, "Body_207bf8bc": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Name of the project.", "examples": [ "Vacation Planning" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the project.", "examples": [ "Tasks for planning the trip." ] }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "Parent project ID. If provided, creates this project as a sub-project", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "color": { "$ref": "#/components/schemas/APIColorID", "description": "Color of the project icon.", "default": "charcoal" }, "is_favorite": { "type": "boolean", "title": "Is Favorite", "description": "Whether the project is a favorite for the user.", "default": false, "examples": [ false ] }, "view_style": { "anyOf": [ { "$ref": "#/components/schemas/ProjectViewStyleV1" }, { "type": "null" } ], "description": "View style of the project.", "examples": [ "list" ] }, "workspace_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Workspace Id", "description": "Workspace ID. If provided, creates a workspace project instead of a personal project.", "examples": [ 123456 ] } }, "type": "object", "required": [ "name" ], "title": "Body" }, "Body_28d2b1b0": { "properties": { "content": { "type": "string", "maxLength": 15000, "minLength": 1, "title": "Content", "description": "Content of the comment", "examples": [ "Need one bottle of milk" ] }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id", "description": "String ID of the project", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id", "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "attachment": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Attachment", "description": "A [File attachment](#tag/Sync/Comments/File-Attachments) object", "examples": [ { "file_name": "File.pdf", "file_type": "application/pdf", "file_url": "https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf", "resource_type": "file" } ] }, "uids_to_notify": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Uids To Notify", "description": "Optional list of user IDs to notify about this comment.", "examples": [ [ 12345678, 23456789 ] ] } }, "type": "object", "required": [ "content" ], "title": "Body" }, "Body_37565102": { "properties": { "content": { "type": "string", "minLength": 1, "title": "Content", "description": "Task content.", "examples": [ "Buy milk" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Task description.", "examples": [ "Pick up two liters of whole milk." ] }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id", "description": "ID of the project to add the task to. If omitted or null, the task will be added to the user's Inbox.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "section_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Section Id", "description": "ID of the section to add the task to", "examples": [ "6fFPHV272WWh3gpW" ] }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "ID of the parent task", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "order": { "anyOf": [ { "type": "integer", "maximum": 2147483647.0, "minimum": -2147483648.0 }, { "type": "null" } ], "title": "Order", "description": "Position of the task in the project or section", "examples": [ 12 ] }, "labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Labels", "description": "List of label names.", "examples": [ [ "errands", "shopping" ] ] }, "priority": { "anyOf": [ { "type": "integer", "maximum": 4.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Priority", "description": "Task priority (1-4, where 1 is highest)", "examples": [ 2 ] }, "assignee_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Assignee Id", "description": "ID of the user to assign the task to. To find User IDs, use [Get user](#operation/user_info_api_v1_user_get) for your own ID or [Get all collaborators](#operation/get_project_collaborators_api_v1_projects__project_id__collaborators_get) for project members.", "examples": [ 123456789 ] }, "due_string": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due String", "description": "Human-readable representation of the due date. See the [Due dates](#tag/Due-dates) section for more details.", "examples": [ "tomorrow at 12:00" ] }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due Date", "description": "Due date in RFC 3339 format or similar. See the [Due dates](#tag/Due-dates) section for more details.", "examples": [ "2025-02-12" ] }, "due_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due Datetime", "description": "Due date and time. See the [Due dates](#tag/Due-dates) section for more details.", "examples": [ "2025-02-12T12:00:00Z" ] }, "due_lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due Lang", "description": "Due date language code. See the [Due dates](#tag/Due-dates) section for more details.", "examples": [ "en" ] }, "duration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration", "description": "Task duration, in either minutes or days. Only used if `duration_unit` is also provided.", "examples": [ 30 ] }, "duration_unit": { "anyOf": [ { "type": "string", "enum": [ "minute", "day" ] }, { "type": "null" } ], "title": "Duration Unit", "description": "Unit of time for duration.", "examples": [ "minute" ] }, "deadline_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date", "title": "Deadline Date", "description": "Deadline date in YYYY-MM-DD format", "examples": [ "2025-02-12" ] } }, "type": "object", "required": [ "content" ], "title": "Body" }, "Body_38bb43e2": { "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name", "description": "Name of the new label.", "examples": [ "Priority" ] }, "order": { "anyOf": [ { "type": "integer", "maximum": 32767.0, "minimum": -32768.0 }, { "type": "null" } ], "title": "Order", "description": "Position of the new label in the label list", "examples": [ 12 ] }, "color": { "$ref": "#/components/schemas/APIColorID", "description": "Label color.", "default": "charcoal", "examples": [ "berry_red" ] }, "is_favorite": { "type": "boolean", "title": "Is Favorite", "description": "Whether the label is marked as a favorite.", "default": false, "examples": [ false ] } }, "type": "object", "required": [ "name" ], "title": "Body" }, "Body_40158d1f": { "properties": { "text": { "type": "string", "title": "Text", "description": "The text of the task to parse using Quick Add syntax. See the endpoint description for supported syntax elements.", "examples": [ "Buy milk today #Shopping @groceries p1", "Meeting tomorrow at 2pm #Work +Jane", "Call dentist next week !!1", "Review PR {Friday} // Check the authentication flow", "Submit report #Work /Urgent @important // Include Q3 metrics" ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note", "description": "A note to attach to the task. The note content is added as a comment on the created task. If the user's plan does not support comments, this parameter is ignored.", "examples": [ "Remember to check the expiration date", "Meeting notes: Discuss Q4 goals" ] }, "reminder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reminder", "description": "A reminder date in natural language format, similar to due date parsing. If the user's plan does not support reminders, this parameter is ignored. If the reminder text cannot be parsed, it is silently ignored.", "examples": [ "tomorrow at 9am", "in 2 hours", "next Monday at 10am" ] }, "auto_reminder": { "type": "boolean", "title": "Auto Reminder", "description": "When 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](#tag/Sync/User) for more info about the default reminder.", "default": false, "examples": [ false ] }, "meta": { "type": "boolean", "title": "Meta", "description": "When enabled, the response includes a `meta` object containing the detailed parsing results. This shows exactly how the Quick Add text was interpreted, including which project, labels, due date, priority, etc. were detected. Useful for debugging parsing behavior or building integrations that need to understand how text was parsed.", "default": false, "examples": [ false ] } }, "type": "object", "required": [ "text" ], "title": "Body" }, "Body_4c96330f": { "properties": { "task_id": { "$ref": "#/components/schemas/LocationReminderTaskIDAttribute" }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Name of the location", "examples": [ "Home" ] }, "loc_lat": { "type": "string", "maxLength": 20, "minLength": 1, "title": "Loc Lat", "description": "Latitude of the location", "examples": [ "37.7749" ] }, "loc_long": { "type": "string", "maxLength": 20, "minLength": 1, "title": "Loc Long", "description": "Longitude of the location", "examples": [ "-122.4194" ] }, "loc_trigger": { "type": "string", "enum": [ "on_enter", "on_leave" ], "title": "Loc Trigger", "description": "Trigger type: 'on_enter' or 'on_leave'", "examples": [ "on_enter" ] }, "radius": { "type": "integer", "maximum": 255.0, "minimum": 1.0, "title": "Radius", "description": "Radius in meters (default 100, max 255)", "default": 100, "examples": [ 100 ] } }, "type": "object", "required": [ "task_id", "name", "loc_lat", "loc_long", "loc_trigger" ], "title": "Body" }, "Body_51341cd2": { "properties": { "role": { "$ref": "#/components/schemas/WorkspaceRole", "description": "Updated role for the user.", "examples": [ "ADMIN" ] } }, "type": "object", "required": [ "role" ], "title": "Body" }, "Body_52bab197": { "properties": { "workspace_id": { "type": "integer", "title": "Workspace Id", "description": "ID of the workspace containing the invitation.", "examples": [ 123456 ] }, "user_email": { "type": "string", "title": "User Email", "description": "Email address of the invited user.", "examples": [ "teammate@example.com" ] } }, "type": "object", "required": [ "workspace_id", "user_email" ], "title": "Body" }, "Body_604e3e52": { "properties": { "notification_type": { "$ref": "#/components/schemas/NotificationType", "description": "Notification type to update.", "examples": [ "workspace_invitation_created" ] }, "service": { "$ref": "#/components/schemas/NotificationChannel", "description": "Notification channel to update.", "examples": [ "email" ] }, "dont_notify": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Dont Notify", "description": "Whether notifications should be disabled for the selected type and channel.", "examples": [ true ] } }, "type": "object", "required": [ "notification_type", "service" ], "title": "Body" }, "Body_61d93e0e": { "properties": { "content": { "anyOf": [ { "type": "string", "maxLength": 15000, "minLength": 1 }, { "type": "null" } ], "title": "Content", "description": "New content for the comment. If null or an empty string, no update is performed.", "examples": [ "Need two bottles of milk" ] } }, "type": "object", "required": [ "content" ], "title": "Body" }, "Body_6ec83bd4": { "properties": { "name": { "type": "string", "title": "Name", "description": "Current shared label name to rename.", "examples": [ "waiting" ] }, "new_name": { "type": "string", "title": "New Name", "description": "New shared label name to apply to matching tasks.", "examples": [ "follow-up" ] } }, "type": "object", "required": [ "name", "new_name" ], "title": "Body" }, "Body_829067ab": { "properties": { "content": { "type": "string", "title": "Content", "description": "Updated task content. Omit this field to keep it unchanged.", "examples": [ "Buy milk" ] }, "description": { "type": "string", "title": "Description", "description": "Updated task description. Omit this field to keep it unchanged.", "examples": [ "Pick up two liters of whole milk." ] }, "labels": { "items": { "type": "string" }, "type": "array", "title": "Labels", "description": "Updated list of label names. Omit this field to keep it unchanged.", "examples": [ [ "errands", "shopping" ] ] }, "priority": { "type": "integer", "maximum": 4.0, "minimum": 1.0, "title": "Priority", "description": "Updated task priority (1-4, where 1 is highest). Omit this field to keep it unchanged.", "examples": [ 2 ] }, "due_string": { "type": "string", "title": "Due String", "description": "Updated human-readable representation of the due date. See the [Due dates](#tag/Due-dates) section for more details. Omit this field to keep it unchanged.", "examples": [ "tomorrow at 12:00" ] }, "due_date": { "type": "string", "title": "Due Date", "description": "Updated due date in RFC 3339 format or similar. See the [Due dates](#tag/Due-dates) section for more details. Omit this field to keep it unchanged.", "examples": [ "2025-02-12" ] }, "due_datetime": { "type": "string", "title": "Due Datetime", "description": "Updated due date and time. See the [Due dates](#tag/Due-dates) section for more details. Omit this field to keep it unchanged.", "examples": [ "2025-02-12T12:00:00Z" ] }, "due_lang": { "type": "string", "title": "Due Lang", "description": "Updated due date language code. See the [Due dates](#tag/Due-dates) section for more details. Omit this field to keep it unchanged.", "examples": [ "en" ] }, "assignee_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Assignee Id", "description": "ID of the user to assign the task to. To find User IDs, use [Get user](#operation/user_info_api_v1_user_get) for your own ID or [Get all collaborators](#operation/get_project_collaborators_api_v1_projects__project_id__collaborators_get) for project members. Pass null to clear the value. Omit this field to keep it unchanged.", "examples": [ 123456789 ] }, "duration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration", "description": "Updated task duration, in either minutes or days. Only used if `duration_unit` is also provided. Pass null to clear the value. Omit this field to keep it unchanged.", "examples": [ 30 ] }, "duration_unit": { "anyOf": [ { "type": "string", "enum": [ "minute", "day" ] }, { "type": "null" } ], "title": "Duration Unit", "description": "Unit of time for duration. Must be provided to update the task duration. Pass null to clear the value. Omit this field to keep it unchanged.", "examples": [ "minute" ] }, "deadline_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date", "title": "Deadline Date", "description": "Updated deadline date in YYYY-MM-DD format. Pass null to clear the value. Omit this field to keep it unchanged.", "examples": [ "2025-02-12" ] }, "child_order": { "type": "integer", "maximum": 2147483647.0, "minimum": -2147483648.0, "title": "Child Order", "description": "Updated position of the task in its current scope. Omit this field to keep it unchanged.", "examples": [ 12 ] }, "is_collapsed": { "type": "boolean", "title": "Is Collapsed", "description": "Updated collapsed state of the task for the current user. Omit this field to keep it unchanged.", "examples": [ false ] }, "day_order": { "type": "integer", "maximum": 2147483647.0, "minimum": -2147483648.0, "title": "Day Order", "description": "Updated position of the task in Today and Upcoming views. Omit this field to keep it unchanged.", "examples": [ 3 ] } }, "type": "object", "title": "Body" }, "Body_8e7e8a3c": { "properties": { "token": { "type": "string", "title": "Token", "description": "The token to be revoked (access token).", "examples": [ "0123456789abcdef0123456789abcdef01234567" ] }, "token_type_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Type Hint", "description": "A hint about the type of the token being revoked (optional). Expected value: 'access_token'", "examples": [ "access_token" ] } }, "type": "object", "required": [ "token" ], "title": "Body" }, "Body_925d2d9b": { "properties": { "project_id": { "type": "string", "title": "Project Id", "description": "String ID of the project to import the template into.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "template_id": { "type": "string", "title": "Template Id", "description": "ID of the saved template to import.", "examples": [ "123456" ] }, "locale": { "type": "string", "title": "Locale", "description": "Locale to use for localized template content.", "default": "en", "examples": [ "en" ] } }, "type": "object", "required": [ "project_id", "template_id" ], "title": "Body" }, "Body_958e83bd": { "properties": { "task_id": { "$ref": "#/components/schemas/ReminderTaskIDAttribute" }, "reminder_type": { "type": "string", "enum": [ "relative", "absolute" ], "title": "Reminder Type", "description": "Type of the reminder: 'relative' or 'absolute'", "default": "relative", "examples": [ "relative" ] }, "minute_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Minute Offset", "description": "Minutes before due time to trigger (for relative reminders)", "examples": [ 30 ] }, "due": { "anyOf": [ { "$ref": "#/components/schemas/ReminderDueAttribute" }, { "type": "null" } ], "description": "Due date dictionary for absolute reminders.", "examples": [ { "date": "2025-02-12T09:00:00", "lang": "en", "timezone": "Europe/Madrid" } ] }, "service": { "anyOf": [ { "$ref": "#/components/schemas/ReminderServiceTypeAttribute" }, { "$ref": "#/components/schemas/Undefined" } ], "title": "Service" }, "is_urgent": { "$ref": "#/components/schemas/ReminderIsUrgentAttribute", "default": false } }, "type": "object", "required": [ "task_id" ], "title": "Body" }, "Body_999fd79a": { "properties": { "client_id": { "type": "string", "title": "Client Id", "description": "The unique Client ID of the Todoist application that you registered.", "examples": [ "0123456789abcdef" ] }, "client_secret": { "type": "string", "title": "Client Secret", "description": "The unique Client Secret of the Todoist application that you registered.", "examples": [ "abcdef0123456789abcdef0123456789" ] }, "personal_token": { "type": "string", "title": "Personal Token", "description": "Token obtained from the email/password authentication.", "examples": [ "0123456789abcdef0123456789abcdef01234567" ] }, "scope": { "type": "string", "title": "Scope", "description": "Scopes of the OAuth token. Please refer to the [Authorization](#tag/Authorization) guide for the detailed list of available scopes.", "examples": [ "data:read_write" ] } }, "type": "object", "required": [ "client_id", "client_secret", "personal_token", "scope" ], "title": "Body" }, "Body_9c2f879b": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Name of the location. If not provided (or null), the value remains unchanged.", "examples": [ "Office" ] }, "loc_lat": { "anyOf": [ { "type": "string", "maxLength": 20, "minLength": 1 }, { "type": "null" } ], "title": "Loc Lat", "description": "Latitude of the location. If not provided (or null), the value remains unchanged.", "examples": [ "40.416775" ] }, "loc_long": { "anyOf": [ { "type": "string", "maxLength": 20, "minLength": 1 }, { "type": "null" } ], "title": "Loc Long", "description": "Longitude of the location. If not provided (or null), the value remains unchanged.", "examples": [ "-3.703790" ] }, "loc_trigger": { "anyOf": [ { "type": "string", "enum": [ "on_enter", "on_leave" ] }, { "type": "null" } ], "title": "Loc Trigger", "description": "Trigger type: 'on_enter' or 'on_leave'. If not provided (or null), the value remains unchanged.", "examples": [ "on_enter" ] }, "radius": { "anyOf": [ { "type": "integer", "maximum": 255.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Radius", "description": "Radius in meters. If not provided (or null), the value remains unchanged.", "examples": [ 100 ] } }, "type": "object", "title": "Body" }, "Body_9c41452d": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Updated label name. Passing null or omitting this field will leave it unchanged.", "examples": [ "Priority" ] }, "order": { "anyOf": [ { "type": "integer", "maximum": 32767.0, "minimum": -32768.0 }, { "type": "null" } ], "title": "Order", "description": "Position of the label in the label list. Passing null or omitting this field will leave it unchanged.", "examples": [ 12 ] }, "color": { "anyOf": [ { "$ref": "#/components/schemas/APIColorID" }, { "type": "null" } ], "description": "Label color. Passing null or omitting this field will leave it unchanged.", "examples": [ "berry_red" ] }, "is_favorite": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Favorite", "description": "Whether the label is marked as a favorite. Passing null or omitting this field will leave it unchanged.", "examples": [ true ] } }, "type": "object", "title": "Body" }, "Body_b48755ce": { "properties": { "amount": { "type": "integer", "title": "Amount", "description": "Amount to buy, in the currency's minor unit (1000 = $10.00).", "examples": [ 1000 ] }, "currency": { "type": "string", "title": "Currency", "description": "ISO currency code.", "examples": [ "usd" ] }, "return_url": { "type": "string", "title": "Return Url", "description": "URL Checkout returns the user to.", "examples": [ "https://todoist.com/app/settings/automations" ] } }, "type": "object", "required": [ "amount", "currency", "return_url" ], "title": "Body" }, "Body_b628cfc1": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Updated workspace name. Passing null or omitting this field will leave it unchanged.", "examples": [ "Design Team" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Updated workspace description. Passing null or omitting this field will leave it unchanged.", "examples": [ "Workspace for design projects." ] }, "is_link_sharing_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Link Sharing Enabled", "description": "Updated link sharing status. Passing null or omitting this field will leave it unchanged.", "examples": [ true ] }, "is_guest_allowed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Guest Allowed", "description": "Updated guest access status. Passing null or omitting this field will leave it unchanged.", "examples": [ true ] }, "domain_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Name", "description": "Updated workspace email domain. Passing null or omitting this field will leave it unchanged.", "examples": [ "example.com" ] }, "domain_discovery": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Domain Discovery", "description": "Updated domain discovery setting. Passing null or omitting this field will leave it unchanged.", "examples": [ false ] }, "restrict_email_domains": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Restrict Email Domains", "description": "Updated email domain restriction setting. Passing null or omitting this field will leave it unchanged.", "examples": [ false ] }, "properties": { "anyOf": [ { "$ref": "#/components/schemas/PublicWorkspaceProperties" }, { "type": "null" } ], "description": "Updated workspace properties. Passing null or omitting this field will leave it unchanged.", "examples": [ {} ] }, "is_trial_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Trial Pending", "description": "Updated trial pending state. Passing null or omitting this field will leave it unchanged.", "examples": [ false ] }, "invite_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invite Code", "description": "Regenerate workspace invite code when set. Passing null or omitting this field will leave it unchanged.", "examples": [ "regenerate" ] }, "is_collapsed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Collapsed", "description": "Updated collapse state for current user. Passing null or omitting this field will leave it unchanged.", "examples": [ false ] } }, "type": "object", "title": "Body" }, "Body_c04ca410": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the new folder.", "examples": [ "Design" ] }, "workspace_id": { "type": "integer", "title": "Workspace Id", "description": "ID of the workspace to create the folder in.", "examples": [ 123456 ] }, "default_order": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Default Order", "description": "Default position of the folder in the workspace.", "examples": [ 1 ] }, "child_order": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Child Order", "description": "User-specific position of the folder.", "examples": [ 1 ] } }, "type": "object", "required": [ "name", "workspace_id" ], "title": "Body" }, "Body_cb8d28ec": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Updated project name. Passing null or omitting this field will leave it unchanged.", "examples": [ "Vacation Planning" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Updated project description. Passing null or omitting this field will leave it unchanged.", "examples": [ "Tasks for planning the trip." ] }, "color": { "anyOf": [ { "$ref": "#/components/schemas/APIColorID" }, { "type": "null" } ], "description": "Updated project color. Passing null or omitting this field will leave it unchanged.", "examples": [ "charcoal" ] }, "is_favorite": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Favorite", "description": "Whether the project is marked as a favorite. Passing null or omitting this field will leave it unchanged.", "examples": [ true ] }, "view_style": { "anyOf": [ { "$ref": "#/components/schemas/ProjectViewStyleV1" }, { "type": "null" } ], "description": "Updated project view style. Passing null or omitting this field will leave it unchanged.", "examples": [ "board" ] }, "child_order": { "anyOf": [ { "type": "integer", "maximum": 2147483647.0, "minimum": -2147483648.0 }, { "type": "null" } ], "title": "Child Order", "description": "Updated position of the project in the hierarchy. Only supported for personal projects. Passing null or omitting this field will leave it unchanged.", "examples": [ 12 ] }, "is_collapsed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Collapsed", "description": "Whether the project is collapsed. Passing null or omitting this field will leave it unchanged.", "examples": [ false ] }, "folder_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0.0, "description": "Numeric ID of the folder.", "examples": [ 1234 ] }, { "type": "null" } ], "title": "Folder Id", "description": "Folder to move the project into. Only supported for workspace projects. Pass null to clear the value. Omit this field to keep it unchanged." } }, "type": "object", "title": "Body" }, "Body_create_project_from_file_api_v1_templates_create_project_from_file_post": { "properties": { "name": { "type": "string", "title": "Name" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "name", "file" ], "title": "Body_create_project_from_file_api_v1_templates_create_project_from_file_post" }, "Body_e1a528d7": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Name of the workspace.", "examples": [ "Design Team" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the workspace.", "examples": [ "Workspace for design projects." ] }, "is_link_sharing_enabled": { "type": "boolean", "title": "Is Link Sharing Enabled", "description": "Whether link sharing is enabled for the workspace.", "default": true, "examples": [ true ] }, "is_guest_allowed": { "type": "boolean", "title": "Is Guest Allowed", "description": "Whether guests are allowed in the workspace.", "default": true, "examples": [ true ] }, "domain_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Name", "description": "Workspace email domain.", "examples": [ "example.com" ] }, "domain_discovery": { "type": "boolean", "title": "Domain Discovery", "description": "Whether users with matching email domains can discover this workspace.", "default": false, "examples": [ false ] }, "restrict_email_domains": { "type": "boolean", "title": "Restrict Email Domains", "description": "Whether workspace invites are restricted to workspace domain.", "default": false, "examples": [ false ] }, "properties": { "anyOf": [ { "$ref": "#/components/schemas/PublicWorkspaceProperties" }, { "type": "null" } ], "description": "Workspace properties.", "examples": [ {} ] }, "is_trial_pending": { "type": "boolean", "title": "Is Trial Pending", "description": "Whether the workspace is waiting for trial confirmation.", "default": false, "examples": [ false ] } }, "type": "object", "title": "Body" }, "Body_e4b32da9": { "properties": { "reason_flag": { "type": "string", "title": "Reason Flag", "description": "Short identifier of the cancellation reason category.", "default": "", "examples": [ "too_expensive" ] }, "reason_description": { "type": "string", "title": "Reason Description", "description": "Human-readable label of the cancellation reason.", "default": "", "examples": [ "It's too expensive for me" ] }, "reason_text": { "type": "string", "title": "Reason Text", "description": "Free-form feedback from the user about the cancellation.", "default": "", "examples": [ "I no longer use it daily." ] }, "return_url": { "type": "string", "title": "Return Url", "description": "URL the user is redirected to after completing the flow.", "default": "", "examples": [ "https://todoist.com/app/settings/subscription" ] } }, "type": "object", "title": "Body" }, "Body_fe5aa153": { "properties": { "invite_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invite Code", "description": "Workspace invite code to join with. Provide either `invite_code` or `workspace_id`, not both.", "examples": [ "26d332457f16dc67f18385194be148f62c2b4317" ] }, "workspace_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Workspace Id", "description": "Workspace ID to join by verified email domain. Provide either `invite_code` or `workspace_id`, not both.", "examples": [ 123456 ] } }, "type": "object", "title": "Body" }, "Body_import_into_project_from_file_api_v1_templates_import_into_project_from_file_post": { "properties": { "project_id": { "type": "string", "title": "Project Id" }, "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "project_id", "file" ], "title": "Body_import_into_project_from_file_api_v1_templates_import_into_project_from_file_post" }, "Body_update_logo_api_v1_workspaces_logo_post": { "properties": { "workspace_id": { "type": "integer", "title": "Workspace Id" }, "delete": { "type": "boolean", "title": "Delete", "default": false }, "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "workspace_id", "file" ], "title": "Body_update_logo_api_v1_workspaces_logo_post" }, "Body_upload_file_api_v1_uploads_post": { "properties": { "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_file_api_v1_uploads_post" }, "Collaborator": { "properties": { "id": { "type": "string", "title": "Id", "description": "The user's ID", "examples": [ "0192837465" ] }, "name": { "type": "string", "title": "Name", "description": "The user's full name", "examples": [ "John Smith" ] }, "email": { "type": "string", "title": "Email", "description": "The user's email address", "examples": [ "email@example.org" ] } }, "type": "object", "required": [ "id", "name", "email" ], "title": "Collaborator" }, "CollaboratorRole": { "type": "string", "enum": [ "CREATOR", "ADMIN", "READ_WRITE", "EDIT_ONLY", "COMPLETE_ONLY" ], "title": "CollaboratorRole", "description": "User role in the project. For personal project the role should be always \"CREATOR\"\nUser role for projects v1 maybe specified as \"CREATOR\" or \"ADMIN\", because in the\npast there was no permissions.", "x-enumDescriptions": { "ADMIN": "Admin", "COMPLETE_ONLY": "Complete Only", "CREATOR": "Creator", "EDIT_ONLY": "Edit Only", "READ_WRITE": "Read Write" } }, "CreatedPlatform": { "type": "string", "enum": [ "web", "ios", "android" ] }, "CreatorRole": { "type": "string", "enum": [ "owner_founder", "leader", "individual_contributor" ] }, "DailyCompletionItem": { "properties": { "date": { "type": "string", "format": "date", "title": "Date", "description": "Date for this daily completion data (ISO 8601 format: YYYY-MM-DD)", "examples": [ "2025-02-12" ] }, "items": { "items": { "$ref": "#/components/schemas/ProjectCompletedItem" }, "type": "array", "title": "Items", "description": "Per-project completion breakdown for this day", "examples": [ [ { "completed": 3, "id": "6XGgm6PHrGgMpCFX" } ] ] }, "total_completed": { "type": "integer", "title": "Total Completed", "description": "Total number of tasks completed across all projects on this day", "examples": [ 3 ] } }, "type": "object", "required": [ "date", "items", "total_completed" ], "title": "DailyCompletionItem", "description": "Completion statistics for a single day." }, "DefaultAccessLevel": { "type": "string", "enum": [ "restricted", "team" ] }, "DefaultCollaboratorsSyncView": { "properties": { "user_ids": { "items": { "type": "integer" }, "type": "array", "title": "User Ids" }, "predefined_group_ids": { "items": { "type": "string" }, "type": "array", "title": "Predefined Group Ids" } }, "type": "object", "title": "DefaultCollaboratorsSyncView", "description": "Client representation of default collaborators within a workspace.\nSplit into 2 lists rather than using the polymorphic original\nWorkspaceDefaultCollaboratorView." }, "Department": { "type": "string", "enum": [ "administration", "customer_service", "finance_accounting", "human_resources", "information_technology", "legal", "marketing", "operations", "product_development", "research_development", "sales", "supply_chain_management", "engineering", "quality_assurance", "executive_management", "other" ] }, "DesktopWorkspaceModal": { "type": "string", "enum": [ "TRIAL_OFFER" ], "title": "DesktopWorkspaceModal", "description": "Enum to indicate when desktop should show workspace modal", "x-enumDescriptions": { "TRIAL_OFFER": "Trial Offer" } }, "EmailObjectType": { "type": "string", "enum": [ "project", "project_comments", "task" ], "title": "EmailObjectType", "x-enumDescriptions": { "project": "Project", "project_comments": "Project Comments", "task": "Task" } }, "EmailObjectTypePre9221": { "type": "string", "enum": [ "project", "project_comments", "item" ], "title": "EmailObjectTypePre9221", "x-enumDescriptions": { "item": "Item", "project": "Project", "project_comments": "Project Comments" } }, "ExposedCollaborator": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the collaborator.", "examples": [ "123456" ] }, "full_name": { "type": "string", "title": "Full Name", "description": "Full name of the collaborator.", "examples": [ "Ada Lovelace" ] }, "email": { "type": "string", "title": "Email", "description": "Email address of the collaborator.", "examples": [ "ada@example.com" ] }, "timezone": { "type": "string", "title": "Timezone", "description": "Timezone of the collaborator.", "examples": [ "Europe/London" ] }, "image_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Id", "description": "Avatar image ID for the collaborator.", "examples": [ null ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the collaborator has been deleted.", "default": false, "examples": [ false ] } }, "type": "object", "required": [ "id", "full_name", "email", "timezone", "image_id" ], "title": "ExposedCollaborator", "description": "A project collaborator, as exposed in sync and REST API responses." }, "FileURLResponse": { "properties": { "file_name": { "type": "string", "title": "File Name", "description": "Name of the exported template file.", "examples": [ "Project.csv" ] }, "file_url": { "type": "string", "format": "uri", "title": "File Url", "description": "Temporary URL for downloading the exported template.", "examples": [ "https://example.com/Project.csv" ] } }, "type": "object", "required": [ "file_name", "file_url" ], "title": "FileURLResponse" }, "FolderSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the folder.", "examples": [ "1234" ] }, "name": { "type": "string", "title": "Name", "description": "Folder name.", "examples": [ "Design" ] }, "workspace_id": { "type": "string", "title": "Workspace Id", "description": "String ID of the workspace that contains the folder.", "examples": [ "123456" ] }, "default_order": { "type": "integer", "title": "Default Order", "description": "Default position of the folder in the workspace.", "examples": [ 1 ] }, "child_order": { "type": "integer", "title": "Child Order", "description": "User-specific position of the folder.", "examples": [ 1 ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the folder is deleted.", "examples": [ false ] } }, "type": "object", "required": [ "id", "name", "workspace_id", "default_order", "child_order", "is_deleted" ], "title": "FolderSyncView" }, "FolderView": { "properties": { "workspace_id": { "type": "string", "title": "Workspace Id", "description": "String ID of the workspace that contains the folder.", "examples": [ "123456" ] }, "name": { "type": "string", "title": "Name", "description": "Folder name.", "default": "", "examples": [ "Design" ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the folder is deleted.", "default": false, "examples": [ false ] }, "id": { "type": "string", "title": "Id", "description": "String ID of the folder.", "default": "0", "examples": [ "1234" ] }, "default_order": { "type": "integer", "title": "Default Order", "description": "Default position of the folder in the workspace.", "default": 0, "examples": [ 1 ] }, "child_order": { "type": "integer", "title": "Child Order", "description": "User-specific position of the folder.", "default": 0, "examples": [ 1 ] } }, "type": "object", "required": [ "workspace_id" ], "title": "FolderView" }, "FormattedPrice": { "properties": { "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code.", "examples": [ "USD" ] }, "unit_amount": { "type": "integer", "title": "Unit Amount", "description": "Price amount in the currency's smallest unit.", "examples": [ 600 ] }, "tax_behavior": { "type": "string", "title": "Tax Behavior", "description": "Tax behavior for the price.", "examples": [ "exclusive" ] } }, "type": "object", "required": [ "currency", "unit_amount", "tax_behavior" ], "title": "FormattedPrice" }, "FormattedPriceListing": { "properties": { "billing_cycle": { "type": "string", "enum": [ "monthly", "yearly" ], "title": "Billing Cycle", "description": "Billing cycle for the listed prices.", "examples": [ "monthly" ] }, "prices": { "items": { "$ref": "#/components/schemas/FormattedPrice" }, "type": "array", "title": "Prices", "description": "Prices available for the billing cycle.", "examples": [ [ { "currency": "USD", "tax_behavior": "exclusive", "unit_amount": 600 } ] ] } }, "type": "object", "required": [ "billing_cycle", "prices" ], "title": "FormattedPriceListing" }, "GoalsSettings": { "properties": { "user": { "type": "string", "title": "User", "description": "User ID (legacy field, same as user_id)", "examples": [ "1234567" ] }, "user_id": { "type": "string", "title": "User Id", "description": "User ID", "examples": [ "1234567" ] }, "daily_goal": { "type": "integer", "title": "Daily Goal", "description": "Daily task completion goal set by the user", "examples": [ 5 ] }, "weekly_goal": { "type": "integer", "title": "Weekly Goal", "description": "Weekly task completion goal set by the user", "examples": [ 25 ] }, "ignore_days": { "items": { "type": "integer" }, "type": "array", "title": "Ignore Days", "description": "List of weekday numbers (0=Sunday, 1=Monday, ..., 6=Saturday) excluded from daily goals", "examples": [ [ 6, 0 ] ] }, "vacation_mode": { "type": "integer", "title": "Vacation Mode", "description": "Vacation mode status (0=disabled, 1=enabled)", "examples": [ 0 ] }, "karma_disabled": { "type": "integer", "title": "Karma Disabled", "description": "Karma tracking status (0=enabled, 1=disabled)", "examples": [ 0 ] }, "current_daily_streak": { "$ref": "#/components/schemas/StreakInfo", "description": "Current consecutive daily completion streak", "examples": [ { "count": 5, "end": "2025-02-14", "start": "2025-02-10" } ] }, "current_weekly_streak": { "$ref": "#/components/schemas/StreakInfo", "description": "Current consecutive weekly completion streak", "examples": [ { "count": 2, "end": "2025-02-16", "start": "2025-02-03" } ] }, "last_daily_streak": { "$ref": "#/components/schemas/StreakInfo", "description": "Previous daily streak (before the current one)", "examples": [ { "count": 3, "end": "2025-01-22", "start": "2025-01-20" } ] }, "last_weekly_streak": { "$ref": "#/components/schemas/StreakInfo", "description": "Previous weekly streak (before the current one)", "examples": [ { "count": 1, "end": "2025-01-26", "start": "2025-01-20" } ] }, "max_daily_streak": { "$ref": "#/components/schemas/StreakInfo", "description": "Longest daily streak achieved by the user", "examples": [ { "count": 10, "end": "2025-01-10", "start": "2025-01-01" } ] }, "max_weekly_streak": { "$ref": "#/components/schemas/StreakInfo", "description": "Longest weekly streak achieved by the user", "examples": [ { "count": 4, "end": "2025-01-28", "start": "2025-01-01" } ] } }, "type": "object", "required": [ "user", "user_id", "daily_goal", "weekly_goal", "ignore_days", "vacation_mode", "karma_disabled", "current_daily_streak", "current_weekly_streak", "last_daily_streak", "last_weekly_streak", "max_daily_streak", "max_weekly_streak" ], "title": "GoalsSettings", "description": "User goals and settings." }, "GraphPoint": { "properties": { "date": { "type": "string", "title": "Date", "description": "Date for the karma data point in YYYY-MM-DD format.", "examples": [ "2025-02-12" ] }, "karma_avg": { "type": "integer", "title": "Karma Avg", "description": "Average karma score for this date.", "examples": [ 1024 ] } }, "type": "object", "required": [ "date", "karma_avg" ], "title": "GraphPoint", "description": "Historical karma data point for graphing." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Hdyhau": { "type": "string", "enum": [ "friend", "social_media", "ai_chatbot", "search_engine", "app_store", "other" ] }, "IDMapping": { "properties": { "old_id": { "anyOf": [ { "$ref": "#/components/schemas/V1orV2IDStr" }, { "type": "null" } ], "description": "Legacy ID for the object.", "examples": [ "918273645" ] }, "new_id": { "anyOf": [ { "$ref": "#/components/schemas/V1orV2IDStr" }, { "type": "null" } ], "description": "Curent ID for the object.", "examples": [ "6VfWjjjFg2xqX6Pa" ] } }, "type": "object", "required": [ "old_id", "new_id" ], "title": "IDMapping" }, "IDMappingsMultipleResponse": { "items": { "$ref": "#/components/schemas/IDMapping" }, "type": "array" }, "Industry": { "type": "string", "enum": [ "agriculture", "arts_entertainment", "automotive", "banking_financial_services", "construction", "consulting", "consumer_goods", "education", "energy_utilities", "food_beverages", "government_public_sector", "healthcare_life_sciences", "information_technology", "insurance", "legal_services", "manufacturing", "media_communications", "non_profit", "pharmaceuticals", "real_estate", "retail_wholesale", "telecommunications", "transportation_logistics", "travel_hospitality", "other" ] }, "IntendedTeamSize": { "type": "string", "enum": [ "size_1", "size_2_to_10", "size_11_to_50", "more_than_50", "size_2_to_7", "size_8_to_15", "size_16_to_24", "more_than_25" ] }, "InviteWorkspaceUsersResponse": { "properties": { "invited_emails": { "items": { "type": "string" }, "type": "array", "title": "Invited Emails", "description": "Emails successfully invited to the workspace.", "examples": [ [ "teammate@example.com" ] ] } }, "type": "object", "required": [ "invited_emails" ], "title": "InviteWorkspaceUsersResponse" }, "ItemNoteSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the comment.", "examples": [ "6XGgmFQrx44wfGHr" ] }, "posted_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Posted Uid", "description": "String ID of the user who posted the comment.", "examples": [ "1234567" ] }, "content": { "type": "string", "title": "Content", "description": "Comment content.", "default": "", "examples": [ "Looks good to me." ] }, "file_attachment": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "items": {}, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "File Attachment", "description": "File attachment metadata, or `null` when the comment has no attachment.", "examples": [ null ] }, "uids_to_notify": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Uids To Notify", "description": "String IDs of users notified by the comment.", "examples": [ [ "1234567" ] ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the comment is deleted.", "examples": [ false ] }, "posted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Posted At", "description": "Date and time when the comment was posted, or `null` if unknown.", "examples": [ "2025-01-15T10:30:00Z" ] }, "reactions": { "anyOf": [ { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Reactions", "description": "Reaction emoji mapped to user IDs that reacted.", "examples": [ { "\ud83d\udc4d": [ "1234567" ] } ] }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Item Id" } }, "type": "object", "required": [ "id", "posted_uid", "file_attachment", "uids_to_notify", "is_deleted", "posted_at", "reactions", "item_id" ], "title": "ItemNoteSyncView", "description": "A representation of an Item Note View, extending the base class NoteSyncView,\nto be returned to clients in a sync (or sync-like) response." }, "ItemSyncView": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "String ID of the user who owns the task.", "examples": [ "1234567" ] }, "id": { "type": "string", "title": "Id", "description": "String ID of the task.", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "project_id": { "type": "string", "title": "Project Id", "description": "String ID of the project that contains the task.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "section_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Section Id", "description": "String ID of the section that contains the task, or `null` if the task is not in a section.", "examples": [ "6fFPHV272WWh3gpW" ] }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "String ID of the parent task, or `null` if this is a top-level task.", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "added_by_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Added By Uid", "description": "String ID of the user who created the task, or `null` if unknown.", "examples": [ "1234567" ] }, "assigned_by_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned By Uid", "description": "String ID of the user who assigned the task, or `null` if unassigned.", "examples": [ "1234567" ] }, "responsible_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Responsible Uid", "description": "String ID of the user responsible for the task, or `null` if unassigned.", "examples": [ "1234567" ] }, "labels": { "items": { "type": "string" }, "type": "array", "title": "Labels", "description": "Names of labels attached to the task.", "examples": [ [ "priority" ] ] }, "deadline": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Deadline", "description": "Deadline details for the task, or `null` when the task has no deadline.", "examples": [ { "date": "2025-02-12", "lang": "en" } ] }, "duration": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "object" }, { "type": "null" } ], "title": "Duration", "description": "Task duration details, or `null` when the task has no duration.", "examples": [ { "amount": 30, "unit": "minute" } ] }, "is_collapsed": { "type": "boolean", "title": "Is Collapsed", "description": "Whether the task is collapsed in the user's view.", "examples": [ false ] }, "checked": { "type": "boolean", "title": "Checked", "description": "Whether the task is completed.", "examples": [ false ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the task is deleted.", "examples": [ false ] }, "added_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Added At", "description": "Date and time when the task was created, or `null` if unknown.", "examples": [ "2025-01-15T10:30:00Z" ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Completed At", "description": "Date and time when the task was completed, or `null` if active.", "examples": [ "2025-01-16T10:30:00Z" ] }, "completed_by_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed By Uid", "description": "String ID of the user who completed the task, or `null` if active.", "examples": [ "1234567" ] }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Updated At", "description": "Date and time when the task was last updated, or `null` if unknown.", "examples": [ "2025-01-17T10:30:00Z" ] }, "due": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Due", "description": "Due date details for the task, or `null` when the task has no due date.", "examples": [ { "date": "2025-02-12", "is_recurring": false, "lang": "en", "string": "tomorrow" } ] }, "priority": { "type": "integer", "title": "Priority", "description": "Task priority from 1 (normal) to 4 (urgent).", "examples": [ 1 ] }, "child_order": { "type": "integer", "title": "Child Order", "description": "Position of the task among sibling tasks.", "examples": [ 1 ] }, "content": { "type": "string", "title": "Content", "description": "Task content.", "examples": [ "Buy milk" ] }, "description": { "type": "string", "title": "Description", "description": "Task description.", "examples": [ "Pick up organic milk" ] }, "note_count": { "type": "integer", "title": "Note Count", "description": "**Deprecated**: only returns 0 and is marked for removal.", "examples": [ 0 ] }, "day_order": { "type": "integer", "title": "Day Order", "description": "Task order for day-based views.", "examples": [ 1 ] }, "completed_count": { "type": "integer", "title": "Completed Count", "description": "Number of times the task has been marked as completed. Increments on every completion, including recurring occurrences and re-completions of a previously reopened task. Decremented when a recurring completion is undone.", "examples": [ 3 ] }, "postponed_count": { "type": "integer", "title": "Postponed Count", "description": "Number of times the task's due date has been rescheduled by the user. Increments on any due-date change between two set dates (forward or backward); recurring completions and undos are not counted.", "examples": [ 1 ] } }, "type": "object", "required": [ "user_id", "id", "project_id", "section_id", "parent_id", "added_by_uid", "assigned_by_uid", "responsible_uid", "labels", "deadline", "duration", "is_collapsed", "checked", "is_deleted", "added_at", "completed_at", "completed_by_uid", "updated_at", "due", "priority", "child_order", "content", "description", "note_count", "day_order", "completed_count", "postponed_count" ], "title": "ItemSyncView", "description": "A class with fields representing an ItemView which will be returned to\nclients in a sync (or sync-like) response." }, "KarmaUpdateReasonEntry": { "properties": { "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Time", "description": "Timestamp when this karma update occurred (ISO 8601 datetime)", "examples": [ "2025-02-12T10:30:00Z" ] }, "new_karma": { "type": "number", "title": "New Karma", "description": "New total karma score after this update", "examples": [ 1024.0 ] }, "positive_karma": { "type": "number", "title": "Positive Karma", "description": "Amount of karma gained in this update", "examples": [ 1.0 ] }, "negative_karma": { "type": "number", "title": "Negative Karma", "description": "Amount of karma lost in this update (negative value)", "examples": [ 0.0 ] }, "positive_karma_reasons": { "items": { "$ref": "#/components/schemas/PositiveKarmaReason" }, "type": "array", "title": "Positive Karma Reasons", "description": "List of reason codes for karma gains. Values: 1=Tasks added, 2=Tasks completed, 3=Advanced features, 4=Signup, 5=Beta upgrade, 6=Support activity, 7=Premium upgrade, 8=Getting started, 9=Daily goal reached, 10=Weekly goal reached", "examples": [ [ 2, 9 ] ] }, "negative_karma_reasons": { "items": { "$ref": "#/components/schemas/NegativeKarmaReason" }, "type": "array", "title": "Negative Karma Reasons", "description": "List of reason codes for karma losses. Values: 50=Tasks overdue, 51=Tasks postponed, 52=Is inactive", "examples": [ [ 50 ] ] } }, "type": "object", "required": [ "new_karma", "positive_karma", "negative_karma", "positive_karma_reasons", "negative_karma_reasons" ], "title": "KarmaUpdateReasonEntry", "description": "Karma update event with reasons and amounts." }, "LabelRestView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the label.", "examples": [ "2147509004" ] }, "name": { "type": "string", "title": "Name", "description": "Label name.", "examples": [ "Priority" ] }, "color": { "type": "string", "title": "Color", "description": "Label color name.", "examples": [ "berry_red" ] }, "order": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Order", "description": "Position of the label in the label list, or `null` when no explicit order is set.", "examples": [ 12 ] }, "is_favorite": { "type": "boolean", "title": "Is Favorite", "description": "Whether the label is marked as a favorite.", "examples": [ false ] } }, "type": "object", "required": [ "id", "name", "color", "order", "is_favorite" ], "title": "LabelRestView" }, "LocationReminderTaskIDAttribute": { "type": "string", "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "MemberView": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "String ID of the workspace member.", "examples": [ "1234567" ] }, "workspace_id": { "type": "string", "title": "Workspace Id", "description": "String ID of the workspace.", "examples": [ "123456" ] }, "user_email": { "type": "string", "title": "User Email", "description": "Email address of the workspace member.", "examples": [ "example@email.org" ] }, "full_name": { "type": "string", "title": "Full Name", "description": "Full name of the workspace member.", "examples": [ "Dain Ironfoot" ] }, "timezone": { "type": "string", "title": "Timezone", "description": "Timezone of the workspace member.", "examples": [ "Europe/Madrid" ] }, "role": { "$ref": "#/components/schemas/WorkspaceRole", "description": "Workspace role assigned to the member.", "examples": [ "MEMBER" ] }, "image_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Id", "description": "Avatar image ID of the workspace member, or `null`.", "examples": [ "abc123" ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the workspace member is deleted.", "default": false, "examples": [ false ] } }, "type": "object", "required": [ "user_id", "workspace_id", "user_email", "full_name", "timezone", "role" ], "title": "MemberView" }, "NegativeKarmaReason": { "type": "integer", "enum": [ 50, 51, 52 ], "title": "NegativeKarmaReason", "description": "Reasons why karma can decrease.", "x-enumDescriptions": { "50": "Tasks Overdue", "51": "Tasks Postponed", "52": "Is Inactive" } }, "NoteSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the comment.", "examples": [ "6XGgmFQrx44wfGHr" ] }, "posted_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Posted Uid", "description": "String ID of the user who posted the comment.", "examples": [ "1234567" ] }, "content": { "type": "string", "title": "Content", "description": "Comment content.", "default": "", "examples": [ "Looks good to me." ] }, "file_attachment": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "items": {}, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "File Attachment", "description": "File attachment metadata, or `null` when the comment has no attachment.", "examples": [ null ] }, "uids_to_notify": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Uids To Notify", "description": "String IDs of users notified by the comment.", "examples": [ [ "1234567" ] ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the comment is deleted.", "examples": [ false ] }, "posted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Posted At", "description": "Date and time when the comment was posted, or `null` if unknown.", "examples": [ "2025-01-15T10:30:00Z" ] }, "reactions": { "anyOf": [ { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Reactions", "description": "Reaction emoji mapped to user IDs that reacted.", "examples": [ { "\ud83d\udc4d": [ "1234567" ] } ] } }, "type": "object", "required": [ "id", "posted_uid", "file_attachment", "uids_to_notify", "is_deleted", "posted_at", "reactions" ], "title": "NoteSyncView", "description": "The base class for NoteSyncViews, to be extended for Items and Projects.\n\nThis class should generally not be instantiated directly, as it serves as a\ncommon structure for Items and Projects." }, "NotificationChannel": { "type": "string", "enum": [ "email", "push" ], "title": "NotificationChannel", "description": "Which communication mechanism is being used to send this notification", "x-enumDescriptions": { "email": "Email", "push": "Push" } }, "NotificationLocationSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the location reminder", "examples": [ "6XGgmFQrx44wfGHr" ] }, "item_id": { "type": "string", "title": "Item Id", "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "project_id": { "type": "string", "title": "Project Id", "description": "String ID of the project containing the task", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "notify_uid": { "type": "string", "title": "Notify Uid", "description": "String ID of the user who will receive the reminder", "examples": [ "1029384756" ] }, "name": { "type": "string", "title": "Name", "description": "Name of the location", "examples": [ "Home" ] }, "loc_lat": { "type": "string", "title": "Loc Lat", "description": "Latitude of the location", "examples": [ "37.7749" ] }, "loc_long": { "type": "string", "title": "Loc Long", "description": "Longitude of the location", "examples": [ "-122.4194" ] }, "loc_trigger": { "type": "string", "enum": [ "on_enter", "on_leave" ], "title": "Loc Trigger", "description": "Trigger type for the location reminder", "examples": [ "on_enter" ] }, "radius": { "type": "integer", "title": "Radius", "description": "Radius in meters", "examples": [ 100 ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the location reminder is deleted", "examples": [ false ] }, "type": { "type": "string", "const": "location", "title": "Type", "description": "The reminder type", "default": "location", "examples": [ "location" ] } }, "type": "object", "required": [ "id", "item_id", "project_id", "notify_uid", "name", "loc_lat", "loc_long", "loc_trigger", "radius", "is_deleted" ], "title": "NotificationLocationSyncView", "description": "A class with fields representing a NotificationLocationView which will be\nreturned to clients in a sync-like response." }, "NotificationSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the reminder.", "examples": [ "6XGgmFQrx44wfGHr" ] }, "item_id": { "type": "string", "title": "Item Id", "description": "String ID of the task that owns the reminder.", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "notify_uid": { "type": "string", "title": "Notify Uid", "description": "String ID of the user who receives the reminder.", "examples": [ "1234567" ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the reminder is deleted.", "examples": [ false ] }, "is_urgent": { "type": "boolean", "title": "Is Urgent", "description": "Whether the reminder should be delivered urgently.", "examples": [ false ] }, "type": { "type": "string", "title": "Type", "description": "Reminder type.", "examples": [ "relative" ] }, "minute_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Minute Offset", "description": "Minutes before the task due time for relative reminders.", "examples": [ 30 ] }, "due": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Due", "description": "Datetime when the reminder fires, or `null` if unset.", "examples": [ { "date": "2025-02-12T09:00:00", "lang": "en", "timezone": "Europe/Madrid" } ] } }, "type": "object", "required": [ "id", "item_id", "notify_uid", "is_deleted", "is_urgent", "type", "minute_offset", "due" ], "title": "NotificationSyncView", "description": "A class with fields representing a NotificationView which will be returned\nto clients in a sync (or sync-like) response." }, "NotificationType": { "type": "string", "enum": [ "note_added", "item_assigned", "item_completed", "item_uncompleted", "karma_level", "share_invitation_sent", "share_invitation_accepted", "share_invitation_rejected", "share_invitation_blocked_by_project_limit", "user_left_project", "user_removed_from_project", "teams_workspace_upgraded", "teams_workspace_canceled", "teams_workspace_payment_failed", "pro_trial_started", "pro_trial_ended", "workspace_invitation_created", "workspace_invitation_accepted", "workspace_invitation_rejected", "project_archived", "project_moved", "removed_from_workspace", "workspace_deleted", "message", "workspace_user_joined_by_domain", "price_increase_new_pro_users", "price_increase_new_team", "price_increase_new_team_trial", "price_increase_android", "workspace_team_cohort_tagged" ], "title": "NotificationType", "description": "The type of notification being sent", "x-enumDescriptions": { "item_assigned": "Item Assigned", "item_completed": "Item Completed", "item_uncompleted": "Item Uncompleted", "karma_level": "Karma Level", "message": "Message", "note_added": "Note Added", "price_increase_android": "Price Increase Android", "price_increase_new_pro_users": "Price Increase New Pro Users", "price_increase_new_team": "Price Increase New Team", "price_increase_new_team_trial": "Price Increase New Team Trial", "pro_trial_ended": "Pro Trial Ended", "pro_trial_started": "Pro Trial Started", "project_archived": "Project Archived", "project_moved": "Project Moved", "removed_from_workspace": "Removed From Workspace", "share_invitation_accepted": "Share Invitation Accepted", "share_invitation_blocked_by_project_limit": "Share Invitation Blocked By Project Limit", "share_invitation_rejected": "Share Invitation Rejected", "share_invitation_sent": "Share Invitation Sent", "teams_workspace_canceled": "Teams Workspace Canceled", "teams_workspace_payment_failed": "Teams Workspace Payment Failed", "teams_workspace_upgraded": "Teams Workspace Upgraded", "user_left_project": "User Left Project", "user_removed_from_project": "User Removed From Project", "workspace_deleted": "Workspace Deleted", "workspace_invitation_accepted": "Workspace Invitation Accepted", "workspace_invitation_created": "Workspace Invitation Created", "workspace_invitation_rejected": "Workspace Invitation Rejected", "workspace_team_cohort_tagged": "Workspace Team Acquisition Cohort Tagged", "workspace_user_joined_by_domain": "Workspace User Joined By Domain" } }, "OrganizationSize": { "type": "string", "enum": [ "size_1", "size_2_to_10", "size_11_to_50", "size_51_to_100", "size_101_to_250", "size_51_to_250", "more_than_250" ] }, "PaginatedList_ActivityEvents_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/ActivityEvents" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_AnyProjectSyncViewResponse_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/AnyProjectSyncViewResponse" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_Collaborator_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/Collaborator" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_FolderSyncView_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/FolderSyncView" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_ItemSyncView_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/ItemSyncView" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_LabelRestView_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/LabelRestView" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_NoteSyncView_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/NoteSyncView" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_NotificationLocationSyncView_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/NotificationLocationSyncView" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_NotificationSyncView_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/NotificationSyncView" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_SectionSyncView_": { "properties": { "results": { "items": { "$ref": "#/components/schemas/SectionSyncView" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PaginatedList_str_": { "properties": { "results": { "items": { "type": "string" }, "type": "array", "title": "Results", "description": "Objects in the current page of results.", "examples": [ [] ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the next page of results, or `null` when there are no more results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "results", "next_cursor" ], "title": "PaginatedList" }, "PersonalProjectSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the project.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "can_assign_tasks": { "type": "boolean", "title": "Can Assign Tasks", "description": "Whether the current user can assign tasks in the project.", "examples": [ true ] }, "can_comment": { "type": "boolean", "title": "Can Comment", "description": "Whether the current user can comment in the project.", "examples": [ true ] }, "child_order": { "type": "integer", "title": "Child Order", "description": "Position of the project among sibling projects.", "examples": [ 1 ] }, "is_collapsed": { "type": "boolean", "title": "Is Collapsed", "description": "Whether the project is collapsed in the user's view.", "examples": [ false ] }, "color": { "type": "string", "title": "Color", "description": "Project color name.", "examples": [ "charcoal" ] }, "creator_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Creator Uid", "description": "String ID of the user who created the project.", "examples": [ "1234567" ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Created At", "description": "Date and time when the project was created, or `null` if unknown.", "examples": [ "2025-01-15T10:30:00Z" ] }, "is_archived": { "type": "boolean", "title": "Is Archived", "description": "Whether the project is archived.", "examples": [ false ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the project is deleted.", "examples": [ false ] }, "is_favorite": { "type": "boolean", "title": "Is Favorite", "description": "Whether the project is marked as a favorite.", "examples": [ false ] }, "is_frozen": { "type": "boolean", "title": "Is Frozen", "description": "Whether the project is frozen and cannot be modified.", "examples": [ false ] }, "name": { "type": "string", "title": "Name", "description": "Project name.", "examples": [ "Inbox" ] }, "is_shared": { "type": "boolean", "title": "Is Shared", "description": "Whether the project is shared with other users.", "examples": [ false ] }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Updated At", "description": "Date and time when the project was last updated, or `null` if unknown.", "examples": [ "2025-01-16T10:30:00Z" ] }, "view_style": { "type": "string", "title": "View Style", "description": "Project view style.", "examples": [ "list" ] }, "default_order": { "type": "integer", "title": "Default Order", "description": "Default order of the project in team views.", "examples": [ 1 ] }, "description": { "type": "string", "title": "Description", "description": "Project description.", "examples": [ "Tasks for the launch plan" ] }, "public_key": { "type": "string", "title": "Public Key", "description": "Public access key for the project, or an empty string when public access is disabled.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "access": { "anyOf": [ { "$ref": "#/components/schemas/ProjectAccessView" }, { "type": "null" } ], "description": "Project access configuration.", "examples": [ null ] }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "Current user's role in the project.", "examples": [ "admin" ] }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "String ID of the parent project, or `null` for root projects.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "inbox_project": { "type": "boolean", "title": "Inbox Project", "description": "Whether this project is the user's Inbox project.", "examples": [ false ] } }, "type": "object", "required": [ "id", "can_assign_tasks", "can_comment", "child_order", "is_collapsed", "color", "creator_uid", "created_at", "is_archived", "is_deleted", "is_favorite", "is_frozen", "name", "is_shared", "updated_at", "view_style", "default_order", "description", "public_key", "access", "role", "parent_id", "inbox_project" ], "title": "PersonalProjectSyncView", "description": "A representation of a Personal Project Sync View, extending the base ProjectSync\nView, to be returned to clients in a sync (or sync-like) response." }, "PlanPrice": { "properties": { "amount": { "type": "string", "title": "Amount", "description": "Formatted plan price amount.", "examples": [ "600" ] }, "raw_amount": { "type": "number", "title": "Raw Amount", "description": "Raw plan price amount in the currency's smallest unit.", "examples": [ 600.0 ] }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code.", "examples": [ "USD" ] }, "billing_cycle": { "anyOf": [ { "type": "string", "enum": [ "monthly", "yearly" ] }, { "type": "null" } ], "title": "Billing Cycle", "description": "Billing cycle for the plan price, or `null` if unknown.", "examples": [ "monthly" ] }, "tax_behavior": { "type": "string", "enum": [ "exclusive", "inclusive", "unspecified" ], "title": "Tax Behavior", "description": "Tax behavior for the plan price.", "examples": [ "exclusive" ] } }, "type": "object", "required": [ "amount", "raw_amount", "currency", "billing_cycle", "tax_behavior" ], "title": "PlanPrice" }, "PlanType": { "type": "string", "enum": [ "STARTER", "BUSINESS" ], "title": "PlanType", "description": "The plan the workspace is currently on", "x-enumDescriptions": { "BUSINESS": "Business", "STARTER": "Starter" } }, "PositiveKarmaReason": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ], "title": "PositiveKarmaReason", "description": "Reasons why karma can increase.", "x-enumDescriptions": { "1": "Tasks Added", "2": "Tasks Completed", "3": "Advanced Features", "4": "Signup", "5": "Beta Upgrade", "6": "Support Activity", "7": "Premium Upgrade", "8": "Getting Started", "9": "Daily Goal Reached", "10": "Weekly Goal Reached" } }, "ProductivityStatsResponse": { "properties": { "days_items": { "items": { "$ref": "#/components/schemas/DailyCompletionItem" }, "type": "array", "title": "Days Items", "description": "Daily completion statistics for the last 7 days, ordered chronologically", "examples": [ [ { "date": "2025-02-12", "items": [], "total_completed": 3 } ] ] }, "week_items": { "items": { "$ref": "#/components/schemas/WeeklyCompletionItem" }, "type": "array", "title": "Week Items", "description": "Weekly completion statistics for the last 4 weeks, ordered chronologically. Only available for Pro and Business plan users", "examples": [ [ { "from": "2025-02-10", "items": [], "to": "2025-02-16", "total_completed": 12 } ] ] }, "project_colors": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Project Colors", "description": "Mapping of project IDs to their color names (e.g., {'2aB3cD4eF5gH6iJ7': 'blue', '8kL9mN0oP1qR2sT3': 'red'})", "examples": [ { "6XGgm6PHrGgMpCFX": "blue" } ] }, "completed_count": { "type": "integer", "title": "Completed Count", "description": "Total number of tasks completed by the user (all time)", "examples": [ 42 ] }, "karma": { "type": "number", "title": "Karma", "description": "Current karma score", "examples": [ 1024.0 ] }, "karma_trend": { "type": "string", "title": "Karma Trend", "description": "Karma trend indicator ('up' or 'down')", "examples": [ "up" ] }, "karma_graph_data": { "items": { "$ref": "#/components/schemas/GraphPoint" }, "type": "array", "title": "Karma Graph Data", "description": "Historical karma data points for graphing, each containing date and karma_avg", "examples": [ [ { "date": "2025-02-12", "karma_avg": 1024 } ] ] }, "karma_last_update": { "type": "number", "title": "Karma Last Update", "description": "Net karma change from the most recent update (positive_karma + negative_karma)", "examples": [ 1.0 ] }, "karma_update_reasons": { "items": { "$ref": "#/components/schemas/KarmaUpdateReasonEntry" }, "type": "array", "title": "Karma Update Reasons", "description": "Recent karma update events with reasons and amounts", "examples": [ [ { "negative_karma": 0.0, "negative_karma_reasons": [ 50 ], "new_karma": 1024.0, "positive_karma": 1.0, "positive_karma_reasons": [ 2, 9 ], "time": "2025-02-12T10:30:00Z" } ] ] }, "goals": { "$ref": "#/components/schemas/GoalsSettings", "description": "User goals, streaks, and productivity settings" } }, "type": "object", "required": [ "days_items", "week_items", "project_colors", "completed_count", "karma", "karma_trend", "karma_graph_data", "karma_last_update", "karma_update_reasons", "goals" ], "title": "ProductivityStatsResponse", "description": "Comprehensive productivity statistics response.\n\nIncludes completion counts, karma information, goals, and streaks." }, "ProjectAccessView": { "properties": { "visibility": { "$ref": "#/components/schemas/ProjectVisibility", "description": "Project visibility level.", "examples": [ "public" ] }, "configuration": { "anyOf": [ { "$ref": "#/components/schemas/RestrictedProjectConfiguration" }, { "$ref": "#/components/schemas/TeamProjectConfiguration" }, { "$ref": "#/components/schemas/PublicProjectConfiguration" } ], "title": "Configuration", "description": "Configuration for the selected visibility level.", "examples": [ {} ] } }, "type": "object", "required": [ "visibility", "configuration" ], "title": "ProjectAccessView", "description": "Contains the details on who can view a project." }, "ProjectCompletedItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "Project ID (v1 or v2 format depending on API version)", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "completed": { "type": "integer", "title": "Completed", "description": "Number of tasks completed in this project during the time period", "examples": [ 3 ] } }, "type": "object", "required": [ "id", "completed" ], "title": "ProjectCompletedItem", "description": "Completion statistics for a specific project." }, "ProjectImportCreateResponseWithObjects": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status", "description": "Always `ok` on success.", "examples": [ "ok" ] }, "project_id": { "type": "string", "title": "Project Id", "description": "ID of the project created from the template.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "template_type": { "type": "string", "title": "Template Type", "description": "Type of template that was imported.", "examples": [ "project" ] }, "projects": { "items": { "anyOf": [ { "$ref": "#/components/schemas/PersonalProjectSyncView" }, { "$ref": "#/components/schemas/WorkspaceProjectSyncView" } ] }, "type": "array", "title": "Projects", "description": "Projects created by the import.", "examples": [ [ { "access": { "configuration": {}, "visibility": "restricted" }, "can_assign_tasks": false, "can_comment": true, "child_order": 1, "color": "lime_green", "created_at": "2025-01-15T10:30:00Z", "creator_uid": "1234567", "default_order": 0, "description": "", "id": "6XGgm6PHrGgMpCFX", "is_archived": false, "is_collapsed": false, "is_deleted": false, "is_favorite": false, "is_frozen": false, "is_shared": false, "name": "Shopping List", "public_access": false, "public_key": "", "role": "CREATOR", "updated_at": "2025-01-16T10:30:00Z", "view_style": "list" } ] ] }, "sections": { "items": { "$ref": "#/components/schemas/SectionSyncView" }, "type": "array", "title": "Sections", "description": "Sections created by the import.", "examples": [ [ { "added_at": "2025-01-15T10:30:00Z", "description": "Tasks for the launch plan", "id": "6fFPHV272WWh3gpW", "is_archived": false, "is_collapsed": false, "is_deleted": false, "name": "Introductions", "order_key": "a1V", "project_id": "6XGgm6PHrGgMpCFX", "section_order": 1, "updated_at": "2025-01-16T10:30:00Z", "user_id": "1234567" } ] ] }, "tasks": { "items": { "$ref": "#/components/schemas/ItemSyncView" }, "type": "array", "title": "Tasks", "description": "Tasks created by the import.", "examples": [ [ { "added_at": "2025-01-15T10:30:00Z", "added_by_uid": "1234567", "checked": false, "child_order": 1, "completed_count": 3, "content": "Welcome the new hire", "day_order": -1, "description": "", "id": "6XGgmFVcrG5RRjVr", "is_collapsed": false, "is_deleted": false, "labels": [], "note_count": 0, "postponed_count": 1, "priority": 1, "project_id": "6XGgm6PHrGgMpCFX", "section_id": "6fFPHV272WWh3gpW", "updated_at": "2025-01-16T10:30:00Z", "user_id": "1234567" } ] ] }, "comments": { "items": { "$ref": "#/components/schemas/ItemNoteSyncView" }, "type": "array", "title": "Comments", "description": "Task comments created by the import.", "examples": [ [ { "content": "Great idea!", "id": "6Xw8x1xCFFw6Q5p9", "is_deleted": false, "item_id": "6XGgmFVcrG5RRjVr", "posted_at": "2025-01-15T10:30:00Z", "posted_uid": "1234567" } ] ] }, "project_notes": { "items": { "$ref": "#/components/schemas/ProjectNoteSyncView" }, "type": "array", "title": "Project Notes", "description": "Project comments created by the import.", "examples": [ [ { "content": "Project kickoff notes", "id": "6Xw8x1xCFFw6Q5q0", "is_deleted": false, "posted_at": "2025-01-15T10:30:00Z", "posted_uid": "1234567", "project_id": "6XGgm6PHrGgMpCFX" } ] ] } }, "type": "object", "required": [ "status", "project_id", "template_type", "projects", "sections", "tasks", "comments", "project_notes" ], "title": "ProjectImportCreateResponseWithObjects" }, "ProjectImportResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status", "description": "Always `ok` on success.", "examples": [ "ok" ] }, "template_type": { "type": "string", "title": "Template Type", "description": "Type of template that was imported.", "examples": [ "project" ] }, "projects": { "items": { "anyOf": [ { "$ref": "#/components/schemas/PersonalProjectSyncView" }, { "$ref": "#/components/schemas/WorkspaceProjectSyncView" } ] }, "type": "array", "title": "Projects", "description": "Projects created or updated by the import.", "examples": [ [ { "access": { "configuration": {}, "visibility": "restricted" }, "can_assign_tasks": false, "can_comment": true, "child_order": 1, "color": "lime_green", "created_at": "2025-01-15T10:30:00Z", "creator_uid": "1234567", "default_order": 0, "description": "", "id": "6XGgm6PHrGgMpCFX", "is_archived": false, "is_collapsed": false, "is_deleted": false, "is_favorite": false, "is_frozen": false, "is_shared": false, "name": "Shopping List", "public_access": false, "public_key": "", "role": "CREATOR", "updated_at": "2025-01-16T10:30:00Z", "view_style": "list" } ] ] }, "sections": { "items": { "$ref": "#/components/schemas/SectionSyncView" }, "type": "array", "title": "Sections", "description": "Sections created by the import.", "examples": [ [ { "added_at": "2025-01-15T10:30:00Z", "description": "Tasks for the launch plan", "id": "6fFPHV272WWh3gpW", "is_archived": false, "is_collapsed": false, "is_deleted": false, "name": "Introductions", "order_key": "a1V", "project_id": "6XGgm6PHrGgMpCFX", "section_order": 1, "updated_at": "2025-01-16T10:30:00Z", "user_id": "1234567" } ] ] }, "tasks": { "items": { "$ref": "#/components/schemas/ItemSyncView" }, "type": "array", "title": "Tasks", "description": "Tasks created by the import.", "examples": [ [ { "added_at": "2025-01-15T10:30:00Z", "added_by_uid": "1234567", "checked": false, "child_order": 1, "completed_count": 3, "content": "Welcome the new hire", "day_order": -1, "description": "", "id": "6XGgmFVcrG5RRjVr", "is_collapsed": false, "is_deleted": false, "labels": [], "note_count": 0, "postponed_count": 1, "priority": 1, "project_id": "6XGgm6PHrGgMpCFX", "section_id": "6fFPHV272WWh3gpW", "updated_at": "2025-01-16T10:30:00Z", "user_id": "1234567" } ] ] }, "comments": { "items": { "$ref": "#/components/schemas/ItemNoteSyncView" }, "type": "array", "title": "Comments", "description": "Task comments created by the import.", "examples": [ [ { "content": "Great idea!", "id": "6Xw8x1xCFFw6Q5p9", "is_deleted": false, "item_id": "6XGgmFVcrG5RRjVr", "posted_at": "2025-01-15T10:30:00Z", "posted_uid": "1234567" } ] ] }, "project_notes": { "items": { "$ref": "#/components/schemas/ProjectNoteSyncView" }, "type": "array", "title": "Project Notes", "description": "Project comments created by the import.", "examples": [ [ { "content": "Project kickoff notes", "id": "6Xw8x1xCFFw6Q5q0", "is_deleted": false, "posted_at": "2025-01-15T10:30:00Z", "posted_uid": "1234567", "project_id": "6XGgm6PHrGgMpCFX" } ] ] } }, "type": "object", "required": [ "status", "template_type", "projects", "sections", "tasks", "comments", "project_notes" ], "title": "ProjectImportResponse" }, "ProjectNoteSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the comment.", "examples": [ "6XGgmFQrx44wfGHr" ] }, "posted_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Posted Uid", "description": "String ID of the user who posted the comment.", "examples": [ "1234567" ] }, "content": { "type": "string", "title": "Content", "description": "Comment content.", "default": "", "examples": [ "Looks good to me." ] }, "file_attachment": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "items": {}, "type": "array" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "File Attachment", "description": "File attachment metadata, or `null` when the comment has no attachment.", "examples": [ null ] }, "uids_to_notify": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Uids To Notify", "description": "String IDs of users notified by the comment.", "examples": [ [ "1234567" ] ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the comment is deleted.", "examples": [ false ] }, "posted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Posted At", "description": "Date and time when the comment was posted, or `null` if unknown.", "examples": [ "2025-01-15T10:30:00Z" ] }, "reactions": { "anyOf": [ { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Reactions", "description": "Reaction emoji mapped to user IDs that reacted.", "examples": [ { "\ud83d\udc4d": [ "1234567" ] } ] }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" } }, "type": "object", "required": [ "id", "posted_uid", "file_attachment", "uids_to_notify", "is_deleted", "posted_at", "reactions", "project_id" ], "title": "ProjectNoteSyncView", "description": "A representation of a Project Note View, extending the base class NoteSyncView,\nto be returned to clients in a sync (or sync-like) response." }, "ProjectSortPreference": { "type": "string", "enum": [ "MANUAL", "A_TO_Z", "Z_TO_A" ], "title": "ProjectSortPreference", "description": "User preference for workspace project sorting", "x-enumDescriptions": { "A_TO_Z": "A To Z", "MANUAL": "Manual", "Z_TO_A": "Z To A" } }, "ProjectStatus": { "type": "string", "enum": [ "PLANNED", "IN_PROGRESS", "PAUSED", "COMPLETED", "CANCELED" ], "title": "ProjectStatus", "description": "Project status.\n\nAt the moment, this is for workspace projects only.", "x-enumDescriptions": { "CANCELED": "Canceled", "COMPLETED": "Completed", "IN_PROGRESS": "In Progress", "PAUSED": "Paused", "PLANNED": "Planned" } }, "ProjectViewStyle": { "type": "string", "enum": [ "LIST", "BOARD", "CALENDAR" ], "title": "ProjectViewStyle", "x-enumDescriptions": { "BOARD": "Board", "CALENDAR": "Calendar", "LIST": "List" } }, "ProjectViewStyleV1": { "type": "string", "enum": [ "list", "board", "calendar" ] }, "ProjectVisibility": { "type": "string", "enum": [ "restricted", "team", "public" ], "title": "ProjectVisibility", "description": "Indicates who can see a project", "x-enumDescriptions": { "public": "Public", "restricted": "Restricted", "team": "Team" } }, "PublicProjectConfiguration": { "properties": { "hide_collaborator_details": { "type": "boolean", "title": "Hide Collaborator Details", "description": "Whether collaborator details are hidden on the public project.", "examples": [ true ] }, "disable_duplication": { "type": "boolean", "title": "Disable Duplication", "description": "Whether public project duplication is disabled.", "examples": [ true ] } }, "type": "object", "required": [ "hide_collaborator_details", "disable_duplication" ], "title": "PublicProjectConfiguration", "description": "Configuration specific to public projects." }, "PublicWorkspaceProperties": { "properties": { "industry": { "anyOf": [ { "$ref": "#/components/schemas/Industry" }, { "type": "null" } ], "description": "Industry selected for the workspace.", "examples": [ "information_technology" ] }, "department": { "anyOf": [ { "$ref": "#/components/schemas/Department" }, { "type": "null" } ], "description": "Department selected for the workspace.", "examples": [ "engineering" ] }, "organization_size": { "anyOf": [ { "$ref": "#/components/schemas/OrganizationSize" }, { "type": "null" } ], "description": "Organization size selected for the workspace.", "examples": [ "size_11_to_50" ] }, "intended_team_size": { "anyOf": [ { "$ref": "#/components/schemas/IntendedTeamSize" }, { "type": "null" } ], "description": "Number of collaborators the creator intends to work with, selected during onboarding.", "examples": [ "size_2_to_10" ] }, "type_of_work": { "anyOf": [ { "$ref": "#/components/schemas/TypeOfWork" }, { "type": "null" } ], "description": "Type of work the team primarily does, selected during onboarding.", "examples": [ "projects" ] }, "creator_role": { "anyOf": [ { "$ref": "#/components/schemas/CreatorRole" }, { "type": "null" } ], "description": "Role selected by the workspace creator.", "examples": [ "owner_founder" ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "2-letter continent code, possible values are `AF`, `AS`, `EU`, `NA`, `SA`, `OC`, and `AN`.", "examples": [ "EU" ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "2-letter ISO 3166-1 alpha-2 country code.", "examples": [ "ES" ] }, "default_access_level": { "anyOf": [ { "$ref": "#/components/schemas/DefaultAccessLevel" }, { "type": "null" } ], "description": "Default access level for new workspace projects.", "default": "team", "examples": [ "team" ] }, "desktop_workspace_modal": { "anyOf": [ { "$ref": "#/components/schemas/DesktopWorkspaceModal" }, { "type": "null" } ], "description": "Desktop workspace modal variant shown to the user.", "examples": [ "TRIAL_OFFER" ] }, "beta_enabled": { "type": "boolean", "title": "Beta Enabled", "description": "Whether beta features are enabled for the workspace.", "default": false, "examples": [ false ] }, "acquisition_source": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionSource" }, { "type": "null" } ], "description": "Workspace acquisition source.", "examples": [ "high_paid_channel" ] }, "team_acquisition_cohort": { "anyOf": [ { "$ref": "#/components/schemas/TeamAcquisitionCohort" }, { "type": "null" } ], "description": "Team acquisition cohort assigned to the workspace.", "examples": [ "type_1_unaware" ] }, "acquisition_loop_last_show": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Acquisition Loop Last Show", "description": "Date when the acquisition loop was last shown in YYYY-MM-DD format.", "examples": [ "2025-02-12" ] }, "hdyhau": { "anyOf": [ { "$ref": "#/components/schemas/Hdyhau" }, { "type": "null" } ], "description": "How did you hear about us marketing attribution field.", "examples": [ "search_engine" ] }, "onboarding_filter_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Onboarding Filter Id", "description": "ID of the workspace assigned filter created during onboarding.", "examples": [ 1234 ] }, "created_platform": { "anyOf": [ { "$ref": "#/components/schemas/CreatedPlatform" }, { "type": "null" } ], "description": "Platform used to create this workspace.", "examples": [ "web" ] } }, "type": "object", "title": "PublicWorkspaceProperties", "description": "Client-settable workspace properties.\n\nTrusted-only provenance fields are rejected outright (including\nexplicit nulls) so the public create/update surfaces can neither opt\na workspace into import behavior nor clear its provenance." }, "ReminderDueAttribute": { "properties": { "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date", "description": "Absolute reminder date in ISO 8601 format.", "examples": [ "2025-02-12T09:00:00" ] }, "string": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "String", "description": "Natural-language reminder date.", "examples": [ "tomorrow at 9am" ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lang", "description": "Language used to parse the natural-language date.", "examples": [ "en" ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone", "description": "Timezone for the reminder date.", "examples": [ "Europe/Madrid" ] }, "is_recurring": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Recurring", "description": "Whether the reminder date is recurring.", "examples": [ false ] } }, "type": "object", "title": "ReminderDueAttribute", "description": "Due date input for absolute reminders." }, "ReminderIsUrgentAttribute": { "type": "boolean", "description": "Whether the reminder is an urgent reminder. Urgent reminders trigger an alarm notification on the user's designated urgent reminder device.", "examples": [ false ] }, "ReminderServiceType": { "type": "string", "enum": [ "email", "push" ] }, "ReminderServiceTypeAttribute": { "$ref": "#/components/schemas/ReminderServiceType", "description": "Notification service type: 'email', 'push'.", "examples": [ "email" ] }, "ReminderTaskIDAttribute": { "type": "string", "description": "String ID of the task", "examples": [ "6XGgmFVcrG5RRjVr" ] }, "RemoveWorkspaceUserResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status", "description": "Always `ok` on success.", "default": "ok", "examples": [ "ok" ] } }, "type": "object", "title": "RemoveWorkspaceUserResponse" }, "RemovedNotificationType": { "type": "string", "enum": [ "biz_trial_enter_cc", "biz_trial_will_end", "biz_payment_failed", "biz_account_disabled", "biz_invitation_created", "biz_invitation_accepted", "biz_invitation_rejected", "biz_policy_disallowed_invitation", "biz_policy_rejected_invitation" ], "title": "RemovedNotificationType", "description": "A set of legacy NotificationType values that have been removed\nfrom the mailers and database, but are still referenced by clients\ntherefore we have to maintain the contract.\n\nEnsures we still send down the keys without needing to maintain\nthe associated mailer code and database values.", "x-enumDescriptions": { "biz_account_disabled": "Biz Account Disabled", "biz_invitation_accepted": "Biz Invitation Accepted", "biz_invitation_created": "Biz Invitation Created", "biz_invitation_rejected": "Biz Invitation Rejected", "biz_payment_failed": "Biz Payment Failed", "biz_policy_disallowed_invitation": "Biz Policy Disallowed Invitation", "biz_policy_rejected_invitation": "Biz Policy Rejected Invitation", "biz_trial_enter_cc": "Biz Trial Enter Cc", "biz_trial_will_end": "Biz Trial Will End" } }, "RestrictedProjectConfiguration": { "properties": {}, "type": "object", "title": "RestrictedProjectConfiguration", "description": "Configuration specific to restricted projects." }, "RoleToActionMappingView": { "properties": { "project_collaborator_actions": { "items": { "$ref": "#/components/schemas/RoleView" }, "type": "array", "title": "Project Collaborator Actions", "description": "Project collaborator roles and their allowed actions.", "examples": [ [ { "actions": [ { "name": "UPDATE_ITEM" } ], "name": "MEMBER" } ] ] }, "workspace_collaborator_actions": { "items": { "$ref": "#/components/schemas/RoleView" }, "type": "array", "title": "Workspace Collaborator Actions", "description": "Workspace collaborator roles and their allowed actions.", "examples": [ [ { "actions": [ { "name": "UPDATE_ITEM" } ], "name": "MEMBER" } ] ] } }, "type": "object", "required": [ "project_collaborator_actions", "workspace_collaborator_actions" ], "title": "RoleToActionMappingView" }, "RoleView": { "properties": { "name": { "anyOf": [ { "$ref": "#/components/schemas/CollaboratorRole" }, { "$ref": "#/components/schemas/WorkspaceRole" } ], "title": "Name", "description": "Role that grants the listed actions.", "examples": [ "MEMBER" ] }, "actions": { "items": { "$ref": "#/components/schemas/ActionView" }, "type": "array", "title": "Actions", "description": "Actions granted to this role.", "examples": [ [ { "name": "UPDATE_ITEM" } ] ] } }, "type": "object", "required": [ "name", "actions" ], "title": "RoleView" }, "SectionSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the section.", "examples": [ "6fFPHV272WWh3gpW" ] }, "user_id": { "type": "string", "title": "User Id", "description": "String ID of the user who owns the section.", "examples": [ "1234567" ] }, "project_id": { "type": "string", "title": "Project Id", "description": "String ID of the project that contains the section.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "added_at": { "type": "string", "format": "date-time", "title": "Added At", "description": "Date and time when the section was created.", "examples": [ "2025-01-15T10:30:00Z" ] }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Updated At", "description": "Date and time when the section was last updated, or `null` if unknown.", "examples": [ "2025-01-16T10:30:00Z" ] }, "archived_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Archived At", "description": "Date and time when the section was archived, or `null` if it is active.", "examples": [ "2025-01-17T10:30:00Z" ] }, "name": { "type": "string", "title": "Name", "description": "Section name.", "examples": [ "Groceries" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Section description, or `null` if it has none.", "examples": [ "Tasks for the launch plan" ] }, "section_order": { "type": "integer", "title": "Section Order", "description": "Position of the section in the project.", "examples": [ 1 ] }, "order_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Order Key", "description": "Fractional-indexing order key: sections sort by comparing keys lexicographically within a project. May be `null` for projects not yet migrated.", "examples": [ "a1V" ] }, "is_collapsed": { "type": "boolean", "title": "Is Collapsed", "description": "Whether the section is collapsed in the user's view.", "examples": [ false ] }, "is_archived": { "type": "boolean", "title": "Is Archived", "description": "Whether the section is archived.", "examples": [ false ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the section is deleted.", "examples": [ false ] } }, "type": "object", "required": [ "id", "user_id", "project_id", "added_at", "updated_at", "archived_at", "name", "description", "section_order", "order_key", "is_collapsed", "is_archived", "is_deleted" ], "title": "SectionSyncView", "description": "A class with fields representing a SectionView which will be returned\nto clients in a sync (or sync-like) response." }, "StreakInfo": { "properties": { "count": { "type": "integer", "title": "Count", "description": "Number of consecutive days/weeks in the streak", "examples": [ 5 ] }, "start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Start", "description": "Start date of the streak (ISO 8601 format: YYYY-MM-DD), or null if no streak", "examples": [ "2025-02-10" ] }, "end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End", "description": "End date of the streak (ISO 8601 format: YYYY-MM-DD), or null if no streak", "examples": [ "2025-02-14" ] } }, "type": "object", "required": [ "count" ], "title": "StreakInfo", "description": "Streak information (count and dates)." }, "SubscriptionInfo": { "properties": { "status": { "type": "string", "enum": [ "none", "autorenew", "canceled", "expired", "trial", "trial_canceled" ], "title": "Status", "description": "Current subscription status. `none` = never subscribed, `autorenew` = active and renewing, `canceled` = active until period end, `expired` = no longer active, `trial` = in free trial, `trial_canceled` = trial that will not convert.", "examples": [ "autorenew" ] }, "plan": { "type": "string", "enum": [ "free", "pro", "pro_gifted", "pro_legacy" ], "title": "Plan", "description": "Plan tier the user is currently on.", "examples": [ "pro" ] }, "expiration_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expiration Date", "description": "Date the current paid period ends, in `YYYY-MM-DD` format.", "examples": [ "2026-12-31" ] }, "activation_method": { "type": "string", "enum": [ "stripe", "appstore", "playstore", "teams", "manual" ], "title": "Activation Method", "description": "How the active subscription was purchased.", "examples": [ "stripe" ] }, "plan_price": { "anyOf": [ { "$ref": "#/components/schemas/PlanPrice" }, { "type": "null" } ], "description": "Price of the active plan, when known.", "examples": [ null ] }, "billing_portal_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Portal Url", "description": "One-time URL to the Stripe customer portal, if available.", "examples": [ null ] }, "billing_portal_switch_to_annual_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Portal Switch To Annual Url", "description": "One-time URL to a Stripe portal flow for switching from monthly to annual billing, if eligible.", "examples": [ null ] }, "has_billing_portal": { "type": "boolean", "title": "Has Billing Portal", "description": "`true` when the user has a Stripe customer with a portal session.", "examples": [ true ] }, "has_billing_portal_switch_to_annual": { "type": "boolean", "title": "Has Billing Portal Switch To Annual", "description": "`true` when a switch-to-annual flow is available in Stripe.", "examples": [ false ] }, "invoice_credit_balance": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Invoice Credit Balance", "description": "Stripe customer credit balance, keyed by ISO 4217 currency code, with values in the smallest currency unit (e.g. cents).", "examples": [ { "usd": 0 } ] }, "has_switch_legacy_to_current": { "type": "boolean", "title": "Has Switch Legacy To Current", "description": "`true` when the user is eligible to switch from a legacy Pro price to the current one.", "examples": [ false ] } }, "type": "object", "required": [ "status", "plan", "expiration_date", "activation_method", "plan_price", "billing_portal_url", "billing_portal_switch_to_annual_url", "has_billing_portal", "has_billing_portal_switch_to_annual", "invoice_credit_balance", "has_switch_legacy_to_current" ], "title": "SubscriptionInfo" }, "TasksCompletedDateResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ItemSyncView" }, "type": "array", "title": "Items", "description": "Completed tasks in the current page.", "examples": [ [ { "added_at": "2025-01-15T10:30:00Z", "added_by_uid": "1234567", "assigned_by_uid": "1234567", "checked": false, "child_order": 1, "completed_at": "2025-01-16T10:30:00Z", "completed_by_uid": "1234567", "completed_count": 3, "content": "Buy milk", "day_order": 1, "deadline": { "date": "2025-02-12", "lang": "en" }, "description": "Pick up organic milk", "due": { "date": "2025-02-12", "is_recurring": false, "lang": "en", "string": "tomorrow" }, "duration": { "amount": 30, "unit": "minute" }, "id": "6XGgmFVcrG5RRjVr", "is_collapsed": false, "is_deleted": false, "labels": [ "priority" ], "note_count": 0, "parent_id": "6XGgmFVcrG5RRjVr", "postponed_count": 1, "priority": 1, "project_id": "6XGgm6PHrGgMpCFX", "responsible_uid": "1234567", "section_id": "6fFPHV272WWh3gpW", "updated_at": "2025-01-17T10:30:00Z", "user_id": "1234567" } ] ] }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "Cursor for the next page of completed tasks, when more results are available. Omitted when there is no next page.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "title": "TasksCompletedDateResponse" }, "TeamAcquisitionCohort": { "type": "string", "enum": [ "type_1_unaware", "type_2_unconvinced", "type_3_reverted" ], "title": "TeamAcquisitionCohort", "x-enumDescriptions": { "type_1_unaware": "Type 1 Unaware", "type_2_unconvinced": "Type 2 Unconvinced", "type_3_reverted": "Type 3 Reverted" } }, "TeamProjectConfiguration": { "properties": {}, "type": "object", "title": "TeamProjectConfiguration", "description": "Configuration specific to team projects." }, "ThemeAppearance": { "type": "string", "enum": [ "light", "dark", "system" ], "title": "ThemeAppearance", "x-enumDescriptions": { "dark": "Dark", "light": "Light", "system": "System" } }, "TypeOfWork": { "type": "string", "enum": [ "projects", "processes", "both" ] }, "Undefined": { "type": "integer", "enum": [ 0 ], "title": "Undefined", "description": "Undefined object\n\nThe object is used as a default argument in some constructors to differentiate\nfrom `None` which usually means in that context \"reset the value\".\n\n- Use the `parts.util.undefined` singleton for the default variable.\n- Use `is undefined` to see if value is undefined.\n- For type hints, use `YourType | Undefined`\n\nUsage example:\n\n```\n from parts.util import Undefined, undefined\n\n def update_item(\n id: int,\n title: str | Undefined = undefined,\n content: str | Undefined = undefined,\n ):\n pass\n```", "x-enumDescriptions": { "0": "Token" } }, "UpdateReminderIsUrgentAttribute": { "type": "boolean", "description": "Whether the reminder is an urgent reminder. Urgent reminders trigger an alarm notification on the user's designated urgent reminder device. Omit this field to keep it unchanged.", "examples": [ false ] }, "UploadResult": { "properties": { "file_url": { "type": "string", "title": "File Url", "description": "URL of the uploaded file.", "examples": [ "https://files.todoist.com/abc123/by/1234567/as/file.pdf" ] }, "file_name": { "type": "string", "title": "File Name", "description": "Name of the uploaded file.", "examples": [ "document.pdf" ] }, "file_size": { "type": "integer", "title": "File Size", "description": "Size of the uploaded file in bytes.", "examples": [ 12345 ] }, "file_type": { "type": "string", "title": "File Type", "description": "MIME type of the uploaded file.", "examples": [ "application/pdf" ] }, "resource_type": { "type": "string", "title": "Resource Type", "description": "Detected resource type of the upload.", "examples": [ "file" ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image", "description": "Image URL for image uploads, or `null` for non-image files.", "examples": [ null ] }, "image_width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Image Width", "description": "Image width in pixels, or `null` for non-image files.", "examples": [ 1200 ] }, "image_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Image Height", "description": "Image height in pixels, or `null` for non-image files.", "examples": [ 800 ] }, "upload_state": { "type": "string", "enum": [ "pending", "completed" ], "title": "Upload State", "description": "Upload processing state.", "default": "pending", "examples": [ "completed" ] } }, "type": "object", "required": [ "file_url", "file_name", "file_size", "file_type", "resource_type" ], "title": "UploadResult" }, "UrgentReminderDeviceView": { "properties": { "device_platform": { "type": "string", "enum": [ "ios", "android" ], "title": "Device Platform", "description": "Registered device platform.", "examples": [ "ios" ] }, "device_id": { "type": "string", "title": "Device Id", "description": "Registered device ID.", "examples": [ "device-123" ] }, "device_token": { "type": "string", "title": "Device Token", "description": "Registered device token.", "examples": [ "token-123" ] }, "device_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device Name", "description": "Registered device name when available.", "examples": [ "Maria's iPhone" ] } }, "type": "object", "required": [ "device_platform", "device_id", "device_token" ], "title": "UrgentReminderDeviceView" }, "UserJSON": { "properties": { "id": { "type": "string", "title": "Id", "description": "User ID", "examples": [ "1234567" ] }, "email": { "type": "string", "title": "Email", "description": "User's email address", "examples": [ "user@example.com" ] }, "full_name": { "type": "string", "title": "Full Name", "description": "The user's real name formatted as Firstname Lastname", "examples": [ "Maria Garcia" ] }, "has_password": { "type": "boolean", "title": "Has Password", "description": "Whether the user has a password set on the account. It will be false if they have only authenticated without a password (e.g. using Google, Facebook, etc.)", "examples": [ true ] }, "verification_status": { "type": "string", "enum": [ "unverified", "verified", "blocked", "legacy" ], "title": "Verification Status", "description": "User's email verification status. unverified (just signed up), verified (verified email or social login), blocked (failed to verify in 7 days), legacy (signed up before August 2022)", "examples": [ "verified" ] }, "mfa_enabled": { "type": "boolean", "title": "Mfa Enabled", "description": "Whether multi-factor authentication is enabled", "examples": [ false ] }, "token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token", "description": "The user's token that should be used to call the other API methods", "examples": [ "0123456789abcdef0123456789abcdef01234567" ] }, "is_premium": { "type": "boolean", "title": "Is Premium", "description": "Whether the user has a Todoist Pro subscription (a true or false value)", "examples": [ true ] }, "premium_status": { "anyOf": [ { "type": "string", "enum": [ "not_premium", "current_personal_plan", "legacy_personal_plan", "teams_business_member" ] }, { "type": "null" } ], "title": "Premium Status", "description": "Outlines why a user is premium, possible values are: not_premium, current_personal_plan, legacy_personal_plan or teams_business_member", "examples": [ "current_personal_plan" ] }, "premium_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Premium Until", "description": "The date when the user's Todoist Pro subscription ends (null if not a Todoist Pro user). This should be used for informational purposes only as this does not include the grace period upon expiration", "examples": [ "2025-12-31T23:59:59Z" ] }, "free_trial_expires": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Free Trial Expires", "description": "Date when free trial expires (ISO 8601 format)", "examples": [ "2025-03-01T00:00:00Z" ] }, "has_started_a_trial": { "type": "boolean", "title": "Has Started A Trial", "description": "Whether the user has ever started a free trial", "examples": [ true ] }, "joined_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Joined At", "description": "Date when user joined Todoist (ISO 8601 format)", "examples": [ "2025-01-15T10:30:00Z" ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the user is deleted", "default": false, "examples": [ false ] }, "deleted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deleted At", "description": "Date when user was deleted (ISO 8601 format)", "examples": [ null ] }, "business_account_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Business Account Id", "description": "The ID of the user's business account", "examples": [ null ] }, "date_format": { "type": "integer", "enum": [ 0, 1 ], "title": "Date Format", "description": "Whether to use the DD-MM-YYYY date format (if set to 0), or the MM-DD-YYYY format (if set to 1)", "examples": [ 1 ] }, "time_format": { "anyOf": [ { "type": "integer", "enum": [ 0, 1 ] }, { "type": "null" } ], "title": "Time Format", "description": "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)", "examples": [ 0 ] }, "sort_order": { "type": "integer", "enum": [ 0, 1 ], "title": "Sort Order", "description": "Whether to show projects in an oldest dates first order (if set to 0), or a oldest dates last order (if set to 1)", "examples": [ 0 ] }, "theme_id": { "type": "string", "title": "Theme Id", "description": "The currently selected Todoist theme (a number between 0 and 13)", "examples": [ "todoist" ] }, "theme_appearance": { "$ref": "#/components/schemas/ThemeAppearance", "description": "Whether Todoist uses a light theme, a dark theme, or follows the system appearance", "examples": [ "system" ] }, "start_day": { "type": "integer", "maximum": 7.0, "minimum": 1.0, "title": "Start Day", "description": "The first day of the week (between 1 and 7, where 1 is Monday and 7 is Sunday)", "examples": [ 1 ] }, "weekend_start_day": { "type": "integer", "maximum": 7.0, "minimum": 1.0, "title": "Weekend Start Day", "description": "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)", "examples": [ 6 ] }, "next_week": { "type": "integer", "maximum": 7.0, "minimum": 1.0, "title": "Next Week", "description": "The day of the next week, that tasks will be postponed to (between 1 and 7, where 1 is Monday and 7 is Sunday)", "examples": [ 1 ] }, "auto_reminder": { "type": "integer", "title": "Auto Reminder", "description": "The default time in minutes for the automatic reminders set, whenever a due date has been specified for a task", "examples": [ 30 ] }, "urgent_reminder_device": { "anyOf": [ { "$ref": "#/components/schemas/UrgentReminderDeviceView" }, { "type": "null" } ], "description": "The device that should ring urgent reminders. Contains device_id, device_token, device_platform (ios or android), and optionally device_name.", "examples": [ null ] }, "start_page": { "type": "string", "title": "Start Page", "description": "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, or filter?id=1234 to open a filter", "examples": [ "inbox" ] }, "inbox_project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inbox Project Id", "description": "The ID of the user's Inbox project", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "lang": { "type": "string", "enum": [ "cs", "da", "de", "en", "es", "fi", "fr", "it", "ja", "ko", "nl", "pl", "pt_BR", "ru", "sv", "tr", "zh_CN", "zh_TW" ], "title": "Lang", "description": "The user's language", "examples": [ "en" ] }, "tz_info": { "additionalProperties": true, "type": "object", "title": "Tz Info", "description": "The user's timezone (a dictionary structure), which includes the following elements: the timezone as a string value, the hours and minutes difference from GMT, whether daylight saving time applies denoted by is_dst, and a string value of the time difference from GMT that is gmt_string", "examples": [ { "gmt_string": "+01:00", "is_dst": false, "timezone": "Europe/Madrid" } ] }, "karma": { "type": "number", "title": "Karma", "description": "The user's karma score", "examples": [ 1024.0 ] }, "karma_trend": { "anyOf": [ { "type": "string", "enum": [ "up", "down", "-" ] }, { "type": "null" } ], "title": "Karma Trend", "description": "The user's karma trend. Can be 'up', 'down', or '-' (no change)", "examples": [ "up" ] }, "daily_goal": { "type": "integer", "title": "Daily Goal", "description": "The daily goal number of completed tasks for karma", "examples": [ 5 ] }, "weekly_goal": { "type": "integer", "title": "Weekly Goal", "description": "The target number of tasks to complete per week", "examples": [ 25 ] }, "days_off": { "items": { "type": "integer" }, "type": "array", "title": "Days Off", "description": "Array of integers representing user's days off (between 1 and 7, where 1 is Monday and 7 is Sunday)", "examples": [ [ 6, 7 ] ] }, "is_celebrations_enabled": { "type": "boolean", "title": "Is Celebrations Enabled", "description": "Whether celebration animations are enabled", "examples": [ true ] }, "completed_count": { "type": "integer", "title": "Completed Count", "description": "Total number of tasks completed by user", "examples": [ 42 ] }, "completed_today": { "type": "integer", "title": "Completed Today", "description": "Number of tasks completed today by the user", "examples": [ 3 ] }, "share_limit": { "type": "integer", "title": "Share Limit", "description": "Maximum number of collaborators allowed in shared projects", "examples": [ 5 ] }, "features": { "additionalProperties": true, "type": "object", "title": "Features", "description": "Feature flags and settings for the user", "examples": [ { "webhooks": true } ] }, "feature_identifier": { "type": "string", "title": "Feature Identifier", "description": "Feature identifier for feature flag evaluations", "examples": [ "1234567" ] }, "joinable_workspace": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Joinable Workspace", "description": "Information about workspaces the user can join", "examples": [ null ] }, "onboarding_completed": { "type": "boolean", "title": "Onboarding Completed", "description": "Whether the user has completed onboarding", "examples": [ true ] }, "onboarding_initiated": { "type": "boolean", "title": "Onboarding Initiated", "description": "Whether the user has initiated onboarding", "examples": [ true ] }, "onboarding_started": { "type": "boolean", "title": "Onboarding Started", "description": "Whether the user has started onboarding", "examples": [ true ] }, "onboarding_level": { "anyOf": [ { "type": "string", "enum": [ "beginner", "intermediate", "pro" ] }, { "type": "null" } ], "title": "Onboarding Level", "description": "User's self-reported skill level during onboarding", "examples": [ "intermediate" ] }, "onboarding_persona": { "anyOf": [ { "type": "string", "enum": [ "analog", "tasks", "calendar", "organic" ] }, { "type": "null" } ], "title": "Onboarding Persona", "description": "User's onboarding persona selection", "examples": [ "tasks" ] }, "onboarding_role": { "anyOf": [ { "type": "string", "enum": [ "leader", "founder", "ic" ] }, { "type": "null" } ], "title": "Onboarding Role", "description": "User's role selection during onboarding", "examples": [ "ic" ] }, "onboarding_team_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Onboarding Team Mode", "description": "Whether user selected team mode during onboarding", "examples": [ "solo" ] }, "onboarding_use_cases": { "anyOf": [ { "items": { "type": "string", "enum": [ "personal", "work", "education", "teamwork", "solo", "teamcreator", "simple", "teamjoiner" ] }, "type": "array" }, { "type": "null" } ], "title": "Onboarding Use Cases", "description": "Use cases the user selected during onboarding", "examples": [ [ "work" ] ] }, "getting_started_guide_projects": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Getting Started Guide Projects", "description": "List of project IDs for getting started guide", "examples": [ [ "6XGgm6PHrGgMpCFX" ] ] }, "onboarded_dated_tasks_created": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Onboarded Dated Tasks Created", "description": "True once the user has created at least 1 task with a due date that includes a time component (excluding auto-seeded getting-started-guide tasks).", "examples": [ true ] }, "onboarded_tasks_completed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Onboarded Tasks Completed", "description": "True once the user has completed at least 3 tasks.", "examples": [ true ] }, "onboarded_mobile_accessed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Onboarded Mobile Accessed", "description": "True once the user has synced from iOS or Android.", "examples": [ true ] }, "onboarded_desktop_accessed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Onboarded Desktop Accessed", "description": "True once the user has synced from Web, macOS, or Windows.", "examples": [ true ] }, "is_onboarded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Onboarded", "description": "Composite flag: true once all four onboarded_* criteria above are met.", "examples": [ true ] }, "activated_user": { "type": "boolean", "title": "Activated User", "description": "Whether the user is considered activated (completed key onboarding actions)", "examples": [ true ] }, "has_magic_number": { "type": "boolean", "title": "Has Magic Number", "description": "Whether the user has reached a magic number milestone", "examples": [ false ] }, "image_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Id", "description": "The ID of the user's avatar", "examples": [ "abc123" ] }, "avatar_big": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Big", "description": "The link to a 195x195 pixels image of the user's avatar", "examples": [ "https://dcff1xvirvpfp.cloudfront.net/avatar_big.jpg" ] }, "avatar_medium": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Medium", "description": "The link to a 60x60 pixels image of the user's avatar", "examples": [ "https://dcff1xvirvpfp.cloudfront.net/avatar_medium.jpg" ] }, "avatar_s640": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar S640", "description": "The link to a 640x640 pixels image of the user's avatar", "examples": [ "https://dcff1xvirvpfp.cloudfront.net/avatar_s640.jpg" ] }, "avatar_small": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Small", "description": "The link to a 35x35 pixels image of the user's avatar", "examples": [ "https://dcff1xvirvpfp.cloudfront.net/avatar_small.jpg" ] }, "websocket_url": { "type": "string", "title": "Websocket Url", "description": "WebSocket URL for real-time updates", "examples": [ "wss://ws.todoist.com/ws?token=0123456789abcdef" ] } }, "type": "object", "required": [ "id", "email", "full_name", "has_password", "verification_status", "mfa_enabled", "is_premium", "has_started_a_trial", "date_format", "sort_order", "theme_id", "theme_appearance", "start_day", "weekend_start_day", "next_week", "auto_reminder", "start_page", "lang", "tz_info", "karma", "daily_goal", "weekly_goal", "days_off", "is_celebrations_enabled", "completed_count", "completed_today", "share_limit", "features", "feature_identifier", "joinable_workspace", "onboarding_completed", "onboarding_initiated", "onboarding_started", "activated_user", "has_magic_number", "websocket_url" ], "title": "UserSyncView", "description": "A model for the user objects returned by the sync/REST API.\n\nThis model is used purely for OpenAPI documentation generation and does not\nhandle actual serialization (which is handled by @todoist.models.json.user.generate)." }, "V1orV2IDStr": { "type": "string" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WeeklyCompletionItem": { "properties": { "from": { "type": "string", "format": "date", "title": "From", "description": "Start date of the week (Monday, ISO 8601 format: YYYY-MM-DD)", "examples": [ "2025-02-10" ] }, "to": { "type": "string", "format": "date", "title": "To", "description": "End date of the week (Sunday, ISO 8601 format: YYYY-MM-DD)", "examples": [ "2025-02-16" ] }, "items": { "items": { "$ref": "#/components/schemas/ProjectCompletedItem" }, "type": "array", "title": "Items", "description": "Per-project completion breakdown for this week", "examples": [ [ { "completed": 12, "id": "6XGgm6PHrGgMpCFX" } ] ] }, "total_completed": { "type": "integer", "title": "Total Completed", "description": "Total number of tasks completed across all projects during this week", "examples": [ 12 ] } }, "type": "object", "required": [ "from", "to", "items", "total_completed" ], "title": "WeeklyCompletionItem", "description": "Completion statistics for a week." }, "WorkspaceInvitationView": { "properties": { "inviter_id": { "type": "string", "title": "Inviter Id", "description": "ID of the user user who sent the invitation", "examples": [ "1029384756" ] }, "user_email": { "type": "string", "title": "User Email", "description": "The invited person's email.", "examples": [ "foo@example.com" ] }, "workspace_id": { "type": "string", "title": "Workspace Id", "description": "ID of the workspace", "examples": [ "12345" ] }, "role": { "$ref": "#/components/schemas/WorkspaceRole", "description": "Workspace role granted by the invitation.", "examples": [ "MEMBER" ] }, "id": { "type": "string", "title": "Id", "description": "The ID of the invitation", "default": "0", "examples": [ "234" ] } }, "type": "object", "required": [ "inviter_id", "user_email", "workspace_id", "role" ], "title": "WorkspaceInvitationView" }, "WorkspaceLimitsSyncView": { "properties": { "current": { "$ref": "#/components/schemas/WorkspacePlanLimitSettings", "description": "Limits of the workspace's current plan." }, "next": { "anyOf": [ { "$ref": "#/components/schemas/WorkspacePlanLimitSettings" }, { "type": "null" } ], "description": "Limits of the next upgrade plan, or `null` if the workspace is already on the highest plan." } }, "type": "object", "required": [ "current", "next" ], "title": "WorkspaceLimitsSyncView", "description": "Current and next plan limits returned for a workspace in sync responses." }, "WorkspacePlanLimitSettings": { "properties": { "plan_name": { "type": "string", "title": "Plan Name" }, "max_projects": { "type": "integer", "title": "Max Projects" }, "max_collaborators": { "type": "integer", "title": "Max Collaborators" }, "upload_limit_mb": { "type": "integer", "title": "Upload Limit Mb" }, "automatic_backups": { "type": "boolean", "title": "Automatic Backups" }, "reminders": { "type": "boolean", "title": "Reminders" }, "reminders_at_due": { "type": "boolean", "title": "Reminders At Due" }, "max_guests_per_workspace": { "type": "integer", "title": "Max Guests Per Workspace" }, "max_folders_per_workspace": { "type": "integer", "title": "Max Folders Per Workspace" }, "advanced_permissions": { "type": "boolean", "title": "Advanced Permissions" }, "durations": { "type": "boolean", "title": "Durations" }, "calendar_layout": { "type": "boolean", "title": "Calendar Layout", "default": false }, "email_forwarding": { "type": "boolean", "title": "Email Forwarding", "default": true }, "email_ai_forwarding": { "type": "boolean", "title": "Email Ai Forwarding", "default": false }, "max_live_notifications": { "type": "integer", "title": "Max Live Notifications", "default": 500 }, "max_monthly_ramble": { "type": "integer", "title": "Max Monthly Ramble", "default": 10 }, "admin_tools": { "type": "boolean", "title": "Admin Tools", "default": false }, "security_controls": { "type": "boolean", "title": "Security Controls", "default": false }, "max_filters": { "type": "integer", "title": "Max Filters", "default": 3 }, "max_workspace_users": { "type": "integer", "title": "Max Workspace Users", "default": 0 }, "max_workspaces": { "type": "integer", "title": "Max Workspaces", "default": 50 }, "max_workspace_templates": { "type": "integer", "title": "Max Workspace Templates", "default": 100 }, "project_insights": { "type": "boolean", "title": "Project Insights", "default": false } }, "type": "object", "required": [ "plan_name", "max_projects", "max_collaborators", "upload_limit_mb", "automatic_backups", "reminders", "reminders_at_due", "max_guests_per_workspace", "max_folders_per_workspace", "advanced_permissions", "durations" ], "title": "WorkspacePlanLimitSettings" }, "WorkspaceProjectSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the project.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "can_assign_tasks": { "type": "boolean", "title": "Can Assign Tasks", "description": "Whether the current user can assign tasks in the project.", "examples": [ true ] }, "can_comment": { "type": "boolean", "title": "Can Comment", "description": "Whether the current user can comment in the project.", "examples": [ true ] }, "child_order": { "type": "integer", "title": "Child Order", "description": "Position of the project among sibling projects.", "examples": [ 1 ] }, "is_collapsed": { "type": "boolean", "title": "Is Collapsed", "description": "Whether the project is collapsed in the user's view.", "examples": [ false ] }, "color": { "type": "string", "title": "Color", "description": "Project color name.", "examples": [ "charcoal" ] }, "creator_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Creator Uid", "description": "String ID of the user who created the project.", "examples": [ "1234567" ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Created At", "description": "Date and time when the project was created, or `null` if unknown.", "examples": [ "2025-01-15T10:30:00Z" ] }, "is_archived": { "type": "boolean", "title": "Is Archived", "description": "Whether the project is archived.", "examples": [ false ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the project is deleted.", "examples": [ false ] }, "is_favorite": { "type": "boolean", "title": "Is Favorite", "description": "Whether the project is marked as a favorite.", "examples": [ false ] }, "is_frozen": { "type": "boolean", "title": "Is Frozen", "description": "Whether the project is frozen and cannot be modified.", "examples": [ false ] }, "name": { "type": "string", "title": "Name", "description": "Project name.", "examples": [ "Inbox" ] }, "is_shared": { "type": "boolean", "title": "Is Shared", "description": "Whether the project is shared with other users.", "examples": [ false ] }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Updated At", "description": "Date and time when the project was last updated, or `null` if unknown.", "examples": [ "2025-01-16T10:30:00Z" ] }, "view_style": { "type": "string", "title": "View Style", "description": "Project view style.", "examples": [ "list" ] }, "default_order": { "type": "integer", "title": "Default Order", "description": "Default order of the project in team views.", "examples": [ 1 ] }, "description": { "type": "string", "title": "Description", "description": "Project description.", "examples": [ "Tasks for the launch plan" ] }, "public_key": { "type": "string", "title": "Public Key", "description": "Public access key for the project, or an empty string when public access is disabled.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "access": { "anyOf": [ { "$ref": "#/components/schemas/ProjectAccessView" }, { "type": "null" } ], "description": "Project access configuration.", "examples": [ null ] }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "Current user's role in the project.", "examples": [ "admin" ] }, "collaborator_role_default": { "type": "string", "title": "Collaborator Role Default", "description": "Default collaborator role for the workspace project.", "examples": [ "member" ] }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folder Id", "description": "String ID of the folder that contains the project, or `null`.", "examples": [ "1234" ] }, "is_invite_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Invite Only", "description": "Whether joining the workspace project requires an invitation.", "examples": [ false ] }, "is_link_sharing_enabled": { "type": "boolean", "title": "Is Link Sharing Enabled", "description": "Whether invitation links are enabled for the project.", "examples": [ false ] }, "status": { "$ref": "#/components/schemas/ProjectStatus", "description": "Project status.", "examples": [ "in_progress" ] }, "workspace_id": { "type": "string", "title": "Workspace Id", "description": "String ID of the workspace that contains the project.", "examples": [ "123456" ] }, "is_pending_default_collaborator_invites": { "type": "boolean", "title": "Is Pending Default Collaborator Invites", "description": "Whether default collaborator invitations are still being created in the background.", "examples": [ false ] }, "is_project_insights_enabled": { "type": "boolean", "title": "Is Project Insights Enabled", "description": "Whether project insights are enabled for the project.", "examples": [ true ] }, "parent_id": { "type": "null", "title": "Parent Id", "description": "Always null for workspace projects." } }, "type": "object", "required": [ "id", "can_assign_tasks", "can_comment", "child_order", "is_collapsed", "color", "creator_uid", "created_at", "is_archived", "is_deleted", "is_favorite", "is_frozen", "name", "is_shared", "updated_at", "view_style", "default_order", "description", "public_key", "access", "role", "collaborator_role_default", "folder_id", "is_invite_only", "is_link_sharing_enabled", "status", "workspace_id", "is_pending_default_collaborator_invites", "is_project_insights_enabled" ], "title": "WorkspaceProjectSyncView", "description": "A representation of a Workspace Project Sync View, extending the base ProjectSync\nView, to be returned to clients in a sync (or sync-like) response." }, "WorkspaceProjectView": { "properties": { "initiated_by_uid": { "type": "integer", "title": "Initiated By Uid", "description": "Numeric ID of the user requesting the workspace project.", "examples": [ 1234567 ] }, "project_id": { "type": "string", "title": "Project Id", "description": "String ID of the project.", "examples": [ "6XGgm6PHrGgMpCFX" ] }, "workspace_id": { "type": "integer", "title": "Workspace Id", "description": "Numeric ID of the workspace that contains the project.", "examples": [ 123456 ] }, "public_access": { "type": "boolean", "title": "Public Access", "description": "Whether the project is publicly accessible.", "examples": [ false ] }, "access": { "anyOf": [ { "$ref": "#/components/schemas/ProjectAccessView" }, { "type": "null" } ], "description": "Project access configuration.", "examples": [ null ] }, "folder_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Folder Id", "description": "Numeric ID of the folder that contains the project, or `null`.", "examples": [ 1234 ] }, "is_invite_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Invite Only", "description": "Whether joining the workspace project requires an invitation.", "default": false, "examples": [ false ] }, "is_archived": { "type": "boolean", "title": "Is Archived", "description": "Whether the workspace project is archived.", "default": false, "examples": [ false ] }, "archived_timestamp": { "type": "integer", "title": "Archived Timestamp", "description": "Unix timestamp for when the project was archived, or 0 if active.", "default": 0, "examples": [ 0 ] }, "archived_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Archived Date", "description": "Date and time when the project was archived, or `null` if active.", "examples": [ null ] }, "is_frozen": { "type": "boolean", "title": "Is Frozen", "description": "Whether the project is frozen and cannot be modified.", "default": false, "examples": [ false ] }, "name": { "type": "string", "title": "Name", "description": "Project name.", "default": "", "examples": [ "Marketing" ] }, "color": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Color", "description": "Numeric project color code.", "default": 47, "examples": [ 47 ] }, "view_style": { "$ref": "#/components/schemas/ProjectViewStyle", "description": "Project view style.", "default": "list", "examples": [ "list" ] }, "description": { "type": "string", "title": "Description", "description": "Project description.", "default": "", "examples": [ "Marketing launch tasks" ] }, "status": { "$ref": "#/components/schemas/ProjectStatus", "description": "Project status.", "default": "IN_PROGRESS", "examples": [ "in_progress" ] }, "default_order": { "type": "integer", "title": "Default Order", "description": "Default order of the project in workspace views.", "default": 0, "examples": [ 1 ] }, "is_project_insights_enabled": { "type": "boolean", "title": "Is Project Insights Enabled", "description": "Whether project insights are enabled for the project.", "default": true, "examples": [ true ] }, "_role": { "anyOf": [ { "$ref": "#/components/schemas/CollaboratorRole" }, { "type": "null" } ], "title": "Role", "default": 0 } }, "type": "object", "required": [ "initiated_by_uid", "project_id", "workspace_id", "public_access", "access" ], "title": "WorkspaceProjectView" }, "WorkspaceProperties": { "properties": { "industry": { "anyOf": [ { "$ref": "#/components/schemas/Industry" }, { "type": "null" } ], "description": "Industry selected for the workspace.", "examples": [ "information_technology" ] }, "department": { "anyOf": [ { "$ref": "#/components/schemas/Department" }, { "type": "null" } ], "description": "Department selected for the workspace.", "examples": [ "engineering" ] }, "organization_size": { "anyOf": [ { "$ref": "#/components/schemas/OrganizationSize" }, { "type": "null" } ], "description": "Organization size selected for the workspace.", "examples": [ "size_11_to_50" ] }, "intended_team_size": { "anyOf": [ { "$ref": "#/components/schemas/IntendedTeamSize" }, { "type": "null" } ], "description": "Number of collaborators the creator intends to work with, selected during onboarding.", "examples": [ "size_2_to_10" ] }, "type_of_work": { "anyOf": [ { "$ref": "#/components/schemas/TypeOfWork" }, { "type": "null" } ], "description": "Type of work the team primarily does, selected during onboarding.", "examples": [ "projects" ] }, "creator_role": { "anyOf": [ { "$ref": "#/components/schemas/CreatorRole" }, { "type": "null" } ], "description": "Role selected by the workspace creator.", "examples": [ "owner_founder" ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "2-letter continent code, possible values are `AF`, `AS`, `EU`, `NA`, `SA`, `OC`, and `AN`.", "examples": [ "EU" ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "2-letter ISO 3166-1 alpha-2 country code.", "examples": [ "ES" ] }, "default_access_level": { "anyOf": [ { "$ref": "#/components/schemas/DefaultAccessLevel" }, { "type": "null" } ], "description": "Default access level for new workspace projects.", "default": "team", "examples": [ "team" ] }, "desktop_workspace_modal": { "anyOf": [ { "$ref": "#/components/schemas/DesktopWorkspaceModal" }, { "type": "null" } ], "description": "Desktop workspace modal variant shown to the user.", "examples": [ "TRIAL_OFFER" ] }, "beta_enabled": { "type": "boolean", "title": "Beta Enabled", "description": "Whether beta features are enabled for the workspace.", "default": false, "examples": [ false ] }, "acquisition_source": { "anyOf": [ { "$ref": "#/components/schemas/AcquisitionSource" }, { "type": "null" } ], "description": "Workspace acquisition source.", "examples": [ "high_paid_channel" ] }, "team_acquisition_cohort": { "anyOf": [ { "$ref": "#/components/schemas/TeamAcquisitionCohort" }, { "type": "null" } ], "description": "Team acquisition cohort assigned to the workspace.", "examples": [ "type_1_unaware" ] }, "acquisition_loop_last_show": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Acquisition Loop Last Show", "description": "Date when the acquisition loop was last shown in YYYY-MM-DD format.", "examples": [ "2025-02-12" ] }, "hdyhau": { "anyOf": [ { "$ref": "#/components/schemas/Hdyhau" }, { "type": "null" } ], "description": "How did you hear about us marketing attribution field.", "examples": [ "search_engine" ] }, "onboarding_filter_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Onboarding Filter Id", "description": "ID of the workspace assigned filter created during onboarding.", "examples": [ 1234 ] }, "created_platform": { "anyOf": [ { "$ref": "#/components/schemas/CreatedPlatform" }, { "type": "null" } ], "description": "Platform used to create this workspace.", "examples": [ "web" ] }, "imported_from": { "anyOf": [ { "type": "string", "const": "comms" }, { "type": "null" } ], "title": "Imported From", "description": "Product that created this workspace through a trusted import flow.", "examples": [ "comms" ] } }, "type": "object", "title": "WorkspaceProperties" }, "WorkspaceRole": { "type": "string", "enum": [ "ADMIN", "MEMBER", "GUEST" ], "title": "WorkspaceRole", "description": "Role of the user inside the workspace", "x-enumDescriptions": { "ADMIN": "Admin", "GUEST": "Guest", "MEMBER": "Member" } }, "WorkspaceSyncView": { "properties": { "id": { "type": "string", "title": "Id", "description": "String ID of the workspace.", "examples": [ "123456" ] }, "name": { "type": "string", "title": "Name", "description": "Workspace name.", "examples": [ "Doist" ] }, "description": { "type": "string", "title": "Description", "description": "Workspace description.", "examples": [ "Team workspace" ] }, "creator_id": { "type": "string", "title": "Creator Id", "description": "String ID of the user who created the workspace.", "examples": [ "1234567" ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Created At", "description": "Date and time when the workspace was created.", "examples": [ "2025-01-15T10:30:00Z" ] }, "is_deleted": { "type": "boolean", "title": "Is Deleted", "description": "Whether the workspace is deleted.", "examples": [ false ] }, "is_collapsed": { "type": "boolean", "title": "Is Collapsed", "description": "Whether the workspace is collapsed in the user's sidebar.", "examples": [ false ] }, "role": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceRole" }, { "type": "null" } ], "description": "Role of the current user in the workspace, or `null` if they are not part of it.", "examples": [ "ADMIN" ] }, "plan": { "$ref": "#/components/schemas/PlanType", "description": "The plan the workspace is currently on.", "examples": [ "STARTER" ] }, "pending_invitations": { "items": { "type": "string" }, "type": "array", "title": "Pending Invitations", "description": "Emails with a pending invitation to the workspace. Only populated for workspace members.", "examples": [ [ "foo@example.com" ] ] }, "is_link_sharing_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Link Sharing Enabled", "description": "Whether joining the workspace via a link is enabled. `null` for non-members.", "examples": [ true ] }, "is_guest_allowed": { "type": "boolean", "title": "Is Guest Allowed", "description": "Whether guests are allowed in the workspace.", "examples": [ true ] }, "is_trial_pending": { "type": "boolean", "title": "Is Trial Pending", "description": "Whether the workspace is waiting for trial confirmation.", "examples": [ false ] }, "invite_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invite Code", "description": "Opaque code to invite users to the workspace, or `null`.", "examples": [ "abc123" ] }, "limits": { "$ref": "#/components/schemas/WorkspaceLimitsSyncView", "description": "Current and next plan limits for the workspace." }, "current_member_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Member Count", "description": "Number of members in the workspace. `null` for non-members.", "examples": [ 5 ] }, "current_active_projects": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Active Projects", "description": "Number of active projects in the workspace. `null` for non-members.", "examples": [ 10 ] }, "domain_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain Name", "description": "Email domain associated with the workspace, or `null`.", "examples": [ "doist.com" ] }, "domain_discovery": { "type": "boolean", "title": "Domain Discovery", "description": "Whether users with a matching email domain can discover the workspace.", "examples": [ false ] }, "restrict_email_domains": { "type": "boolean", "title": "Restrict Email Domains", "description": "Whether membership is restricted to allowed email domains.", "examples": [ false ] }, "admin_sorting_applied": { "type": "boolean", "title": "Admin Sorting Applied", "description": "Whether an admin has applied custom project sorting.", "examples": [ false ] }, "user_sorting_applied": { "type": "boolean", "title": "User Sorting Applied", "description": "Whether the current user has sorted their workspace sidebar before.", "examples": [ false ] }, "project_sort_preference": { "$ref": "#/components/schemas/ProjectSortPreference", "description": "The current user's project sort preference.", "examples": [ "MANUAL" ] }, "default_collaborators": { "$ref": "#/components/schemas/DefaultCollaboratorsSyncView", "description": "Default collaborators for new workspace projects." }, "properties": { "additionalProperties": true, "type": "object", "description": "Additional workspace properties." }, "logo_s640": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo S640", "description": "URL of the workspace logo (640px)." }, "logo_big": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Big", "description": "URL of the workspace logo (195px)." }, "logo_medium": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Medium", "description": "URL of the workspace logo (60px)." }, "logo_small": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Small", "description": "URL of the workspace logo (35px)." }, "current_template_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Template Count", "description": "Number of active templates in the workspace. Only returned for workspace members.", "examples": [ 3 ] }, "pending_invites_by_type": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Pending Invites By Type", "description": "Number of pending invitations by workspace role. Only returned for workspace members.", "examples": [ { "admin_count": 0, "guest_count": 0, "member_count": 2 } ] }, "member_count_by_type": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Member Count By Type", "description": "Number of members by workspace role. Only returned for workspace members.", "examples": [ { "admin_count": 1, "guest_count": 0, "member_count": 4 } ] } }, "type": "object", "required": [ "id", "name", "description", "creator_id", "created_at", "is_deleted", "is_collapsed", "role", "plan", "pending_invitations", "is_link_sharing_enabled", "is_guest_allowed", "is_trial_pending", "invite_code", "limits", "current_member_count", "current_active_projects", "domain_name", "domain_discovery", "restrict_email_domains", "admin_sorting_applied", "user_sorting_applied", "project_sort_preference", "default_collaborators", "properties" ], "title": "WorkspaceSyncView", "description": "A class with fields representing a WorkspaceView which will be returned to\nclients in a sync (or sync-like) response.\n\nAlways construct instances through `from_view()`: `__json__` serializes\nwith `exclude_unset=True` so that fields `from_view()` deliberately leaves\nunset (member-only fields for non-members, `logo_*` fields for workspaces\nwithout a logo) are omitted from the response, exactly like the historical\n`WorkspaceView.__json__` output." }, "WorkspaceUserView": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "String ID of the workspace user.", "examples": [ "1234567" ] }, "workspace_id": { "type": "string", "title": "Workspace Id", "description": "String ID of the workspace.", "examples": [ "123456" ] }, "role": { "$ref": "#/components/schemas/WorkspaceRole", "description": "Workspace role assigned to the user.", "default": "MEMBER", "examples": [ "MEMBER" ] }, "custom_sorting_applied": { "type": "boolean", "title": "Custom Sorting Applied", "description": "Whether the user has custom project sorting enabled.", "default": false, "examples": [ false ] }, "project_sort_preference": { "$ref": "#/components/schemas/ProjectSortPreference", "description": "Project sorting preference for the user.", "default": "MANUAL", "examples": [ "MANUAL" ] } }, "type": "object", "required": [ "user_id", "workspace_id" ], "title": "WorkspaceUserView" }, "_BackupResponse": { "properties": { "version": { "type": "string", "title": "Version", "description": "Date and time of the backup version", "examples": [ "2025-02-13 02:03" ] }, "url": { "type": "string", "title": "Url", "description": "Backup URL", "examples": [ "https://api.todoist.com/api/v1/backups/download?file=12345678901234567890123456789012.zip" ] } }, "type": "object", "required": [ "version", "url" ], "title": "_BackupResponse" }, "_BillingPortalUrlResponse": { "properties": { "billing_portal_url": { "type": "string", "title": "Billing Portal Url" } }, "type": "object", "required": [ "billing_portal_url" ], "title": "_BillingPortalUrlResponse" }, "_CreditStateResponse": { "properties": { "available_units": { "type": "integer", "title": "Available Units", "description": "Balance net of in-flight holds (`available_cached - held`). The ledger unit, kept for support and reconciliation; display `available_amount` instead. Not a permission to start a run: use `usage_allowed` for that.", "examples": [ 4186300 ] }, "available_amount": { "type": "integer", "title": "Available Amount", "description": "`available_units` in money, in microdollars (millionths of one `currency` unit), so 8372600 is $8.3726. The scale is exact for every amount this API reports; cents and hundredths of a cent both truncate a single chat message to zero. Converted by the server because the client cannot: the ratio is the account's pinned price and only the backend holds it.", "examples": [ 8372600 ] }, "currency": { "type": "string", "title": "Currency", "description": "ISO currency code every amount in this response is in. Fixed for the life of the account: the first top-up pins the price, and the price fixes the currency.", "examples": [ "usd" ] }, "usage_allowed": { "type": "boolean", "title": "Usage Allowed", "description": "Whether a new run may start right now.", "examples": [ true ] }, "low_balance": { "type": "boolean", "title": "Low Balance", "description": "Balance is at or below the low-balance threshold." }, "depleted": { "type": "boolean", "title": "Depleted", "description": "No further runs may start. Equivalent to `usage_allowed` being false; can be true while `available_units` is still positive, because the floor holds back one run's worth." } }, "type": "object", "required": [ "available_units", "available_amount", "currency", "usage_allowed", "low_balance", "depleted" ], "title": "_CreditStateResponse" }, "_EmailResponse": { "properties": { "email": { "type": "string", "title": "Email", "description": "Email address for the Todoist object.", "examples": [ "add.task@example.todoist.net" ] } }, "type": "object", "required": [ "email" ], "title": "_EmailResponse" }, "_GetDataV2Response": { "properties": { "project": { "anyOf": [ { "$ref": "#/components/schemas/PersonalProjectSyncView" }, { "$ref": "#/components/schemas/WorkspaceProjectSyncView" }, { "type": "null" } ], "title": "Project", "description": "Project details returned after joining." }, "tasks": { "items": { "$ref": "#/components/schemas/ItemSyncView" }, "type": "array", "title": "Tasks", "description": "Tasks in the joined project." }, "sections": { "items": { "$ref": "#/components/schemas/SectionSyncView" }, "type": "array", "title": "Sections", "description": "Sections in the joined project." }, "comments": { "items": { "$ref": "#/components/schemas/ProjectNoteSyncView" }, "type": "array", "title": "Comments", "description": "Comments in the joined project." }, "collaborators": { "items": { "$ref": "#/components/schemas/ExposedCollaborator" }, "type": "array", "title": "Collaborators", "description": "Collaborators with access to the joined project.", "examples": [ [ { "email": "ada@example.com", "full_name": "Ada Lovelace", "id": "123456", "is_deleted": false, "timezone": "Europe/London" } ] ] }, "collaborator_states": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Collaborator States", "description": "Collaborator state records for the joined project.", "examples": [ [ { "is_deleted": false, "project_id": "6XGgff2vcGGQCQvj", "state": "active", "user_id": "2671355" } ] ] }, "folder": { "anyOf": [ { "$ref": "#/components/schemas/FolderView" }, { "type": "null" } ], "description": "Folder containing the project, or `null` when it is not in a folder.", "examples": [ null ] }, "subprojects": { "items": { "anyOf": [ { "$ref": "#/components/schemas/PersonalProjectSyncView" }, { "$ref": "#/components/schemas/WorkspaceProjectSyncView" } ] }, "type": "array", "title": "Subprojects", "description": "Subprojects of the joined project." } }, "type": "object", "required": [ "project", "tasks", "sections", "comments", "collaborators", "collaborator_states", "folder", "subprojects" ], "title": "_GetDataV2Response" }, "_HistoryEntry": { "properties": { "id": { "type": "integer", "title": "Id", "description": "Ledger entry id.", "examples": [ 8814 ] }, "type": { "type": "string", "title": "Type", "description": "What moved the balance: `usage_settled`, `top_up`, `void`, `expiry` or `chargeback`.", "examples": [ "usage_settled" ] }, "created_at": { "type": "string", "title": "Created At", "description": "When the entry was written, UTC.", "examples": [ "2026-06-10T14:00:00Z" ] }, "category": { "type": "string", "title": "Category", "description": "What produced the entry, within its `type`: `automation_run`, `paid`, `promotional` or `stripe`.", "examples": [ "automation_run" ] }, "status": { "type": "string", "title": "Status", "description": "Outcome of the run this entry settles: `success`, `failed`, `cancelled`, `timed_out` or `partial`. Present on `usage_settled` only. It does not change the amount: every terminal outcome draws the cost the run actually incurred.", "examples": [ "success" ] }, "charged_units": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Charged Units", "description": "Units taken off the balance, as a positive number, or `null` on a credit, which has no debit side. `0` is a real value and not an absent one: a run that failed before it reached the provider cost nothing. Not a usage figure on its own: `void`, `expiry` and `chargeback` are debits too, so summing this field across types overstates usage by every reversed grant. Filter on `type` to total usage.", "examples": [ 13700 ] }, "charged_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Charged Amount", "description": "`charged_units` in money, in microdollars (millionths of one page-level `currency` unit), so 27400 is $0.0274. `null` exactly when `charged_units` is.", "examples": [ 27400 ] }, "credited_units": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Credited Units", "description": "Units added to the balance, as a positive number, or `null` on a debit. Set on credits (`top_up`).", "examples": [ 5000000 ] }, "credited_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Credited Amount", "description": "`credited_units` in money, in microdollars (millionths of one page-level `currency` unit), so 10000000 is $10.00. `null` exactly when `credited_units` is.", "examples": [ 10000000 ] }, "refs": { "additionalProperties": true, "type": "object", "title": "Refs", "description": "Free-form attribution for the entry. Contents vary by `type` and are not part of the API contract." }, "description": { "type": "string", "title": "Description", "description": "Human-readable summary of the entry.", "examples": [ "Top-up USD 1000" ] } }, "type": "object", "required": [ "id", "type", "created_at", "charged_units", "charged_amount", "credited_units", "credited_amount" ], "title": "_HistoryEntry" }, "_HistoryResponse": { "properties": { "currency": { "type": "string", "title": "Currency", "description": "ISO currency code every amount in this page is in. On the page rather than on each entry: the account pins one price for its whole life (spec section 8), so no two entries can differ.", "examples": [ "usd" ] }, "entries": { "items": { "$ref": "#/components/schemas/_HistoryEntry" }, "type": "array", "title": "Entries", "description": "Ledger entries in the current page, newest first." }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether another page of results is available.", "examples": [ false ] }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "Cursor for the next page of results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] } }, "type": "object", "required": [ "currency", "entries", "has_more" ], "title": "_HistoryResponse" }, "_MigratePersonalTokenResponse": { "properties": { "access_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Access Token", "description": "OAuth access token created from the personal token.", "examples": [ "0123456789abcdef0123456789abcdef01234567" ] }, "token_type": { "type": "string", "const": "Bearer", "title": "Token Type", "description": "OAuth token type.", "examples": [ "Bearer" ] }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Access token lifetime in seconds.", "examples": [ 315360000 ] } }, "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "title": "_MigratePersonalTokenResponse" }, "_PlanDetailsResponse": { "properties": { "current_member_count": { "type": "integer", "title": "Current Member Count", "description": "Current number of active workspace members.", "examples": [ 10 ] }, "current_plan": { "type": "string", "enum": [ "Business", "Starter" ], "title": "Current Plan", "description": "Current workspace plan.", "examples": [ "Business" ] }, "current_plan_status": { "type": "string", "enum": [ "Active", "Downgraded", "Cancelled", "NeverSubscribed" ], "title": "Current Plan Status", "description": "Current workspace plan status.", "examples": [ "Active" ] }, "downgrade_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Downgrade At", "description": "Date when the workspace downgrades, or `null` if not scheduled.", "examples": [ null ] }, "current_active_projects": { "type": "integer", "title": "Current Active Projects", "description": "Current number of active workspace projects.", "examples": [ 12 ] }, "maximum_active_projects": { "type": "integer", "title": "Maximum Active Projects", "description": "Maximum number of active projects allowed by the plan.", "examples": [ 500 ] }, "price_list": { "items": { "$ref": "#/components/schemas/FormattedPriceListing" }, "type": "array", "title": "Price List", "description": "Available plan prices for the workspace country.", "examples": [ [ { "billing_cycle": "monthly", "prices": [ { "currency": "USD", "tax_behavior": "exclusive", "unit_amount": 600 } ] } ] ] }, "workspace_id": { "type": "integer", "title": "Workspace Id", "description": "ID of the workspace.", "examples": [ 123456 ] }, "is_trialing": { "type": "boolean", "title": "Is Trialing", "description": "Whether the workspace is currently trialing a paid plan.", "examples": [ false ] }, "trial_ends_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trial Ends At", "description": "Date when the current trial ends, or `null` if not trialing.", "examples": [ null ] }, "cancel_at_period_end": { "type": "boolean", "title": "Cancel At Period End", "description": "Whether the plan cancels at the end of the billing period.", "examples": [ false ] }, "has_trialed": { "type": "boolean", "title": "Has Trialed", "description": "Whether the workspace has already used a trial.", "examples": [ true ] }, "plan_price": { "anyOf": [ { "$ref": "#/components/schemas/PlanPrice" }, { "type": "null" } ], "description": "Current subscription price, or `null` when there is no active subscription.", "examples": [ null ] }, "has_billing_portal": { "type": "boolean", "title": "Has Billing Portal", "description": "Whether a billing portal is available for the workspace.", "examples": [ true ] }, "has_billing_portal_switch_to_annual": { "type": "boolean", "title": "Has Billing Portal Switch To Annual", "description": "Whether the billing portal can switch the subscription to annual billing.", "examples": [ false ] } }, "type": "object", "required": [ "current_member_count", "current_plan", "current_plan_status", "downgrade_at", "current_active_projects", "maximum_active_projects", "price_list", "workspace_id", "is_trialing", "trial_ends_at", "cancel_at_period_end", "has_trialed", "plan_price", "has_billing_portal", "has_billing_portal_switch_to_annual" ], "title": "_PlanDetailsResponse" }, "_ProjectsResponse": { "properties": { "has_more": { "type": "boolean", "title": "Has More", "description": "Whether another page of results is available.", "examples": [ false ] }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "Cursor for the next page of results.", "examples": [ "14540000435w8hj8pXXwPQJJch.X9DBH8ya2Xenok55" ] }, "workspace_projects": { "items": { "$ref": "#/components/schemas/WorkspaceProjectView" }, "type": "array", "title": "Workspace Projects", "description": "Workspace projects in the current page.", "examples": [ [ { "access": { "configuration": {}, "visibility": "team" }, "can_assign_tasks": true, "color": "charcoal", "default_order": 1, "description": "Marketing launch tasks", "folder_id": "1234", "id": "6XGgm6PHrGgMpCFX", "is_frozen": false, "is_invite_only": false, "is_pending_default_collaborator_invites": false, "name": "Marketing", "public_access": false, "public_key": "ab12cd34ef56", "role": "ADMIN", "status": "in_progress", "view_style": "list" } ] ] } }, "type": "object", "required": [ "has_more", "workspace_projects" ], "title": "_ProjectsResponse" }, "_StatusOkResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status", "description": "Always `ok` on success.", "examples": [ "ok" ] } }, "type": "object", "required": [ "status" ], "title": "_StatusOkResponse" }, "_TopUpResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id", "description": "The created Stripe Checkout session id.", "examples": [ "cs_live_a1b2c3" ] }, "checkout_url": { "type": "string", "title": "Checkout Url", "description": "Hosted Stripe Checkout URL to redirect the user to for payment.", "examples": [ "https://checkout.stripe.com/c/pay/cs_live_a1b2c3" ] } }, "type": "object", "required": [ "session_id", "checkout_url" ], "title": "_TopUpResponse" }, "_UsageSummaryResponse": { "properties": { "currency": { "type": "string", "title": "Currency", "description": "ISO currency code every amount in this response is in. Fixed for the life of the account: the first top-up pins the price, and the price fixes the currency.", "examples": [ "usd" ] }, "usage_count": { "type": "integer", "title": "Usage Count", "description": "How many usage events settled in the window. One per unit of billable work: an automation run, or a chat message. Narrow it with `category` to count one kind. A run that failed before it reached the provider counts here and adds 0 to the amounts: it happened, and it cost nothing.", "examples": [ 412 ] }, "charged_units": { "type": "integer", "title": "Charged Units", "description": "Units those events took off the balance, as a positive number. The ledger unit, kept for support and reconciliation; display `charged_amount` instead. Covers settled usage only, so it is smaller than the sum of `charged_units` over the same window in `/history`, which also carries reversed grants.", "examples": [ 5643900 ] }, "charged_amount": { "type": "integer", "title": "Charged Amount", "description": "`charged_units` in money, in microdollars (millionths of one `currency` unit), so 11287800 is $11.2878. Divide by `usage_count` for the per-run figure; guard the zero case, because an account with no usage reports 0 for both.", "examples": [ 11287800 ] } }, "type": "object", "required": [ "currency", "usage_count", "charged_units", "charged_amount" ], "title": "_UsageSummaryResponse" }, "_UsersResponse": { "properties": { "has_more": { "type": "boolean", "title": "Has More", "description": "Whether more results are available.", "examples": [ false ] }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "Cursor for the next page of results.", "examples": [ "eyJpZCI6MTIzfQ" ] }, "workspace_users": { "items": { "$ref": "#/components/schemas/MemberView" }, "type": "array", "title": "Workspace Users", "description": "Workspace users in the current page.", "examples": [ [ { "full_name": "Dain Ironfoot", "image_id": "abc123", "is_deleted": false, "role": "MEMBER", "timezone": "Europe/Madrid", "user_email": "example@email.org", "user_id": "1234567", "workspace_id": "123456" } ] ] } }, "type": "object", "required": [ "has_more", "workspace_users" ], "title": "_UsersResponse" } } }, "tags": [ { "name": "Todoist CLI", "description": "Use Todoist from your terminal with the official, open-source\n[Todoist CLI](https://www.todoist.com/cli). It is useful for quick task capture,\nterminal workflows, local scripts, and giving AI coding agents access to the\nsame task list you use in Todoist.\n\n## Installation\n\nInstall the npm package:\n\n```shell\nnpm install -g @doist/todoist-cli\n```\n\nThen authenticate with Todoist:\n\n```shell\ntd auth login\n```\n\nThis opens your browser to authenticate with Todoist. Once approved, the token\nis stored in your operating system credential manager.\n\n## Common commands\n\n```shell\ntd add \"Buy milk tomorrow #Shopping\"\ntd today\ntd inbox\ntd task list\ntd task list --project \"Work\"\ntd project list\n```\n\nRun `td --help` or `td --help` for the full command reference.\n\n## Agent skills\n\nThe CLI can install maintained skills for coding agents:\n\n```shell\ntd skill install claude-code\ntd skill install codex\ntd skill install copilot\ntd skill install cursor\ntd skill install gemini\ntd skill install pi\ntd skill install universal\n```\n\nUse `td skill list` to see installed skills and `td skill uninstall ` to\nremove one.\n\n## Shell completions\n\nTab completion is available for bash, zsh, and fish:\n\n```shell\ntd completion install\ntd completion install zsh\n```\n\nFor source code, issues, releases, and contribution details, visit the\n[Doist/todoist-cli repository](https://github.com/Doist/todoist-cli).\n" }, { "name": "Todoist MCP", "description": "Integrate AI assistants with Todoist using the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), an open standard for secure access to your tasks and projects. Our hosted MCP server works with Claude, ChatGPT, Cursor, and VS Code.\n\n- **Easy setup:** OAuth in a minute. \n- **Full access:** Read, create, and update your tasks & projects. \n- **Use cases:** Daily reviews, project planning, natural-language queries.\n\n## Setup guide\n\n**Primary URL (Streamable HTTP):**\n\n`https://ai.todoist.net/mcp`\n\n### Claude\n1. Open **Settings \u2192 Connectors \u2192 Add custom connector**. \n2. Enter `https://ai.todoist.net/mcp` and complete OAuth.\n\n### Cursor\n\nCreate `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):\n\n```json\n{\n \"mcpServers\": {\n \"todoist\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-remote\", \"https://ai.todoist.net/mcp\"]\n }\n }\n}\n```\n\nThen enable the server in Cursor settings if prompted.\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add --transport http todoist https://ai.todoist.net/mcp\n```\n\n### Visual Studio Code\n\nCommand Palette \u2192 MCP: Add Server \u2192 Type HTTP and use:\n\n```json\n{\n \"servers\": {\n \"todoist\": {\n \"type\": \"http\",\n \"url\": \"https://ai.todoist.net/mcp\"\n }\n }\n}\n```\n\n\n### Other Clients\n\n`npx -y mcp-remote https://ai.todoist.net/mcp`\n\n## Tool response format\n\nEvery `tools/call` response from the Todoist MCP server includes the same data in three forms. This mirrors the standard MCP tool result shape, but it is worth calling out because different MCP clients expose different parts of it to the model or to the calling application.\n\n```json\n{\n \"result\": {\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"{\\\"tasks\\\":[{\\\"id\\\":\\\"...\\\",\\\"content\\\":\\\"...\\\",\\\"priority\\\":4},...],\\\"totalCount\\\":2,\\\"hasMore\\\":false,\\\"appliedFilters\\\":{\\\"limit\\\":10,\\\"filter\\\":\\\"today\\\"}}\"\n },\n {\n \"type\": \"text\",\n \"text\": \"Tasks matching filter: today: 2 (limit 10).\\nFilter: filter: today.\"\n }\n ],\n \"structuredContent\": {\n \"tasks\": [\n { \"id\": \"...\", \"content\": \"...\", \"priority\": 4 }\n ],\n \"totalCount\": 2,\n \"hasMore\": false,\n \"appliedFilters\": { \"limit\": 10, \"filter\": \"today\" }\n }\n }\n}\n```\n\n### Fields\n\n- **Stringified JSON of `structuredContent`** \u2014 included as a `text` content item, for compatibility with clients that surface text content but do not yet expose `structuredContent`. For tools that only return text and structured data (the majority of Todoist tools) this is `content[0]`. For tools that also return non-text content items such as images or embedded resources (for example, `view-attachment`), those tool-authored items come first and the JSON `text` item follows them.\n- **Human-readable summary** \u2014 always the **last** `text` content item in the `content[]` array. Intended for display to end users or for models that only consume text. Not intended to be parsed.\n- **`structuredContent`** \u2014 the same payload as the JSON `text` item, already parsed as a JSON object. Available to clients implementing MCP spec revision `2025-03-26` or later.\n\nThe JSON `text` item and `structuredContent` always contain the same data. The trailing summary is derived from that data and is not intended to be parsed.\n\n### Which field should you consume?\n\n- **Direct JSON-RPC callers:** prefer `structuredContent`. If your client targets an older MCP spec revision, parse the JSON `text` item \u2014 locate it by checking each `text` content item for a JSON payload rather than by hard-coded index.\n- **Callers routing through an AI orchestration layer** (for example, the OpenAI Responses API, an agent framework, or another LLM client): check which content items that layer surfaces back to you. Some clients pass through all parts of the tool response; others expose only the first content item.\n\n### Client compatibility note\n\nIf two MCP clients appear to receive different data from the same Todoist tool call, the difference is almost always in how the client surfaces the response \u2014 not in what the server returns. The Todoist MCP server returns the same `content[]` array and `structuredContent` object to every caller.\n\nFor example:\n\n- **Claude** and **Claude Code** process all content items and `structuredContent`, so the model has access to the full structured payload.\n- The **OpenAI Responses API** surfaces only `content[0]` to the caller and strips `structuredContent`. For tools that return only text and structured data, `content[0]` is the stringified JSON payload and callers can parse it directly. For tools that also return non-text content items (for example, `view-attachment` returning an image), `content[0]` is the tool-authored item; callers needing the structured payload from those tools should access the server via direct JSON-RPC.\n\nIf you are debugging unexpected output, inspect the raw JSON-RPC response from `ai.todoist.net/mcp` before assuming a server-side difference.\n\n" }, { "name": "Authorization", "description": "
\n

An authenticated request with authorization header:

\n
\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d sync_token='*' \\\n -d resource_types='[\"all\"]'\n```\n\nIn order to make authorized calls to the Sync API, your application must provide\nan [authorization\nheader](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)\nwith the appropriate `Bearer $token`. For working through the examples, you can\nobtain your personal API token from the [integrations\nsettings](https://app.todoist.com/app/settings/integrations) for your account.\n\nTo authenticate other users, your application will need to obtain a token from\nthem using the OAuth protocol. For information on how to obtain a token from our\nservice using OAuth, please see the [authorization\nguide](/guides/#authorization).\n\nFor the sake of simplicity the token is not listed on every parameter table but\nplease note that the **token parameter is required for every resource**.\n\n## OAuth\n\nOAuth is also available for token generation. It's especially useful for\nexternal applications to obtain a user authorized API token via the OAuth2\nprotocol. Before getting started, developers need to create their applications\nin the [App Management Console](https://app.todoist.com/app/settings/integrations/app-management)\nand configure one or more valid OAuth2 redirect URLs. A registered Todoist\napplication is assigned a unique `Client ID` and `Client Secret` which are\nneeded for the OAuth2 flow.\n\nThis procedure is comprised of 3 steps.\n\n### Step 1: Authorization request\n\n> An example of the URL to the authorization endpoint:\n\n```shell\nhttps://app.todoist.com/oauth/authorize?client_id=0123456789abcdef&scope=data:read,data:delete&state=secretstring&response_type=code\n```\n\nRedirect users to the authorization URL at the endpoint\n`https://app.todoist.com/oauth/authorize`, with the specified request parameters.\n\n#### Required parameters\n\n| Name | Description |\n| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| client_id | The unique Client ID of the Todoist application that you registered. |\n| scope | A comma separated list of permissions that you would like the users to grant to your application. See the below table for detail on the available scopes. |\n| state | A unique and unguessable string. It is used to protect you against cross-site request forgery attacks. |\n\n#### Optional parameters\n\n| Name | Description |\n| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| redirect_uri | The redirect URL for your application. If your application has multiple redirect URIs configured, this parameter is **required** \u2014 the request will be rejected with `invalid_request` if it is omitted. |\n| response_type | Todoist supports the authorization code flow. This parameter may be omitted or set to `code`. Other values are rejected with `unsupported_response_type`. |\n\n#### Permission scopes\n\n| Name | Description |\n| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| task:add | Grants permission to add new tasks (the application cannot read or modify any existing data). |\n| data:read | Grants read-only access to application data, including tasks, projects, labels, and filters. |\n| data:read_write | Grants read and write access to application data, including tasks, projects, labels, and filters. This scope includes `task:add` and `data:read` scopes. |\n| data:delete | Grants permission to delete application data, including tasks, labels, and filters. |\n| project:delete | Grants permission to delete projects. |\n| backups:read | Grants permission to list backups with `GET /api/v1/backups` without MFA. Downloading a backup with `GET /api/v1/backups/download` still requires `data:read_write`. |\n\n\n#### Potential errors\n\n| Error | Description |\n| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| User Rejected Authorization Request | When the user denies your authorization request, Todoist will redirect the user to the configured redirect URI with the `error` parameter: `http://example.com?error=access_denied`. |\n| Redirect URI Not Configured | This JSON error will be returned to the requester (your user's browser) if redirect URI is not configured in the App Management Console. |\n| Invalid Application Status | When your application exceeds the maximum token limit or when your application is being suspended due to abuse, Todoist will redirect the user to the configured redirect URI with the `error` parameter: `http://example.com?error=invalid_application_status`. |\n| Invalid Scope | When the `scope` parameter is invalid, Todoist will redirect the user to the configured redirect URI with `error` parameter: `http://example.com?error=invalid_scope`. |\n| Unsupported Response Type | When the `response_type` parameter is set to a value other than `code`, Todoist will redirect the user to the configured redirect URI with `error` parameter: `http://example.com?error=unsupported_response_type`. |\n\n### Step 2: Redirection to your application site\n\nWhen the user grants your authorization request, the user will be redirected to\nthe redirect URL configured for your application. The redirect request\nwill come with two query parameters attached: `code` and `state`.\n\nThe `code` parameter contains the authorization code that you will use to\nexchange for an access token. The `state` parameter should match the `state`\nparameter that you supplied in the previous step. If the `state` is unmatched,\nyour request has been compromised by other parties, and the process should be\naborted.\n\n### Step 3: Token exchange\n\n> An example of exchanging the token:\n\n```shell\n$ curl \"https://api.todoist.com/oauth/access_token\" \\\n -d \"client_id=0123456789abcdef\" \\\n -d \"client_secret=secret\" \\\n -d \"code=abcdef\" \\\n -d \"redirect_uri=https://example.com\"\n```\n\n> On success, Todoist returns HTTP 200 with the token in JSON object format. For\n> applications with refresh tokens enabled (the default for newly-created apps),\n> the response also includes `expires_in` and `refresh_token`:\n\n```json\n{\n \"access_token\": \"0123456789abcdef0123456789abcdef01234567\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"refresh_token\": \"abcdef0123456789abcdef0123456789abcdef01\",\n \"scope\": \"data:read_write\"\n}\n```\n\n> Legacy applications without refresh tokens enabled receive a response whose\n> `expires_in` is a 10-year compatibility value (`315360000`) rather than a\n> meaningful expiry, and no `refresh_token`. These access tokens are long-lived\n> and will continue to work:\n\n```json\n{\n \"access_token\": \"0123456789abcdef0123456789abcdef01234567\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 315360000\n}\n```\n\nOnce you have the authorization `code`, you can exchange it for the access token\nby sending a `POST` request to the following endpoint:\n\n`https://api.todoist.com/oauth/access_token`.\n\n#### Required parameters\n\n| Name | Description |\n| ------------- | ------------------------------------------------------------------------------------ |\n| client_id | The Client ID of the Todoist application that you registered. |\n| client_secret | The Client Secret of the Todoist application that you registered. |\n| code | The code that was sent in the query string to the redirect URL in the previous step. |\n\n#### Potential errors\n\n| Error | Description |\n| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| Bad Authorization Code Error | Occurs when the `code` parameter does not match the code that is given in the redirect request: `{\"error\": \"bad_authorization_code\"}` |\n| Incorrect Client Credentials Error | Occurs when the `client_id` or `client_secret` parameters are incorrect: `{\"error\": \"incorrect_application_credentials\"}` |\n\n## Dynamic Client Registration\n\n> Registering a new dynamic client:\n\n```shell\n$ curl \"https://api.todoist.com/oauth/register\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"client_name\": \"My App\",\n \"redirect_uris\": [\"https://example.com/callback\"],\n \"scope\": \"data:read_write\",\n \"grant_types\": [\"authorization_code\", \"refresh_token\"],\n \"response_types\": [\"code\"],\n \"token_endpoint_auth_method\": \"client_secret_post\"\n }'\n```\n\n> On success, Todoist returns HTTP 201 Created with a newly-issued\n> client in [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)\n> format. The response includes `Cache-Control: no-store` and\n> `Pragma: no-cache` headers, also per RFC 7591 \u00a73.2.1:\n\n```json\n{\n \"client_id\": \"tdd_0123456789abcdef0123456789abcdef\",\n \"client_secret\": \"abcdef0123456789abcdef0123456789abcdef01\",\n \"client_name\": \"My App\",\n \"redirect_uris\": [\"https://example.com/callback\"],\n \"scope\": \"data:read_write\",\n \"grant_types\": [\"authorization_code\", \"refresh_token\"],\n \"response_types\": [\"code\"],\n \"token_endpoint_auth_method\": \"client_secret_post\",\n \"client_id_issued_at\": 1776865756,\n \"client_secret_expires_at\": 0\n}\n```\n\nClients that cannot pre-register through the App Management Console \u2014\nnotably multi-tenant integrations, MCP servers, and AI agents acting on\nbehalf of an end user \u2014 can register themselves at runtime via\n[RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591).\n\nSend a `POST` to `https://api.todoist.com/oauth/register` with a JSON\nbody describing the client. No authentication is required, but the\nendpoint is rate limited per caller.\n\n### Request parameters\n\n| Name | Required | Description |\n| -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| redirect_uris | Yes | Array of redirect URIs. Up to 10 entries, each \u2264512 characters. Must be HTTPS (localhost is allowed for testing). |\n| client_name | No | Human-readable name shown on the consent screen. |\n| client_uri | No | Public URL for the application. |\n| logo_uri | No | Public URL for the application logo. |\n| scope | No | Space-separated scopes the client will request. Restricted scopes are rejected. Defaults to `data:read_write` when omitted. |\n| grant_types | No | Array of supported grant types. Must include `authorization_code`. Include `refresh_token` to use token refresh. Defaults to `[\"authorization_code\"]`. |\n| response_types | No | Array of supported response types. Must include `code`. Defaults to `[\"code\"]`. |\n| token_endpoint_auth_method | No | One of `client_secret_post` (default), `client_secret_basic`, or `none` (public client using PKCE). |\n\n### Response\n\nDynamic clients are identified by a `tdd_` prefix on `client_id`. The\n`client_secret_expires_at` field is `0` \u2014 client secrets do not expire.\nUse the returned credentials with the standard\n[authorization code flow](#step-1-authorization-request) above.\n\n### Potential errors\n\n| Error | Description |\n| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Invalid Client Metadata | A field failed validation \u2014 e.g. a redirect URI is malformed or not HTTPS, or `grant_types` omits `authorization_code`: `{\"error\": \"invalid_client_metadata\"}`. |\n| Invalid Scope | A requested scope is unknown or restricted to first-party use: `{\"error\": \"invalid_scope\"}`. |\n| Rate Limit Exceeded | Too many registration requests in a short period; retry later. |\n\n## OAuth Client ID Metadata Document\n\n> Example metadata document hosted by the client at its `client_id` URL:\n\n```json\n{\n \"client_id\": \"https://example.com/oauth-client-metadata.json\",\n \"client_name\": \"My App\",\n \"redirect_uris\": [\"https://example.com/callback\"],\n \"grant_types\": [\"authorization_code\", \"refresh_token\"],\n \"response_types\": [\"code\"],\n \"token_endpoint_auth_method\": \"none\"\n}\n```\n\nAs an alternative to RFC 7591 registration, Todoist supports\n[OAuth Client ID Metadata Documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)\n\u2014 a zero-registration flow in which the `client_id` itself is an HTTPS\nURL pointing to a JSON metadata document describing the client. The\nauthorization server fetches and validates the document on demand, so\nclients don't pre-register at all.\n\nThis is intended for public clients that cannot safely store a\n`client_secret` (browser-based SPAs, desktop apps, MCP servers). Clients\nprotect themselves with PKCE during the authorization code exchange\ninstead of a client secret.\n\n### Hosting the document\n\nHost a JSON document at an HTTPS URL you control. The URL must:\n\n- use the `https://` scheme (no plaintext HTTP)\n- include a path component beyond `/` (e.g. `/oauth/client.json`)\n- resolve to a publicly routable IP address (private and loopback ranges are rejected for SSRF protection)\n\nTodoist enforces a **5KB maximum size** and a **5-second fetch timeout**\non the document. Redirects are not followed.\n\n### Document fields\n\n| Field | Required | Description |\n| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |\n| client_id | Yes | Must exactly match the URL the document was fetched from. |\n| redirect_uris | Yes | Non-empty array of redirect URIs. Must be HTTPS (localhost allowed for testing). |\n| token_endpoint_auth_method | Yes | Must be `\"none\"`. Metadata clients are public clients by design and cannot hold a symmetric secret. |\n| grant_types | No | Defaults to `[\"authorization_code\"]`. Include `\"refresh_token\"` to use refresh. |\n| response_types | No | Defaults to `[\"code\"]`. |\n| client_name | No | Human-readable name shown on the consent screen. |\n| client_uri | No | Public URL for the application. |\n| logo_uri | No | Public URL for the application logo. |\n| scope | No | Space-separated scopes the client will request. |\n\n### Using the metadata document\n\nPass the document URL as the `client_id` on the\n[authorization request](#step-1-authorization-request). Todoist fetches\nand caches the document, validates it, and proceeds with the\nauthorization code flow as usual. Because metadata clients use\n`token_endpoint_auth_method: none`, the `client_secret` parameter is\n**not sent** on the `/oauth/access_token` exchange. Clients must\nadditionally send PKCE parameters (`code_challenge` on the authorization\nrequest, `code_verifier` on the token exchange).\n\n### Refreshing the document\n\nMetadata documents are cached server-side. Changes to the document are\npicked up on the next cache miss, which happens automatically \u2014 there is\nno explicit refresh endpoint. To force a refresh you can revoke the\nclient via the [App Management Console](https://app.todoist.com/app/settings/integrations/app-management);\nthe next authorization attempt will fetch fresh metadata.\n\n### Potential errors\n\n| Error | Description |\n| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Invalid Client | The document URL failed SSRF validation (HTTP, private IP, missing path), the document is malformed, exceeds the size limit, or `client_id` inside the document does not match the URL: `{\"error\": \"invalid_client\"}`. |\n| Rate Limit Exceeded | Too many metadata document fetches in a short period; retry later. |\n\n## Refreshing access tokens\n\n> Exchanging a refresh token for a new access token:\n\n```shell\n$ curl \"https://api.todoist.com/oauth/access_token\" \\\n -d \"client_id=0123456789abcdef\" \\\n -d \"client_secret=secret\" \\\n -d \"grant_type=refresh_token\" \\\n -d \"refresh_token=abcdef0123456789abcdef0123456789abcdef01\"\n```\n\n> On success, Todoist returns HTTP 200 with a new access token and a rotated\n> refresh token:\n\n```json\n{\n \"access_token\": \"fedcba9876543210fedcba9876543210fedcba98\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"refresh_token\": \"9876543210abcdef9876543210abcdef98765432\",\n \"scope\": \"data:read_write\"\n}\n```\n\n### Which applications issue refresh tokens?\n\nRefresh tokens are **enabled by default for newly-created applications**. Access\ntokens issued to these applications expire one hour after they are issued, and\nclients must exchange the refresh token for a new access token to continue\nmaking requests.\n\nLegacy applications created before refresh tokens were introduced continue to\nreceive long-lived access tokens that do not expire. These applications can\nopt in to refresh tokens via the\n[App Management Console](https://app.todoist.com/app/settings/integrations/app-management).\nOnce enabled, the setting cannot be disabled \u2014 all new tokens issued by the\napplication will follow the refresh flow. Tokens issued before opting in remain\nlong-lived and are not retroactively converted.\n\n### How to refresh\n\nTo exchange a refresh token for a new access token, send a `POST` request to\n`https://api.todoist.com/oauth/access_token` with the following parameters:\n\n| Name | Description |\n| ------------- | ------------------------------------------------------------------------------------------------------- |\n| client_id | The Client ID of the Todoist application. |\n| grant_type | Must be the literal string `refresh_token`. |\n| refresh_token | The refresh token received in the previous token exchange or refresh. |\n| client_secret | The Client Secret of the Todoist application. Required for confidential clients \u2014 see _Client authentication_ below. |\n\n#### Client authentication\n\nTodoist's token endpoint supports three authentication methods, matching the\n`token_endpoint_auth_method` chosen when the application was registered:\n\n- `client_secret_post` (default for confidential clients) \u2014 `client_id` and\n `client_secret` sent in the request body.\n- `client_secret_basic` \u2014 credentials sent via HTTP Basic auth:\n `Authorization: Basic base64(client_id:client_secret)`.\n- `none` \u2014 public clients (including clients registered via the OAuth 2.0\n Client ID Metadata Document flow). `client_secret` is not sent or validated;\n these clients are expected to protect themselves with PKCE during the\n authorization code exchange.\n\n#### Optional parameters\n\n| Name | Description |\n| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| scope | A comma separated subset of the originally granted scopes. Clients may request a narrower set of scopes; requesting scopes beyond the original grant returns an error. |\n\n### Token rotation and security\n\nRefresh tokens are **rotated on every successful refresh**. The refresh token\nreturned in the response replaces the one you just used, which is marked as\nconsumed. Always store the latest refresh token from each response.\n\n#### Network retries inside the grace window\n\nIf the same (already-consumed) refresh token is presented again within 60\nseconds of being consumed, Todoist treats the second call as a legitimate\nnetwork retry rather than token reuse. The response returns HTTP `200` with\nthe **same replacement access token** that was issued by the original\nsuccessful refresh, but **omits the `refresh_token` field** (Todoist cannot\nreissue it from the consumed hash). Clients must therefore retain the\nrefresh token from the original `200` response; they cannot recover it from\na grace-window retry.\n\n#### Replay detection outside the grace window\n\nIf a consumed refresh token is presented outside the 60-second grace window,\nTodoist treats it as a potential replay attack. All access and refresh tokens\nissued to the user for the application are revoked, and the user must\nre-authorize the application.\n\n### Detecting an expired access token\n\nWhen an access token is invalid or has expired, API requests using that token\nreturn HTTP `401 Unauthorized` with Todoist's standard `UNAUTHORIZED`\n(`error_code` `477`) JSON body and an [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)\n`WWW-Authenticate` challenge. The response may also include retry backoff\nmetadata:\n\n```http\nHTTP/1.1 401 Unauthorized\nContent-Type: application/json\nRetry-After: 3\nWWW-Authenticate: Bearer error=\"invalid_token\", error_description=\"Unauthorized\", resource_metadata=\"https://api.todoist.com/.well-known/oauth-protected-resource\"\n\n{\n \"error_tag\": \"UNAUTHORIZED\",\n \"error_code\": 477,\n \"error\": \"Unauthorized\",\n \"http_code\": 401,\n \"error_extra\": {\n \"retry_after\": 3,\n \"event_id\": \"\"\n }\n}\n```\n\nClients should treat this response as a signal to refresh the access token and\nretry the original request with the new token. When present, `retry_after` and\nthe `Retry-After` header are backoff metadata; do not wait and retry the same\ninvalid or expired token. For legacy applications without refresh tokens\nenabled, the user must re-authorize the application instead. The\n`resource_metadata` URL points at an\n[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) Protected Resource\nMetadata document that identifies the authorization server, which is useful for\nclients discovering the refresh endpoint automatically.\n\n### Potential errors\n\n| Error | Description |\n| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Invalid Grant | The refresh token is unknown, expired, revoked, or has already been consumed outside the grace window: `{\"error\": \"invalid_grant\"}`. The user must re-authorize the application. Also returned for legacy applications that have not opted in to refresh tokens, because they have no refresh token to present. |\n| Invalid Client | The `client_id` or `client_secret` is missing or incorrect: `{\"error\": \"invalid_client\"}`. |\n| Invalid Scope | A scope requested in the refresh was not part of the original grant: `{\"error\": \"invalid_scope\"}`. |\n| Unsupported Grant Type | The `grant_type` parameter is not one of `authorization_code` or `refresh_token`: `{\"error\": \"unsupported_grant_type\"}`. |\n\n## Cross Origin Resource Sharing\n\n> CORS headers example:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -H \"Origin: http://example.com\"\n\nHTTP/1.1 200 OK\nAccess-Control-Allow-Credentials: false\nAccess-Control-Allow-Origin: *\n```\n\nAll API endpoints not related to the initial OAuth2 flow support Cross Origin Resource\nSharing (CORS) for requests from any origin. The header\n`Access-Control-Allow-Origin: *` is set for successfully authenticated requests.\n" }, { "name": "Sync", "description": "The Todoist Sync endpoint is specially designed for efficient data sync between\nclients (e.g. our mobile apps) and Todoist.\n\nSync requests should be made in HTTP POST (`application/x-www-form-urlencoded`).\nSync responses, including errors, will be returned in JSON.\n\nThe Sync endpoint supports the following features:\n\n- [Batching](#tag/Sync/Overview/Batching-commands): reading and writing of\n multiple resources can be done in a single HTTP request. Batch requests help\n clients reduce the number of network calls needed to sync resources.\n- [Incremental sync](#tag/Sync/Overview/Incremental-sync): You only retrieve\n data that is updated since the last time you performed a sync request.\n\n_Refer to [Request Limits](#tag/Request-limits) to learn more about the number of requests/commands\nyou have for the Sync API_\n\n# Overview\n\n## Read resources\n\n> Example read resources request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d sync_token='*' \\\n -d resource_types='[\"all\"]'\n```\n\n> Example response:\n\n```shell\n{\n \"completed_info\": [ ... ],\n \"collaborators\": [ ... ],\n \"collaborator_states\": [ ... ],\n \"day_orders\": { ... },\n \"filters\": [ ... ],\n \"full_sync\": true,\n \"items\": [ ... ],\n \"labels\": [ ... ],\n \"live_notifications\": [ ... ],\n \"live_notifications_last_read_id\": \"0\",\n \"locations\": [ ... ],\n \"notes\": [ ... ],\n \"project_notes\": [ ... ],\n \"projects\": [ ... ],\n \"project_view_options_defaults\": [ ... ],\n \"reminders\": [ ... ],\n \"role_actions\": { ... },\n \"sections\": [ ... ],\n \"stats\": { ... },\n \"settings_notifications\": { ... },\n \"sync_token\": \"TnYUZEpuzf2FMA9qzyY3j4xky6dXiYejmSO85S5paZ_a9y1FI85mBbIWZGpW\",\n \"temp_id_mapping\": { ... },\n \"user\": { ... },\n \"user_plan_limits\": { ... },\n \"user_settings\": { ... },\n \"view_options\": [ ... ],\n \"workspace_users\": { ... }\n}\n```\n\nTo retrieve your user resources, make a Sync API request with the following\nparameters:\n\n#### Parameters\n\n| Parameter | Required | Description |\n|----------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| sync_token _String_ | Yes | A special string, used to allow the client to perform incremental sync. Pass `*` to retrieve all active resource data. More details about this below. |\n| resource_types _JSON array of strings_ | Yes | Used to specify what resources to fetch from the server. It should be a JSON-encoded array of strings. Here is a list of available resource types: `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`. You may use `all` to include all the resource types. Resources can also be excluded by prefixing a `-` prior to the name, for example, `-projects` |\n\nIn order to fetch both types of reminders you must include both resource types in your request, for example: `resource_types=[\"reminders\", \"reminders_location\"]` .\n\nThe `workspace_users` resource type will not be returned in full sync, but should be requested in incremental sync to keep data up-to-date once it's loaded from the REST endpoint.\n\n\n#### Response\n\nWhen the request succeeds, an HTTP 200 response will be returned with a JSON\nobject containing the requested resources and a new `sync_token`.\n\n| Field | Description |\n|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| sync_token | A new synchronization token. Used by the client in the next sync request to perform an incremental sync. |\n| full_sync | Whether the response contains all data (a full synchronization) or just the incremental updates since the last sync. |\n| full_sync_date_utc | For full syncs, the time when the data was generated. For big accounts, the data may be returned with some delay, requiring an [incremental sync](#tag/Sync/Overview/Incremental-sync) to get up-to-date data. |\n| user | A user object. |\n| projects | An array of [project](#tag/Sync/Projects) objects. |\n| items | An array of [item](#tag/Sync/Items) objects. |\n| notes | An array of [task comments](#tag/Sync/Comments/Task-Comments) objects. |\n| project_notes | An array of [project comments](#tag/Sync/Comments/Project-Comments) objects. |\n| sections | An array of [section](#tag/Sync/Sections) objects. |\n| labels | An array of [personal label](#tag/Sync/Labels) objects. |\n| filters | An array of [filter](#tag/Sync/Filters) objects. |\n| workspace_filters | An array of [workspace filter](#tag/Sync/Workspace-Filters) objects. |\n| day_orders | A JSON object specifying the order of items in daily agenda. |\n| reminders | An array of [reminder](#tag/Sync/Reminders) objects. |\n| collaborators | A JSON object containing all [collaborators](#tag/Sync/Sharing/Collaborators) for all shared projects. The `projects` field contains the list of all shared projects, where the user acts as one of collaborators. |\n| collaborators_states | An array specifying the state of each collaborator in each project. The state can be invited, active, inactive, deleted. |\n| completed_info | An array of `completed` info objects indicating the number of completed items within an active project, section, or parent item. Projects will also include the number of archived sections. |\n| live_notifications | An array of `live_notification` objects. |\n| live_notifications_last_read | What is the last live notification the user has seen? This is used to implement unread notifications. |\n| user_settings | A JSON object containing [user settings](#tag/Sync/User/User-settings). |\n| user_plan_limits | A JSON object containing [user plan limits](#tag/Sync/User/User-plan-limits). |\n| stats | A JSON object containing [user productivity stats](#tag/Sync/User/User-productivity-stats) with completion counts for today and this week. |\n| view_options | An array of [view options](#tag/Sync/View-options) objects. |\n| project_view_options_defaults | An array of [project view options defaults](#tag/Sync/Project-View-Options-Defaults) objects. |\n| role_actions | The actions each role in the system are allowed to perform on a project |\n| workspaces | A JSON object containing [workspace](#tag/Sync/Workspace) objects. |\n| workspace_users | A JSON object containing [workspace_user](#tag/Sync/Workspace-users) objects. Only in incremental sync. |\n\n## Write resources\n\n> Example create project request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"project_add\",\n \"temp_id\": \"381e601f-0ef3-4ed6-bf95-58f896d1a314\",\n \"uuid\": \"ed1ce597-e4c7-4a88-ba48-e048d827c067\",\n \"args\": {\n \"name\": \"Shopping List\",\n \"color\": \"berry_red\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n \"sync_token\": \"cdTUEvJoChiaMysD7vJ14UnhN-FRdP-IS3aisOUpl3aGlIQA9qosBgvMmhbn\",\n \"sync_status\": {\"ed1ce597-e4c7-4a88-ba48-e048d827c067\": \"ok\"},\n \"temp_id_mapping\": {\"381e601f-0ef3-4ed6-bf95-58f896d1a314\": \"6HWcc9PJCvPjCxC9\"}\n}\n```\n\nTo write to your user's Todoist resources, make a Sync API request with the\nfollowing parameters:\n\n#### Parameters\n\n| Parameter | Required | Description |\n|-----------------|----------|-----------------------------------------------------------------------------------------|\n| commands _JSON_ | Yes | A JSON array of Command objects. Each command will be processed in the specified order. |\n\n#### Command object\n\n| Field | Description |\n|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|\n| type _String_ | The type of the command. |\n| args _Object_ | The parameters of the command. |\n| uuid _String_ | Command UUID. More details about this below. |\n| temp_id _String_ | Temporary resource ID, Optional. Only specified for commands that create a new resource (e.g. `item_add` command). More details about this below. |\n\n## Command UUID\n\nClients should generate a unique string ID for each command and specify it\nin the `uuid` field. The Command UUID will be used for two purposes:\n\n1. Command result mapping: Each command's result will be stored in the\n `sync_status` field of the response JSON object. The `sync_status` object has\n its key mapped to a command's `uuid` and its value containing the result of a\n command.\n2. Command idempotency: Todoist will not execute a command that has same UUID as\n a previously executed command. This will allow clients to safely retry\n each command without accidentally performing the action twice.\n\n## Temporary resource ID\n\n> An example that shows how temporary IDs can be used and referenced:\n\n```\n[\n {\n \"type\": \"project_add\",\n \"temp_id\": \"c7beb07f-b226-4eb1-bf63-30d782b07b1a\",\n \"args\": {\n \"name\": \"Shopping List\"\n },\n \"uuid\": \"ac417051-1cdc-4dc3-b4f8-14526d5bfd16\"\n },\n {\n \"type\": \"item_add\",\n \"temp_id\": \"43f7ed23-a038-46b5-b2c9-4abda9097ffa\",\n \"args\": {\n \"content\": \"Buy Milk\",\n \"project_id\": \"c7beb07f-b226-4eb1-bf63-30d782b07b1a\"\n },\n \"uuid\": \"849fff4e-8551-4abb-bd2a-838d092775d7\"\n }\n]\n```\n\n> You can see that the `project_add` command specified a `temp_id` property\n> (`c7beb07f-b226-4eb1-bf63-30d782b07b1a`) as placeholder of the actual\n> `project_id`. The `item_add` command can reference to this temporary project\n> ID. The API will automatically resolve these IDs.\n\nSome commands depend on the result of previous command. For instance, you have a\ncommand sequence: `\"project_add\"` and `\"item_add\"` which first creates a project\nand then add a new task to the newly created project. In order to run the later\n`item_add` command, we need to obtain the project ID returned from the previous\ncommand. Therefore, the normal approach would be to run these two commands in\ntwo separate HTTP requests.\n\nThe temporary resource ID feature allows you to run two or more dependent\ncommands in a single HTTP request. For commands that are related to creation of\nresources (i.e. `item_add`, `project_add`), you can specify an extra `temp_id`\nas a placeholder for the actual ID of the resource. The other commands in the\nsame sequence could directly refer to `temp_id` if needed.\n\n## Response / Error\n\n> An example of a single request sync return value:\n\n```\n{\n \"sync_status\": { \"863aca2c-65b4-480a-90ae-af160129abbd\": \"ok\" }\n}\n```\n\n> An example of a multiple requests sync return value:\n\n```\n{\n \"sync_status\": {\n \"32eaa699-e9d7-47ed-91ea-e58d475791f1\": \"ok\",\n \"bec5b356-3cc1-462a-9887-fe145e3e1ebf\": {\n \"error_code\": 15,\n \"error\": \"Invalid temporary id\"\n }\n }\n}\n```\n\n> An example of an error with additional context in `error_extra`:\n\n```\n{\n \"sync_status\": {\n \"bec5b356-3cc1-462a-9887-fe145e3e1ebf\": {\n \"error_tag\": \"INVALID_ARGUMENT_VALUE\",\n \"error_code\": 20,\n \"error\": \"Invalid argument value\",\n \"http_code\": 400,\n \"error_extra\": {\n \"argument\": \"file_url\",\n \"explanation\": \"file_url contains disallowed URL\"\n }\n }\n }\n}\n```\n\nThe error object may contain the following fields:\n\n| Field | Description |\n|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| error_tag _String_ | A machine-readable error identifier (e.g., `INVALID_ARGUMENT_VALUE`). |\n| error_code _Integer_ | A numeric error code. |\n| error _String_ | A human-readable error message. |\n| http_code _Integer_ | The HTTP status code associated with this error. This code may differ from the REST HTTP status for the same `error_tag`. |\n| error_extra _Object_ | Additional context about the error. Contents vary by error type; common fields are documented below. |\n\nCommon fields in `error_extra`:\n\n| Field | Description |\n|-----------------------------|----------------------------------------------------------------------------------------------------------|\n| argument _String_ | The name of the argument that caused the error. |\n| explanation _String_ | A detailed error description, included when it provides more context than the generic `error` message. |\n| retry_after _Integer_ | Seconds to wait before retrying. May be returned on rate-limited requests and other API errors, not just `429` responses. |\n| workspace_id _Integer_ | The workspace ID related to the error. |\n| max_count _Integer_ | The limit that was exceeded (for limit-related errors). |\n| event_id _String_ | An event ID for error tracking/support purposes. |\n| project_id _String_ | The project ID related to the error. |\n| section_id _String_ | The section ID related to the error. |\n| bad_item _Object_ | Information about the item that caused the error. |\n\nThe result of command executions will be stored in the following response JSON\nobject field:\n\n| Data | Description |\n|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| temp_id_mapping _Object_ | A dictionary object that maps temporary resource IDs to real resource IDs. |\n| sync_status _Object_ | A dictionary object containing result of each command execution. The key will be the command's `uuid` field and the value will be the result status of the command execution. |\n\nThe status result of each command execution is in the `sync_status` dictionary\nobject. The key is a command `uuid` and the value will be the result status of\nthe command execution.\n\nThere are two possible values for each command status:\n\n- An \"ok\" string which signals success of the command\n- An error object containing error information of a command.\n\nFor command errors inside `sync_status`, `http_code` describes the command\nresult in the Sync command queue. The same domain error may use a different HTTP\nstatus in REST endpoints. Clients should treat `400` command errors as a\nterminal signal and should not retry the command (e.g. ITEM_NOT_FOUND is\nnon-retryable during sync). Other standard non-retryable statuses, such as `403`\nor `409`, may also be terminal depending on the error.\n\nPlease see the adjacent code examples for the possible format of the\n`sync_status`.\n\n## Response status codes\n\nThe server uses the HTTP status codes to indicate the success or failure of a\nrequest. As is customary in web servers, a 2xx code indicates - success, a\n4xx code - an error due to incorrect user provided information, and a 5xx code -\nan internal, possibly temporary, error.\n\n| Status code | Description |\n|---------------------------|---------------------------------------------------------------------------|\n| 200 OK | The request was processed successfully. |\n| 400 Bad Request | The request was incorrect. |\n| 401 Unauthorized | Authentication is required, and has failed, or has not yet been provided. |\n| 403 Forbidden | The request was valid, but for something that is forbidden. |\n| 404 Not Found | The requested resource could not be found. |\n| 429 Too Many Requests | The user has sent too many requests in a given amount of time. |\n| 500 Internal Server Error | The request failed due to a server error. |\n| 503 Service Unavailable | The server is currently unable to handle the request. |\n\n## Batching commands\n\n> Example of batching multiple commands:\n\n```shell\ncurl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"project_add\",\n \"temp_id\": \"0a57a3db-2ff1-4d2d-adf6-12490c13c712\",\n \"uuid\": \"2c0f6e03-c372-46ba-8e85-d94af56abcf3\",\n \"args\": { \"name\": \"Shopping List\" }\n },\n {\n \"type\": \"item_add\",\n \"temp_id\": \"ef3d840e-84c9-4433-9a32-86ae9a1e7d42\",\n \"uuid\": \"49ede211-12f3-42e9-8345-4c0d2b29c08d\",\n \"args\": { \"content\": \"Buy Milk\", \"project_id\": \"0a57a3db-2ff1-4d2d-adf6-12490c13c712\" }\n },\n {\n \"type\": \"item_add\",\n \"temp_id\": \"8a23c8cb-1d76-469d-a2c0-80a28b3ea6f6\",\n \"uuid\": \"46619250-ae02-4ab0-bd31-3c9ab0307e53\",\n \"args\": { \"content\": \"Buy Coffee\", \"project_id\": \"0a57a3db-2ff1-4d2d-adf6-12490c13c712\" }\n },\n {\n \"type\": \"item_add\",\n \"temp_id\": \"bf087eaf-aea9-4cb1-ab57-85188a2d428f\",\n \"uuid\": \"d0a1666b-d615-4250-aac5-65c7ea89091a\",\n \"args\": { \"content\": \"Buy Sugar\", \"project_id\": \"0a57a3db-2ff1-4d2d-adf6-12490c13c712\" }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n \"sync_status\": {\n \"2c0f6e03-c372-46ba-8e85-d94af56abcf3\": \"ok\",\n \"49ede211-12f3-42e9-8345-4c0d2b29c08d\": \"ok\",\n \"d0a1666b-d615-4250-aac5-65c7ea89091a\": \"ok\",\n \"46619250-ae02-4ab0-bd31-3c9ab0307e53\": \"ok\"\n },\n \"temp_id_mapping\": {\n \"8a23c8cb-1d76-469d-a2c0-80a28b3ea6f6\": \"6X6HrfVQvQq5WCXH\",\n \"0a57a3db-2ff1-4d2d-adf6-12490c13c712\": \"6X6HrhXfQ9857XVG\",\n \"bf087eaf-aea9-4cb1-ab57-85188a2d428f\": \"6X6HrjHFgc3jQM8H\",\n \"ef3d840e-84c9-4433-9a32-86ae9a1e7d42\": \"6X6HrmjgW88crvMC\"\n },\n \"full_sync\": true,\n \"sync_token\": \"GSg4kDBAKWU7TZA_a-gcuSpxmO1lXT5bhLqUGd1F-AH69_qKEdkN_fJoBq3c\"\n}\n```\n\nWhen working with the Sync API, changes can be **batched** into one commit.\nIn our example, we're batching the creation of a 'Shopping List' project with three\ndifferent items.\n\nAs we've committed the changes all at once, we\u2019re significantly reducing the amount of\nnetwork calls that have to be made, as well as ensuring we\u2019re not running into any rate\nlimiting issues.\n\n## Incremental sync\n\nThe Sync API allows clients to retrieve only updated resources, and this is done\nby using the `sync_token` in your Sync API request.\n\nOn your initial sync request, specify `sync_token=*` in your request, and all\nthe user's active resource data will be returned. The server will also\nreturn a new `sync_token` in the Sync API response.\n\nIn your subsequent Sync request, use the `sync_token` that you received from\nyour previous sync response, and the Todoist API server will return only the\nupdated resource data.\n\n### Full sync data delay\n\nFor big accounts, the data in the initial sync may be returned with some delay,\nand newer objects and updates may seem to be missing. The `full_sync_date_utc`\nattribute should be the same or very close to the current UTC date. If you notice a\nbigger time difference, it's recommended to do an incremental sync using the\n`sync_token` included in that initial sync response to get the latest updates.\n\n# Workspace\n\n> An example workspace object:\n\n```\n{\n \"created_at\": \"2024-10-19T10:00:00.123456Z\",\n \"creator_id\": \"123\",\n \"current_active_projects\": 5,\n \"current_member_count\": 2,\n \"current_template_count\": 0,\n \"description\": \"Workspace description\",\n \"desktop_workspace_modal\": null,\n \"domain_discovery\": false,\n \"domain_name\": null,\n \"id\": \"1234\",\n \"invite_code\": \"ptoh4SICUu4\",\n \"is_collapsed\": false,\n \"is_deleted\": false,\n \"is_guest_allowed\": true,\n \"is_link_sharing_enabled\": true,\n \"is_trial_pending\": false,\n \"limits\": {\n \"current\": {\n \"admin_tools\": false,\n \"advanced_permissions\": false,\n \"automatic_backups\": false,\n \"calendar_layout\": false,\n \"durations\": false,\n \"max_collaborators\": 250,\n \"max_folders_per_workspace\": 1000,\n \"max_guests_per_workspace\": 1000,\n \"max_projects\": 5,\n \"max_workspace_templates\": 100,\n \"max_workspace_users\": 1000,\n \"max_workspaces\": 50,\n \"plan_name\": \"teams_workspaces_starter\",\n \"reminders\": false,\n \"reminders_at_due\": true,\n \"security_controls\": false,\n \"upload_limit_mb\": 5\n },\n \"next\": {\n \"admin_tools\": true,\n \"advanced_permissions\": true,\n \"automatic_backups\": true,\n \"max_collaborators\": 250,\n \"max_guests_per_workspace\": 1000,\n \"max_projects\": 1000,\n \"max_workspace_users\": 1000,\n \"plan_name\": \"teams_workspaces_business\",\n \"reminders\": true,\n \"security_controls\": true,\n \"upload_limit_mb\": 100\n }\n },\n \"logo_big\": \"https://...\",\n \"logo_medium\": \"https://...\",\n \"logo_s640\": \"https://...\",\n \"logo_small\": \"https://...\",\n \"member_count_by_type\": {\n \"admin_count\": 2,\n \"guest_count\": 0,\n \"member_count\": 0\n },\n \"name\": \"Workspace name\",\n \"pending_invitations\": [\n \"pending@doist.com\"\n ],\n \"pending_invites_by_type\": {\n \"admin_count\": 1,\n \"guest_count\": 0,\n \"member_count\": 0\n },\n \"plan\": \"STARTER\",\n \"properties\": {},\n \"restrict_email_domains\": false,\n \"role\": \"MEMBER\"\n}\n```\n\n#### Properties\n\n| Property | Description |\n|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | The ID of the workspace. |\n| name _String_ | The name of the workspace (up to 255 characters). |\n| description _String_ | The description of the workspace. |\n| plan _String_ | The subscription plan this workspace is currently on, either `STARTER` or `BUSINESS`. |\n| is_link_sharing_enabled _Boolean_ | True if users are allowed to join the workspace using an invitation link. Default value is True. _For guests, this field will be set to `null` as guests are not allowed to have access to this field._ |\n| is_guest_allowed _Boolean_ | True if users from outside the workspace are allowed to join or be invited to workspace projects. Default value is True. |\n| invite_code _String_ | The invitation code used to generate an invitation link. If `is_link_sharing_enabled` is True, anyone can join the workspace using this code. _For guests, this field will be set to `null` as guests are not allowed to have access to this field._ |\n| role _String_ | The role of the requesting user in this workspace. Possible values are: `ADMIN`, `MEMBER` or `GUEST`. A guest is someone who is a collaborator of a workspace project, without being an actual member of the workspace. This field can be `null` if the requesting user is not part of the workspace. For example, when receiving the workspace deletion related sync update when a user leaves or is removed from a workspace. |\n| logo_big _String_ | The URL for the big workspace logo image. |\n| logo_medium _String_ | The URL for the medium workspace logo image. |\n| logo_small _String_ | The URL for the small workspace logo image. |\n| logo_s640 _String_ | The URL for the square 640px workspace logo image. |\n| limits _Object_ | A list of restrictions for the workspace based on it's current plan, denoting what features are enabled and limits are imposed. |\n| creator_id _String_ | The ID of the user who created the workspace. |\n| created_at _String_ | The date when the workspace was created. |\n| is_deleted _Boolean_ | True if it is a deleted workspace. |\n| is_collapsed _Boolean_ | True if the workspace is collapsed. This is a user-specific attribute and will reflect the requesting user\u2019s `is_collapsed` state. |\n| domain_name _String_ | The domain name of the workspace. |\n| domain_discovery _Boolean_ | True if users with e-mail addresses in the workspace domain can join the workspace without an invitation. |\n| restrict_email_domains _Boolean_ | True if only users with e-mail addresses in the workspace domain can join the workspace. |\n| properties _Object_ | Configuration properties for the workspace. See [Workspace Properties](#workspace-properties) below for detailed structure. |\n| default_collaborators _Object_ | Default collaborators that are automatically added to new projects in this workspace. Contains `user_ids` (array of user IDs) and `predefined_group_ids` (array of predefined group names). |\n| desktop_workspace_modal _String_ | Enum value indicating when desktop should show workspace modal. Currently only supports `TRIAL_OFFER` for trial offers. `null` when no modal should be shown. This field is automatically set by the backend when mobile devices are registered and trial eligibility criteria are met. |\n\n### Workspace Properties\n\nThe `properties` object contains configuration settings for the workspace:\n\n| Property | Type | Description |\n|----------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| industry | _String_ | The industry of the workspace. Possible values: `agriculture`, `arts_entertainment`, `automotive`, `banking_financial_services`, `construction`, `consulting`, `consumer_goods`, `education`, `energy_utilities`, `food_beverages`, `government_public_sector`, `healthcare_life_sciences`, `information_technology`, `insurance`, `legal_services`, `manufacturing`, `media_communications`, `non_profit`, `pharmaceuticals`, `real_estate`, `retail_wholesale`, `telecommunications`, `transportation_logistics`, `travel_hospitality`, `other`. |\n| department | _String_ | The department of the workspace. Possible values: `administration`, `customer_service`, `finance_accounting`, `human_resources`, `information_technology`, `legal`, `marketing`, `operations`, `product_development`, `research_development`, `sales`, `supply_chain_management`, `engineering`, `quality_assurance`, `executive_management`, `other`. |\n| organization_size | _String_ | The size of the organization. Possible values: `size_1`, `size_2_to_10`, `size_11_to_50`, `size_51_to_100`, `size_101_to_250`, `size_51_to_250`, `more_than_250`. |\n| intended_team_size | _String_ | The number of collaborators the workspace creator intends to work with, selected during onboarding. Possible values: `size_1`, `size_2_to_10`, `size_11_to_50`, `more_than_50`, `size_2_to_7`, `size_8_to_15`, `size_16_to_24`, `more_than_25`. |\n| type_of_work | _String_ | The type of work the team primarily does, selected during onboarding. Possible values: `projects`, `processes`, `both`. |\n| creator_role | _String_ | The role of the workspace creator. Possible values: `owner_founder`, `leader`, `individual_contributor`. |\n| region | _String_ | 2 digit continent code. Possible values: `AF`, `AS`, `EU`, `NA`, `SA`, `OC`, `AN`. |\n| country | _String_ | 2 digit ISO 3166-1 alpha-2 country code. |\n| default_access_level | _String_ | Default access level for new projects in the workspace. Possible values: `restricted`, `team` (default). |\n| beta_enabled | _Boolean_ | Indicates whether beta features are enabled for this workspace. Default value is `false`. |\n| acquisition_source | _String_ | The marketing channel or source that led to workspace creation. Possible values: `high_paid_channel` |\n| hdyhau | _String_ | How did you hear about us - marketing attribution field. Possible values: `friend`, `social_media`, `ai_chatbot`, `search_engine`, `app_store`, `other` |\n\n## Add a workspace\n\n> Example add workspace request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"workspace_add\",\n \"temp_id\": \"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"name\": \"Fellowship Workspace\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n \"temp_id_mapping\": {\"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\": \"6X6WMG4rmqx6FXQ9\"},\n ...\n}\n```\n\nAdd a new workspace.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| name _String_ | Yes | The name of the workspace. |\n| description _String_ | No | The description of the workspace (up to 1024 characters). |\n| is_link_sharing_enabled _Boolean_ | No | Indicates if users are allowed to join the workspace using an invitation link. Default value is True. |\n| 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. |\n| domain_name _String_ | No | The domain name of the workspace. |\n| domain_discovery _Boolean_ | No | True if users with e-mail addresses in the workspace domain can join the workspace without an invitation. |\n| restrict_email_domains _Boolean_ | No | True if only users with e-mail addresses in the workspace domain can join the workspace. |\n| properties _Object_ | No | Configuration properties for the workspace. See [Workspace Properties](#workspace-properties) for detailed structure. |\n| 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. |\n\n## Update a workspace\n\n> Example update workspace request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"workspace_update\",\n \"temp_id\": \"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"id\": \"12345\",\n \"description\": \"Where magic happens\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n \"temp_id_mapping\": {\"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\": \"6X6WMMqgq2PWxjCX\"},\n ...\n}\n```\n\nUpdate an existing workspace.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | Yes | Real or temp ID of the workspace |\n| name _String_ | No | The name of the workspace. |\n| description _String_ | No | The description of the workspace (up to 1024 characters). |\n| is_collapsed _Boolean_ | No | The collapsed state of the workspace for the current user |\n| is_link_sharing_enabled _Boolean_ | No | Indicates if users are allowed to join the workspace using an invitation link. |\n| 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. |\n| 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. |\n| domain_name _String_ | No | The domain name of the workspace. |\n| domain_discovery _Boolean_ | No | True if users with e-mail addresses in the workspace domain can join the workspace without an invitation. |\n| restrict_email_domains _Boolean_ | No | True if only users with e-mail addresses in the workspace domain can join the workspace. |\n| properties _Object_ | No | Configuration properties for the workspace. See [Workspace Properties](#workspace-properties) for detailed structure. |\n| 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. |\n\n## Leave a workspace\n\n> Example leave workspace request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"workspace_leave\",\n \"temp_id\": \"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"id\": \"6X6WMMqgq2PWxjCX\",\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n ...\n}\n```\n\nRemove self from a workspace. The user is also removed from any workspace project previously joined.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|----------------------------------|\n| id _String_ | Yes | Real or temp ID of the workspace |\n\n_All workspace_users can leave a workspace by themselves._\n\n## Delete a workspace\n\n> Example delete workspace request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"workspace_delete\",\n \"temp_id\": \"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"id\": \"6X6WMRPC43g2gHVx\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n ...\n}\n```\n\nDelete an existing workspace.\n\n_This command is only usable by workspace admins. Other users will get a \u201cforbidden\u201d error._\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|-------------------------|\n| id _String_ | Yes | The ID of the workspace |\n\n# Workspace users\n\n**`workspace_users` are not returned in full sync responses, only in incremental sync**. To keep a list of workspace users up-to-date, clients should first [list all workspace users](#tag/Workspace/operation/get_workspaces_users_api_v1_workspaces_users_get), then use incremental sync to update that initial list as needed.\n\n`workspace_users` are not the same as collaborators. Two users can be members of a common workspace without having a common shared project, so they will both \u201csee\u201d each other in `workspace_users` but not in collaborators.\n\nGuests will not receive `workspace_users` sync events or resources.\n\n> An example workspace_users object:\n\n```\n{\n \"user_id\": \"1855581\",\n \"workspace_id\": \"424876\",\n \"user_email\": \"you@example.com\",\n \"full_name\": \"Example User\",\n \"timezone\": \"GMT +3:00\",\n \"avatar_big\": \"https://*.cloudfront.net/*_big.jpg\",\n \"avatar_medium\": \"https://*.cloudfront.net/*_medium.jpg\",\n \"avatar_s640\": \"https://*.cloudfront.net/*_s640.jpg\",\n \"avatar_small\": \"https://*.cloudfront.net/*_small.jpg\",\n \"image_id\": \"d160009dfd52b991030d55227003450f\",\n \"role\": \"MEMBER\"\n \"is_deleted\": false,\n}\n```\n\n#### Properties\n\n| Property | Description |\n|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| user_id _String_ | The user ID. |\n| workspace_id _String_ | The workspace ID for this user. |\n| user_email _String_ | The user email. |\n| full_name _String_ | The full name of the user. |\n| timezone _String_ | The timezone of the user. |\n| image_id _String_ | The ID of the user's avatar. |\n| role _String_ | The role of the user in this workspace. Possible values are: ADMIN, MEMBER, GUEST. A guest is someone who is a collaborator of a workspace project, without being an actual member of the workspace. |\n| avatar_big _String_ | The link to a 195x195 pixels image of the user's avatar. |\n| avatar_medium _String_ | The link to a 60x60 pixels image of the user's avatar. |\n| avatar_s640 _String_ | The link to a 640x640 pixels image of the user's avatar. |\n| avatar_small _String_ | The link to a 35x35 pixels image of the user's avatar. |\n| is_deleted _Boolean_ | Whether the workspace user is marked as deleted. |\n\nAvatar URLs are only available if the user has an avatar, in other words, when the `image_id` is not `null`.\n\n## Change user role\n\n> Example role change for a workspace user request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"workspace_update_user\",\n \"temp_id\": \"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"workspace_id\": \"12345,\n \"user_email\": \"user@acme.com\",\n \"role\": \"ADMIN\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n \"temp_id_mapping\": {\"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\": \"12345\"},\n ...\n}\n```\n\nChange the role of a workspace user.\n\n_Admins or members can not be downgraded to guests._\n\n_This command is only usable by workspace admins. Other users will get a \u201cforbidden\u201d error._\n\n#### Command arguments\n\n| Argument | Required | Description |\n|---------------------|----------|--------------------------------------------------------------------------------------------|\n| id _String_ | Yes | Real or temp ID of the workspace |\n| user_email _String_ | Yes | The new member's email |\n| role _String_ | Yes | The role to be assigned to the new member. Valid values are `GUEST`, `MEMBER` and `ADMIN`. |\n\n## Update user sidebar preference\n\n> Example sidebar preference update for a workspace user request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"workspace_update_user_sidebar_preference\",\n \"temp_id\": \"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"workspace_id\": \"12345\",\n \"sidebar_preference\": \"A_TO_Z\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n \"temp_id_mapping\": {\"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\": \"12345\"},\n \"workspaces\": [\n {\n \"id\": \"12345\",\n \"sidebar_preference\": \"A_TO_Z\",\n ...\n }\n ],\n ...\n}\n```\n\nUpdate the sidebar preference for the requesting user in a workspace. This defines the order projects and folders are sorted in the Workspace Overview and Sidebar.\n\n_Any workspace user can update their own sidebar preference._\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-----------------------------|----------|----------------------------------------------------------------------------|\n| workspace_id _String_ | Yes | Real or temp ID of the workspace |\n| sidebar_preference _String_ | Yes | The sidebar preference. Valid values are `MANUAL`, `A_TO_Z`, and `Z_TO_A`. |\n\n## Delete workspace user\n\n> Example delete workspace user request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"workspace_delete_user\",\n \"temp_id\": \"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"workspace_id\": \"12345\",\n \"user_email\": \"user@acme.com\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n ...\n}\n```\n\nRemove a user from a workspace. That user is also removed from any workspace project they joined.\n\n_This command is only usable by workspace admins. Other users will get a \u201cforbidden\u201d error._\n\n_Admins can use this command to remove themselves from a workspace, unless they are the last admin in the workspace. In that case, a \u201cforbidden\u201d error will be returned._\n\n#### Command arguments\n\n| Argument | Required | Description |\n|---------------------|----------|---------------------------------------|\n| id _String_ | Yes | Real or temp ID of the workspace |\n| user_email _String_ | Yes | The email of the member to be deleted |\n\n## Invite Users to a Workspace\n\n> Example request to invite users to a workspace through the Sync API:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"workspace_invite\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"id\": \"6Jf8VQXxpwv56VQ7\",\n \"email_list\": [\"foo@example.com\", \"bar@example.com\"],\n \"role\": \"MEMBER\"\n }\n }]\n '\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n ...\n}\n```\n\nThis will create workspace invitations for a list of email addresses. Usable by all workspace members and admins.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-----------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | Yes | ID of the workspace. |\n| email_list _List of String_ | Yes | A list of emails to be invited to the workspace. |\n| 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. |\n\n## Resend a Workspace Invitation\n\n> Example request to resend a pending workspace invitation:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"workspace_resend_invite\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"id\": \"6Jf8VQXxpwv56VQ7\",\n \"email\": \"bar@example.com\"\n }\n }]\n '\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n ...\n}\n```\n\nRe-send the workspace invitation email for an existing pending invitation. The email, invitation, and accept link are identical to those sent when the invitation was originally created \u2014 no new invitation record is created and no additional analytics events are triggered beyond a single resend marker.\n\n_Only workspace admins may use this command. Other users will get a \u201cforbidden\u201d error._\n\n_Guest invitations cannot currently be resent via this command and will return a \u201cbad request\u201d error._\n\n#### Command arguments\n\n| Argument | Required | Description |\n|----------------|----------|--------------------------------------------------------------------|\n| id _String_ | Yes | ID of the workspace the pending invitation belongs to. |\n| email _String_ | Yes | Email address of the pending invitee whose invite should be resent. |\n\n# View Options\n\n> An example view option object:\n\n```\n{\n \"view_type\": \"project\",\n \"object_id\": \"6Jf8VQXxpwv56VQ7\",\n \"filtered_by\": \"!assigned\",\n \"grouped_by\": \"priority\",\n \"sorted_by\": \"added_date\",\n \"sort_order\": \"asc\",\n \"show_completed_tasks\": false,\n \"view_mode\": \"calendar\",\n \"calendar_settings\": { \"layout\": \"WEEK\", \"visible_day_count\": 3, \"color\": \"PROJECT\" },\n \"is_deleted\": false,\n \"deadline\": \"no deadline\"\n}\n```\n\n#### Properties\n\n| Property | Description |\n|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| view_type _Enum_ | The type of a view customization. `today` for the today view, `upcoming` for the upcoming view, `project` for a project, `label` for a label, `filter` for a personal filter or `workspace_filter` for a team filter. |\n| object_id _String_ | The ID of the object referred to by `view_type`, when `view_type` is `project`, `label`, `filter` or `workspace_filter`. |\n| filtered_by _String_ | A search query for this view customization. [Examples of searches](https://www.todoist.com/help/articles/introduction-to-filters-V98wIH) can be found in the Todoist help page. |\n| grouped_by _Enum_ | Grouping criteria for this view customization. One of `assignee`, `added_date`, `due_date`, `deadline`, `label`, `priority`, `project`, or `workspace`. |\n| sorted_by _Enum_ | Sorting criteria for this view customization. One of `alphabetically`, `assignee`, `added_date`, `due_date`, `deadline`, `label`, `priority`, `project`, `workspace`, or `manual`. |\n| sort_order _Enum_ | Sorting order for this view customization. `asc` for ascending, `desc` for descending. |\n| show_completed_tasks _Boolean_ | Whether completed tasks should be shown automatically in this view customization. |\n| view_mode _Enum_ | The mode in which to render tasks in this view customization. One of `list`, `board`, or `calendar`. **Note: This setting is ignored in projects, where `project.view_style` is used instead.** |\n| deadline _String_ | A search query for this view customization. [Examples of deadline searches](https://www.todoist.com/help/articles/introduction-to-filters-V98wIH) can be found in the Todoist help page. |\n| calendar_settings _JSON_ | 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`. |\n| is_deleted _Boolean_ | Whether the view option is marked as deleted. |\n\n**Note:** `view_options.view_mode` is secondary to [`project.view_style`](#tag/Sync/View-Options) for projects in Todoist clients. The former is set per user, while the latter is set per project.\n\n## Set a view option\n\n| Argument | Required | Description |\n|--------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| view_type _Enum_ | Yes | Type of the view customization to be set. `today` for the today view, `upcoming` for the upcoming view, `project` for a project, `label` for a label, `filter` for a personal filter or `workspace_filter` for a team filter. |\n| object_id _String_ | Yes | ID of the object referred to by `view_type`, required when `view_type` is `project`, `label`, `filter` or `workspace_filter`. |\n| filtered_by _String_ | No | Search query. [Examples of searches](https://www.todoist.com/help/articles/introduction-to-filters-V98wIH) can be found in the Todoist help page. |\n| grouped_by _Enum_ | No | Grouping criteria. One of `assignee`, `added_date`, `due_date`, `deadline`, `label`, `priority`, `project`, or `workspace`. |\n| sorted_by _Enum_ | No | Sorting criteria. One of `alphabetically`, `assignee`, `added_date`, `due_date`, `deadline`, `label`, `priority`, `project`, `workspace`, or `manual`. |\n| sort_order _Enum_ | No | Sorting order. `asc` for ascending, `desc` for descending. |\n| show_completed_tasks _Boolean_ | No | Whether completed tasks should be shown automatically in this view customization. |\n| view_mode _Enum_ | No | The mode in which to render tasks. One of `list`, `board`, or `calendar`. |\n| deadline _String_ | No | A search query for this view customization. [Examples of deadline searches](https://www.todoist.com/help/articles/introduction-to-filters-V98wIH) can be found in the Todoist help page. |\n| 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`. |\n\n> Example set view option request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"view_options_set\",\n \"uuid\": \"997d4b43-55f1-48a9-9e66-de5785dfd696\",\n \"args\": {\n \"view_type\": \"project\",\n \"object_id\": \"6Jf8VQXxpwv56VQ7\",\n \"view_mode\": \"board\",\n \"grouped_by\": \"assignee\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"997d4b43-55f1-48a9-9e66-de5785dfd696\": \"ok\"},\n ...\n}\n```\n\n## Delete view option\n\n| Argument | Required | Description |\n|--------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| view_type _Enum_ | Yes | Type of the view customization to delete. `today` for the today view, `upcoming` for the upcoming view, `project` for a project, `label` for a label, or `filter` for a filter. |\n| object_id _String_ | Yes | ID of the object referred to by `view_type`, required when `view_type` is `project`, `label`, `filter` or `workspace_filter`. |\n\n> Example delete view option request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"view_options_delete\",\n \"uuid\": \"f8539c77-7fd7-4846-afad-3b201f0be8a6\",\n \"args\": {\n \"view_type\": \"today\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"f8539c77-7fd7-4846-afad-3b201f0be8a6\": \"ok\"},\n ...\n}\n```\n\n# Project View Options Defaults\n\nProject View Options Defaults (PVODs) define the default view preferences for all users of a project. These settings serve as the baseline view configuration that applies to all project members unless they have their own personal view options set.\n\n> An example Project View Options Default object:\n\n```json\n{\n \"project_id\": \"2203306141\",\n \"view_mode\": \"list\",\n \"grouped_by\": null,\n \"sorted_by\": \"due_date\",\n \"sort_order\": \"asc\",\n \"show_completed_tasks\": false,\n \"filtered_by\": null,\n \"calendar_settings\": null,\n \"creator_uid\": 1855589,\n \"updater_uid\": 1855589\n}\n```\n\n### Properties\n\n Property | Description\n----------------------|----------------------------------------------------------------------------------------------------------------------------\n project_id | The project ID these defaults apply to (string, required)\n view_mode | The default view mode: `list`, `board`, or `calendar` (string, required)\n grouped_by | How tasks are grouped: `due_date`, `created_at`, `label`, `assignee`, `priority`, or `project` (string or null)\n sorted_by | How tasks are sorted: `due_date`, `created_at`, `task_order`, `assignee`, `alphabetically`, or `priority` (string or null)\n sort_order | Sort direction: `asc` or `desc` (string, required)\n show_completed_tasks | Whether to show completed tasks by default (boolean, required)\n filtered_by | JSON string with filter criteria (string or null)\n calendar_settings | Calendar-specific settings when `view_mode` is `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` (object or null)\n creator_uid | User ID who created these defaults (integer, required)\n updater_uid | User ID who last updated these defaults (integer, required)\n\n### Sync behavior\n\n- PVODs are returned during full sync if the user has access to the project\n- When a project is created, its PVOD is automatically created and included in the same sync response\n- Updates to PVODs trigger sync events for all project members\n- When a PVOD is deleted, a tombstone is returned with `is_deleted: true` and includes: `project_id`, `is_deleted`, `creator_uid`, `updater_uid`, `show_completed_tasks`, and all view option fields (`view_mode`, `grouped_by`, `sorted_by`, `sort_order`, `filtered_by`) set to empty strings. `calendar_settings` is set to `null`\n- PVODs take precedence over legacy `project.view_style` settings\n\n### Commands\n\n#### project_view_options_defaults_set\n\nUpdates the default view options for a project. Only users with admin permissions on the project can update PVODs.\n\n> Command arguments:\n\n Name | Required | Description\n----------------------|----------|----------------------------------------------------------------------\n project_id | Yes | The project ID to update defaults for\n view_mode | No | The default view mode: `list`, `board`, or `calendar`\n grouped_by | No | How to group tasks (see properties above)\n sorted_by | No | How to sort tasks (see properties above)\n sort_order | No | Sort direction: `asc` or `desc`\n show_completed_tasks | No | Whether to show completed tasks\n filtered_by | No | JSON string with filter criteria\n 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`\n\n> Example command:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer $token\" \\\n -d commands='[{\n \"type\": \"project_view_options_defaults_set\",\n \"uuid\": \"bf0855a3-0138-44-b618-1cb8d3d7a869\",\n \"args\": {\n \"project_id\": \"2203306141\",\n \"view_mode\": \"board\",\n \"grouped_by\": \"priority\",\n \"sorted_by\": \"due_date\",\n \"sort_order\": \"asc\",\n \"show_completed_tasks\": false\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"bf0855a3-0138-44-b618-1cb8d3d7a869\": \"ok\"},\n ...\n}\n```\n\n# User\n\n> An example user:\n\n```\n{\n \"activated_user\": false,\n \"auto_reminder\": 0,\n \"avatar_big\": \"https://*.cloudfront.net/*_big.jpg\",\n \"avatar_medium\": \"https://*.cloudfront.net/*_medium.jpg\",\n \"avatar_s640\": \"https://*.cloudfront.net/*_s640.jpg\",\n \"avatar_small\": \"https://*.cloudfront.net/*_small.jpg\",\n \"business_account_id\": \"1\",\n \"daily_goal\": 15,\n \"date_format\": 0,\n \"days_off\": [6, 7],\n \"email\": \"me@example.com\",\n \"feature_identifier\": \"2671355_0123456789abcdef70123456789abcdefe0123456789abcdefd0123456789abc\",\n \"features\": {\n \"beta\": 1,\n \"dateist_inline_disabled\": false,\n \"dateist_lang\": null,\n \"global.teams\": true,\n \"has_push_reminders\": true,\n \"karma_disabled\": false,\n \"karma_vacation\": false,\n \"kisa_consent_timestamp\": null,\n \"restriction\": 3\n },\n \"full_name\": \"Example User\",\n \"has_password\": true,\n \"id\": \"2671355\",\n \"image_id\": \"d160009dfd52b991030d55227003450f\",\n \"inbox_project_id\": \"6X7fqH39MwjmwV4q\",\n \"is_celebrations_enabled\": true,\n \"is_premium\": true,\n \"joinable_workspace\": null,\n \"joined_at\": \"2015-07-31T18:32:06.000000Z\",\n \"karma\": 37504,\n \"karma_trend\": \"up\",\n \"lang\": \"en\",\n \"mfa_enabled\": false,\n \"next_week\": 1,\n \"premium_status\": \"current_personal_plan\",\n \"premium_until\": null,\n \"share_limit\": 51,\n \"sort_order\": 0,\n \"start_day\": 1,\n \"start_page\": \"project?id=2203306141\",\n \"theme_id\": \"11\",\n \"time_format\": 0,\n \"token\": \"0123456789abcdef0123456789abcdef01234567\",\n \"urgent_reminder_device\": {\n \"device_platform\": \"ios\",\n \"device_id\": \"12345678\",\n \"device_token\": \"a1b2c3d4...\",\n \"device_name\": \"iPhone 15 Pro\"\n },\n \"tz_info\": {\n \"gmt_string\": \"-03:00\",\n \"hours\": -3,\n \"is_dst\": 0,\n \"minutes\": 0,\n \"timezone\": \"America/Sao_Paulo\"\n },\n \"verification_status\": \"legacy\",\n \"weekend_start_day\": 6,\n \"weekly_goal\": 30\n}\n```\n\nA Todoist user is represented by a JSON object. The dates will be in the UTC\ntimezone. Typically, a user object will have the following properties:\n\n#### Properties\n\n| Property | Description |\n|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| auto_reminder _Integer_ | The default time in minutes for the automatic reminders set, whenever a due date has been specified for a task. |\n| avatar_big _String_ | The link to a 195x195 pixels image of the user's avatar. |\n| avatar_medium _String_ | The link to a 60x60 pixels image of the user's avatar. |\n| avatar_s640 _String_ | The link to a 640x640 pixels image of the user's avatar. |\n| avatar_small _String_ | The link to a 35x35 pixels image of the user's avatar. |\n| business_account_id _String_ | The ID of the user's business account. |\n| daily_goal _Integer_ | The daily goal number of completed tasks for karma. |\n| date_format _Integer_ | Whether to use the `DD-MM-YYYY` date format (if set to `0`), or the `MM-DD-YYYY` format (if set to `1`). |\n| dateist_lang _String_ | The language expected for date recognition instead of the user's `lang` (`null` if the user's `lang` determines this), one of the following values: `da`, `de`, `en`, `es`, `fi`, `fr`, `it`, `ja`, `ko`, `nl`, `pl`, `pt_BR`, `ru`, `sv`, `tr`, `zh_CN`, `zh_TW`. |\n| days_off _Array_ | Array of integers representing user's days off (between `1` and `7`, where `1` is `Monday` and `7` is `Sunday`). |\n| email _String_ | The user's email. |\n| feature_identifier _String_ | An opaque id used internally to handle features for the user. |\n| features _Object_ | Used internally for any special features that apply to the user. Current special features include whether the user has enabled `beta`, whether `dateist_inline_disabled` that is inline date parsing support is disabled, whether the `dateist_lang` is set which overrides the date parsing language, whether the `gold_theme` has been awarded to the user, whether the user `has_push_reminders` enabled, whether the user has `karma_disabled`, whether the user has `karma_vacation` mode enabled, and whether any special `restriction` applies to the user. |\n| full_name _String_ | The user's real name formatted as `Firstname Lastname`. |\n| has_password _Boolean_ | Whether the user has a password set on the account. It will be `false` if they have only authenticated without a password (e.g. using Google, Facebook, etc.) |\n| id _String_ | The user's ID. |\n| image_id _String_ | The ID of the user's avatar. |\n| inbox_project_id _String_ | The ID of the user's `Inbox` project. |\n| is_premium _Boolean_ | Whether the user has a Todoist Pro subscription (a `true` or `false` value). |\n| joined_at _String_ | The date when the user joined Todoist. |\n| karma _Integer_ | The user's karma score. |\n| karma_trend _String_ | The user's karma trend (for example `up`). |\n| lang _String_ | The user's language, which can take one of the following values: `da`, `de`, `en`, `es`, `fi`, `fr`, `it`, `ja`, `ko`, `nl`, `pl`, `pt_BR`, `ru`, `sv`, `tr`, `zh_CN`, `zh_TW`. |\n| next_week _Integer_ | The day of the next week, that tasks will be postponed to (between `1` and `7`, where `1` is `Monday` and `7` is `Sunday`). |\n| premium_status _String_ | Outlines why a user is premium, possible values are: `not_premium`, `current_personal_plan`, `legacy_personal_plan` or `teams_business_member`. |\n| premium_until _String_ | The date when the user's Todoist Pro subscription ends (`null` if not a Todoist Pro user). This should be used for informational purposes only as this does not include the grace period upon expiration. As a result, avoid using this to determine whether someone has a Todoist Pro subscription and use `is_premium` instead. |\n| sort_order _Integer_ | Whether to show projects in an `oldest dates first` order (if set to `0`, or a `oldest dates last` order (if set to `1`). |\n| start_day _Integer_ | The first day of the week (between `1` and `7`, where `1` is `Monday` and `7` is `Sunday`). |\n| start_page _String_ | 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. |\n| theme_id _String_ | The currently selected Todoist theme (a number between `0` and `10`). |\n| time_format _Integer_ | 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`). |\n| token _String_ | The user's token that should be used to call the other API methods. |\n| urgent_reminder_device _Object_ | The device designated to receive urgent reminder alarms. Contains `device_platform` (`ios` or `android`), `device_id` (the device's numeric ID), `device_token` (the push notification token), and optionally `device_name`. Set to `null` if no device is configured. |\n| tz_info _Object_ | The user's timezone (a dictionary structure), which includes the following elements: the `timezone` as a string value, the `hours` and `minutes` difference from GMT, whether daylight saving time applies denoted by `is_dst`, and a string value of the time difference from GMT that is `gmt_string`. |\n| weekend_start_day _Integer_ | 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). |\n| verification_status _String_ | Describes if the user has verified their e-mail address or not. Possible values are: |\n\n- `unverified`, for users that have just signed up. Those users cannot use any of Todoist's social features like sharing projects or accepting project invitations.\n- `verified`, for users that have verified themselves somehow. Clicking on the verification link inside the account confirmation e-mail is one such way alongside signing up through a social account.\n- `blocked`, for users that have failed to verify themselves in 7 days. Those users will have restricted usage of Todoist.\n- `legacy`, for users that have signed up before August, 2022 weekly_goal _Integer_ | The target number of tasks to complete per week.\n\n## Update user's properties\n\n> Example update user request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"user_update\",\n \"uuid\": \"52f83009-7e27-4b9f-9943-1c5e3d1e6889\",\n \"args\": {\n \"current_password\": \"fke4iorij\",\n \"email\": \"mynewemail@example.com\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"52f83009-7e27-4b9f-9943-1c5e3d1e6889\": \"ok\"},\n ...\n}\n```\n\n#### Command arguments\n\n| Argument | Required | Description |\n|--------------------------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 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](#tag/Sync/User) object). For amending other properties this is not required. |\n| email _String_ | No | The user's email. |\n| full_name _String_ | No | The user's name. |\n| password _String_ | No | The user's updated password. Must contain at least 8 characters and not be a common or easily guessed password. |\n| timezone _String_ | No | The user's timezone (a string value such as `UTC`, `Europe/Lisbon`, `US/Eastern`, `Asia/Taipei`). |\n| 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. |\n| start_day _Integer_ | No | The first day of the week (between `1` and `7`, where `1` is `Monday` and `7` is `Sunday`). |\n| 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`). |\n| 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`). |\n| 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`). |\n| 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`). |\n| auto_reminder _Integer_ | No | The default time in minutes for the automatic reminders set, whenever a due date has been specified for a task. |\n| 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. |\n| theme _Integer_ | No | The currently selected Todoist theme (between `0` and `10`). |\n| 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). |\n| beta _Boolean_ | No | Whether the user is included in the beta testing group. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n\n#### Error codes\n\n| Error Tag | Description |\n|---------------------------|----------------------------------------------------------------------------------------------------------|\n| `PASSWORD_REQUIRED` | The command attempted to modify `password` or `email`, but no value was provided for `current_password`. |\n| `AUTHENTICATION_ERROR` | The value for `current_password` was incorrect. |\n| `PASSWORD_TOO_SHORT` | The value for `password` was shorter than the minimum 8 characters. |\n| `COMMON_PASSWORD` | The value for `password` was matched against a common password list and rejected. |\n| `PASSWORD_CONTAINS_EMAIL` | The value for password was matched against the user's email address or a part of the address. |\n| `INVALID_EMAIL` | The value for `email` was not a valid email address. |\n| `BAD_REQUEST` | The value for `urgent_reminder_device` was invalid (missing or malformed `device_platform`, `device_id`, or `device_token`). |\n| `ERROR_DEVICE_NOT_FOUND` | The device specified in `urgent_reminder_device` is not registered for this user. |\n\n## Update karma goals\n\n> Example update karma goals request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"update_goals\",\n \"uuid\": \"b9bbeaf8-9db6-452a-a843-a192f1542892\",\n \"args\": {\"vacation_mode\": 1}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"b9bbeaf8-9db6-452a-a843-a192f1542892\": \"ok\"},\n ...\n}\n```\n\nUpdate the karma goals of the user.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|--------------------------|----------|---------------------------------------------------------------------------------------------------|\n| daily_goal _Integer_ | No | The target number of tasks to complete per day. |\n| weekly_goal _Integer_ | No | The target number of tasks to complete per week. |\n| ignore_days _Integer_ | No | A list with the days of the week to ignore (`1` for `Monday` and `7` for `Sunday`). |\n| vacation_mode _Integer_ | No | Marks the user as being on vacation (where `1` is true and `0` is false). |\n| karma_disabled _Integer_ | No | Whether to disable the karma and goals measuring altogether (where `1` is true and `0` is false). |\n\n## User plan limits\n\n> An example user plan limits sync response\n\n```\n{\n \"user_plan_limits\": {\n \"current\": {\n \"plan_name\": \"free\",\n ...details of the current user plan\n },\n \"next\": {\n \"plan_name\": \"pro\",\n ...details of a potential upgrade\n }\n }\n}\n```\n\nThe `user_plan_limits` sync resource type describes the available features and\nlimits applicable to the current user plan. The user plan info object (detailed\nin the next section) returned within the `current` property shows the values\nthat are currently applied to the user.\n\nIf there is an upgrade available, the `next` property will show the values that will apply if the user chooses\nto upgrade. If there is no available upgrade, the `next` value will be null.\n\n#### Properties\n\n| Property | Description |\n|------------------|---------------------------------------------------------------------------------------------------------------------------------|\n| current _Object_ | A user plan info object representing the available functionality and limits for the user's current plan. |\n| next _Object_ | A user plan info object representing the plan available for upgrade. If there is no available upgrade, this value will be null. |\n\n### User plan info\n\n> An example user plan info object\n\n```\n{\n \"activity_log\": true,\n \"activity_log_limit\": 7,\n \"advanced_permissions\": true,\n \"automatic_backups\": false,\n \"calendar_feeds\": true,\n \"calendar_layout\": true,\n \"comments\": true,\n \"completed_tasks\": true,\n \"custom_app_icon\": false,\n \"customization_color\": false,\n \"deadlines\": true,\n \"durations\": true,\n \"email_forwarding\": true,\n \"filters\": true,\n \"labels\": true,\n \"max_calendar_accounts\": 1,\n \"max_collaborators\": 5,\n \"max_filters\": 3,\n \"max_folders_per_workspace\": 25,\n \"max_workspace_filters\": 3,\n \"workspace_filters\": true,\n \"max_free_workspaces_created\": 1,\n \"max_guests_per_workspace\": 25,\n \"max_labels\": 500,\n \"max_projects\": 5,\n \"max_projects_joined\": 500,\n \"max_reminders_location\": 300,\n \"max_reminders_time\": 700,\n \"max_sections\": 20,\n \"max_tasks\": 300,\n \"max_user_templates\": 100,\n \"plan_name\": \"free\",\n \"reminders\": false,\n \"reminders_at_due\": true,\n \"templates\": true,\n \"upload_limit_mb\": 5,\n \"uploads\": true,\n \"weekly_trends\": true\n}\n```\n\nThe user plan info object describes the availability of features and any limitations applied for a given user plan.\n\n#### Properties\n\n| Property | Description |\n|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------|\n| plan_name _String_ | The name of the plan. |\n| activity_log _Boolean_ | Whether the user can view the [activity log](#tag/Activity). |\n| activity_log_limit _Integer_ | The number of days of history that will be displayed within the activity log. If there is no limit, the value will be `-1`. |\n| automatic_backups _Boolean_ | Whether [backups](#tag/Backups) will be automatically created for the user's account and available for download. |\n| calendar_feeds _Boolean_ | Whether calendar feeds can be enabled for the user's projects. |\n| comments _Boolean_ | Whether the user can add [comments](#tag/Sync/Comments). |\n| completed_tasks _Boolean_ | Whether the user can search in the completed tasks archive or access the completed tasks overview. |\n| custom_app_icon _Boolean_ | Whether the user can set a custom app icon on the iOS app. |\n| customization_color _Boolean_ | Whether the user can use special themes or other visual customization. |\n| email_forwarding _Boolean_ | Whether the user can add tasks or comments via [email](#tag/Emails). |\n| filters _Boolean_ | Whether the user can add and update [filters](#tag/Sync/Filters). |\n| max_filters _Integer_ | The maximum number of filters a user can have. |\n| workspace_filters _Boolean_ | Whether the user can add and update [workspace filters](#tag/Sync/Workspace-Filters) (Business/Enterprise plans only). |\n| max_workspace_filters _Integer_ | The maximum number of workspace filters a user can have per workspace. |\n| labels _Boolean_ | Whether the user can add [labels](#tag/Sync/Labels). |\n| max_labels _Integer_ | The maximum number of labels a user can have. |\n| reminders _Boolean_ | Whether the user can add [reminders](#tag/Sync/Reminders). |\n| max_reminders_location _Integer_ | The maximum number of location reminders a user can have. |\n| max_reminders_time _Integer_ | The maximum number of time-based reminders a user can have. |\n| templates _Boolean_ | Whether the user can import and export [project templates](#tag/Templates). |\n| uploads _Boolean_ | Whether the user can [upload attachments](#tag/Uploads). |\n| upload_limit_mb _Integer_ | The maximum size of an individual file the user can upload. |\n| weekly_trends _Boolean_ | Whether the user can view [productivity stats](#tag/Sync/User). |\n| max_projects _Integer_ | The maximum number of active [projects](#tag/Sync/Projects) a user can have. |\n| max_sections _Integer_ | The maximum number of active [sections](#tag/Sync/Sections) a user can have. |\n| max_tasks _Integer_ | The maximum number of active [tasks](#tag/Sync/Tasks) a user can have. |\n| max_collaborators _Integer_ | The maximum number of [collaborators](#tag/Sync/Sharing/Collaborators) a user can add to a project. |\n\n## User settings\n\n> Example user settings object:\n\n```\n{\n \"reminder_push\": true,\n \"reminder_desktop\": true,\n \"reminder_email\": true,\n \"completed_sound_desktop\": true,\n \"completed_sound_mobile\": true\n}\n```\n\n_Availability of reminders functionality is dependent on the current user plan.\nThis value is indicated by the `reminders` property of the [user plan limits](#tag/Sync/User/User-plan-limits) object.\nThese settings will have no effect if the user is not eligible for reminders._\n\n#### Properties\n\n| Property | Description |\n|-----------------------------------|----------------------------------------------------------------------------------|\n| reminder_push _Boolean_ | Set to true to send reminders as push notifications. |\n| reminder_desktop _Boolean_ | Set to true to show reminders in desktop applications. |\n| reminder_email _Boolean_ | Set to true to send reminders by email. |\n| completed_sound_desktop _Boolean_ | Set to true to enable sound when a task is completed in Todoist desktop clients. |\n| completed_sound_mobile _Boolean_ | Set to true to enable sound when a task is completed in Todoist mobile clients. |\n\n## User productivity stats\n\n> Example stats object:\n\n```json\n{\n \"completed_count\": 123,\n \"days_items\": [\n {\n \"date\": \"2025-10-17\",\n \"total_completed\": 5\n }\n ],\n \"week_items\": [\n {\n \"from\": \"2025-10-13\",\n \"to\": \"2025-10-19\",\n \"total_completed\": 12\n }\n ]\n}\n```\n\n#### Properties\n\n| Property | Description |\n|------------------------------|------------------------------------------------------------------------------------------------------------|\n| completed_count _Integer_ | The total number of tasks the user has completed across all time. |\n| days_items _Array_ | An array containing completion statistics for today. Each item contains `date` and `total_completed`. |\n| week_items _Array_ | An array containing completion statistics for the current week. Each item contains `from`, `to`, and `total_completed`. |\n\n### Update user settings\n\n> Example update user settings request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"user_settings_update\",\n \"temp_id\": \"e24ad822-a0df-4b7d-840f-83a5424a484a\",\n \"uuid\": \"41e59a76-3430-4e44-92b9-09d114be0d49\",\n \"args\": {\"reminder_desktop\": false}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"41e59a76-3430-4e44-92b9-09d114be0d49\": \"ok\"},\n ...\n}\n```\n\nUpdate one or more user settings.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-----------------------------------|----------|----------------------------------------------------------------------------------|\n| reminder_push _Boolean_ | No | Set to true to send reminders as push notifications. |\n| reminder_desktop _Boolean_ | No | Set to true to show reminders in desktop applications. |\n| reminder_email _Boolean_ | No | Set to true to send reminders by email. |\n| completed_sound_desktop _Boolean_ | No | Set to true to enable sound when a task is completed in Todoist desktop clients. |\n| completed_sound_mobile _Boolean_ | No | Set to true to enable sound when a task is completed in Todoist mobile clients. |\n\n# Sharing\n\nProjects can be shared with other users, which are then referred to as collaborators.\nThis section describes the different commands that are related to sharing.\n\n## Collaborators\n\n> An example collaborator object:\n\n```\n{\n \"id\": \"2671362\",\n \"email\": \"you@example.com\",\n \"full_name\": \"Example User\",\n \"timezone\": \"GMT +3:00\",\n \"image_id\": null\n}\n```\n\nThere are two types of objects to get information about a user\u2019s collaborators,\nand their participation in shared projects: `collaborators` and\n`collaborator_states`\n\nEvery user who shares at least one project with another user, has a\ncollaborators record in the API response. The record contains a restricted\nsubset of user-specific properties.\n\n| Property | Description |\n|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | The user ID of the collaborator. |\n| email _String_ | The email of the collaborator. |\n| full_name _String_ | The full name of the collaborator. |\n| timezone _String_ | The timezone of the collaborator. |\n| image_id _String_ | The image ID for the collaborator's avatar, which can be used to get an avatar from a specific URL. Specifically the `https://dcff1xvirvpfp.cloudfront.net/_big.jpg` can be used for a big (`195x195` pixels) avatar, `https://dcff1xvirvpfp.cloudfront.net/_medium.jpg` for a medium (`60x60` pixels) avatar, and `https://dcff1xvirvpfp.cloudfront.net/_small.jpg` for a small (`35x35` pixels) avatar. |\n\nPartial sync returns updated collaborator objects for users that have changed\ntheir attributes, such as their name or email.\n\n## Collaborator states\n\n> An example collaborator state:\n\n```\n{\n \"project_id\": \"6H2c63wj7x9hFJfX\",\n \"user_id\": \"2671362\",\n \"state\": \"active\",\n \"is_deleted\": false,\n \"role\": \"READ_WRITE\",\n}\n```\n\nThe list of collaborators don\u2019t contain any information on how users are\nconnected to shared projects. To provide information about these connections,\nthe `collaborator_states` field should be used. Every collaborator state record\nis a mere \"user to shared project\" mapping.\n\n| Property | Description |\n|----------------------|-------------------------------------------------------------------------|\n| project_id _String_ | The shared project ID of the user. |\n| user_id _String_ | The user ID of the collaborator. |\n| state _String_ | The status of the collaborator state, either `active` or `invited`. |\n| is_deleted _Boolean_ | Set to `true` when the collaborator leaves the shared project. |\n| role | The role of the collaborator in the project. _Only available for teams_ |\n\n## Share a project\n\n> Example share project request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"share_project\",\n \"temp_id\": \"854be9cd-965f-4ddd-a07e-6a1d4a6e6f7a\",\n \"uuid\": \"fe6637e3-03ce-4236-a202-8b28de2c8372\",\n \"args\": {\n \"project_id\": \"6H2c63wj7x9hFJfX\",\n \"email\": \"you@example.com\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"fe6637e3-03ce-4236-a202-8b28de2c8372\": \"ok\"},\n ...\n}\n```\n\nShare a project with another user.\n\n_When sharing a teams project_\n\nWorkspace projects with `is_invite_only` set to true can only be shared by\nworkspace admins, or by project members with `ADMIN` or `CREATOR` role. Other\nusers will get a \u201cforbidden\u201d error. The role for the new collaborator cannot be\ngreater than the role of the person sharing the project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|---------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------|\n| project_id _String_ | Yes | The project to be shared. |\n| email _String_ | Yes | The user email with whom to share the project. |\n| 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_ |\n\n## Delete a collaborator\n\n> Example delete collaborator request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"delete_collaborator\",\n \"uuid\": \"0ae55ac0-3b8d-4835-b7c3-59ba30e73ae4\",\n \"args\": {\n \"project_id\": \"6H2c63wj7x9hFJfX\",\n \"email\": \"you@example.com\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"0ae55ac0-3b8d-4835-b7c3-59ba30e73ae4\": \"ok\"},\n ...\n}\n```\n\nRemove a user from a shared project.\nIn Teams, only workspace admins or project members with `ADMIN` or `CREATOR` role can delete a collaborator. Other users will get a \u201cforbidden\u201d error.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|---------------------|----------|--------------------------------------------------|\n| project_id _String_ | Yes | The project to be affected. |\n| email _String_ | Yes | The user email with whom the project was shared. |\n\n## Accept an invitation\n\n> Example accept invitation request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"accept_invitation\",\n \"uuid\": \"4b254da4-fa2b-4a88-9439-b27903a90f7f\",\n \"args\": {\n \"invitation_id\": \"1234\",\n \"invitation_secret\": \"abcdefghijklmno\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"4b254da4-fa2b-4a88-9439-b27903a90f7f\": \"ok\"},\n ...\n}\n```\n\nAccept an invitation to join a shared project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|----------------------------|----------|------------------------------------------------|\n| invitation_id _String_ | Yes | The invitation ID. |\n| invitation_secret _String_ | Yes | The secret fetched from the live notification. |\n\n## Reject an invitation\n\n> Example reject invitation request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"reject_invitation\",\n \"uuid\": \"284fd900-c36f-44e5-ab92-ee93455e50e0\",\n \"args\": {\n \"invitation_id\": \"1234\",\n \"invitation_secret\": \"abcdefghijklmno\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"284fd900-c36f-44e5-ab92-ee93455e50e0\": \"ok\"},\n ...\n}\n```\n\nReject an invitation to join a shared project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|----------------------------|----------|------------------------------------------------|\n| invitation_id _String_ | Yes | The invitation ID. |\n| invitation_secret _String_ | Yes | The secret fetched from the live notification. |\n\n## Delete an invitation\n\n> Example delete invitation request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"delete_invitation\",\n \"uuid\": \"399f6a8d-ddea-4146-ae8e-b41fb8ff6945\",\n \"args\": {\"invitation_id\": \"1234\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"399f6a8d-ddea-4146-ae8e-b41fb8ff6945\": \"ok\"},\n ...\n}\n```\n\nDelete an invitation to join a shared project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|------------------------|----------|-------------------------------|\n| invitation_id _String_ | Yes | The invitation to be deleted. |\n\n# Sections\n\n> An example section object\n\n```\n{\n \"id\": \"6Jf8VQXxpwv56VQ7\",\n \"name\": \"Groceries\",\n \"description\": \"Tasks for the launch plan\",\n \"project_id\": \"9Bw8VQXxpwv56ZY2\",\n \"section_order\": 1,\n \"order_key\": \"a1V\",\n \"is_collapsed\": false,\n \"user_id\": \"2671355\",\n \"is_deleted\": false,\n \"is_archived\": false,\n \"archived_at\": null,\n \"added_at\": \"2019-10-07T07:09:27.000000Z\",\n \"updated_at\": \"2019-10-07T07:09:27.000000Z\"\n}\n```\n\n#### Properties\n\n| Property | Description |\n|-------------------------|-------------------------------------------------------------------------------------------------------|\n| id _String_ | The ID of the section. |\n| name _String_ | The name of the section. |\n| description _String_ | The description of the section (or `null` if it has none). |\n| project_id _String_ | Project that the section resides in |\n| section_order _Integer_ | The order of the section. Defines the position of the section among all the sections in the project. |\n| order_key _String_ | Section's fractional-indexing order key: sections sort by comparing keys lexicographically within a project. May be `null` for projects not yet migrated. |\n| is_collapsed _Boolean_ | Whether the section's tasks are collapsed (a `true` or `false` value). |\n| is_deleted _Boolean_ | Whether the section is marked as deleted (a `true` or `false` value). |\n| is_archived _Boolean_ | Whether the section is marked as archived (a `true` or `false` value). |\n| archived_at _String_ | The date when the section was archived (or `null` if not archived). |\n| added_at _String_ | The date when the section was created. |\n| updated_at _String_ | The date when the section was updated. |\n\n## Add a section\n\n> Example add section request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[{\n \"type\": \"section_add\",\n \"temp_id\": \"69ca86df-5ffe-4be4-9c3a-ad14fe98a58a\",\n \"uuid\": \"97b68ab2-f524-48da-8288-476a42cccf28\",\n \"args\": {\"name\": \"Groceries\", \"project_id\": \"9Bw8VQXxpwv56ZY2\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"97b68ab2-f524-48da-8288-476a42cccf28\": \"ok\"},\n \"temp_id_mapping\": {\"69ca86df-5ffe-4be4-9c3a-ad14fe98a58a\": \"6X7FxXvX84jHphx2\"},\n ...\n}\n```\n\nAdd a new section to a project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------------------|----------|------------------------------------------------------------------------------------------------------|\n| name _String_ | Yes | The name of the section. |\n| project_id _String_ | Yes | The ID of the parent project. |\n| description _String_ | No | The description of the section. |\n| section_order _Integer_ | No | The order of the section. Defines the position of the section among all the sections in the project. |\n| 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. |\n\n## Update a section\n\n> Example update section request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[{\n \"type\": \"section_update\",\n \"uuid\": \"afda2f29-319c-4d09-8162-f2975bed3124\",\n \"args\": {\"id\": \"6X7FxXvX84jHphx2\", \"name\": \"Supermarket\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"afda2f29-319c-4d09-8162-f2975bed3124\": \"ok\"},\n ...\n}\n```\n\nUpdates section attributes.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|------------------------|----------|------------------------------------------------------------------------|\n| id _String_ | Yes | The ID of the section. |\n| name _String_ | No | The name of the section. |\n| description _String_ | No | The description of the section. Pass `null` to clear it; omit to leave it unchanged. |\n| 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. |\n| is_collapsed _Boolean_ | No | Whether the section's tasks are collapsed (a `true` or `false` value). |\n\n## Move a section\n\n> Example move section request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[{\n \"type\": \"section_move\",\n \"uuid\": \"a8583f66-5885-4729-9e55-462e72d685ff\",\n \"args\": {\"id\": \"6X7FxXvX84jHphx2\", \"project_id\": \"9Bw8VQXxpwv56ZY2\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"a8583f66-5885-4729-9e55-462e72d685ff\": \"ok\"},\n ...\n}\n```\n\nMove section to a different location.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|---------------------|----------|--------------------------------|\n| id _String_ | Yes | The ID of the section. |\n| project_id _String_ | No | ID of the destination project. |\n\n## Reorder sections\n\n> Example reorder sections request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[{\n \"type\": \"section_reorder\",\n \"uuid\": \"109af205-6ff7-47fa-a5f8-1f13e59744ef\",\n \"args\": {\n \"sections\": [\n {\"id\": \"6X7FxXvX84jHphx2\", \"section_order\": 1},\n {\"id\": \"6X9FxXvX64jjphx3\", \"section_order\": 2}\n ]\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"109af205-6ff7-47fa-a5f8-1f13e59744ef\": \"ok\"},\n ...\n}\n```\n\nThe command updates `section_order` properties of sections in bulk.\n\n**Deprecation notice:** This command is deprecated and will be removed in a future\nversion. Reorder sections by setting the `order_key` property via `section_update`\ninstead: a reorder then updates a single section rather than rewriting the order of\nevery section in the project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-----------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------|\n| 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. |\n\n## Delete a section\n\n> Example delete section request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[{\n \"type\": \"section_delete\",\n \"uuid\": \"cebb5267-3e3c-40da-af44-500649281936\",\n \"args\": {\"id\": \"6X7FxXvX84jHphx2\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"cebb5267-3e3c-40da-af44-500649281936\": \"ok\"},\n ...\n}\n```\n\nDelete a section and all its child tasks.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|------------------------------|\n| id _String_ | Yes | ID of the section to delete. |\n\n## Archive a section\n\n> Example archive section request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[{\n \"type\": \"section_archive\",\n \"uuid\": \"2451f267-46ab-4f0e-8db7-82a9cd576f72\",\n \"args\": {\"id\": \"6X7FxXvX84jHphx2\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"2451f267-46ab-4f0e-8db7-82a9cd576f72\": \"ok\"},\n ...\n}\n```\n\nArchive a section and all its child tasks.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|------------------------|\n| id _String_ | Yes | Section ID to archive. |\n\n## Unarchive a section\n\n> Example unarchive section request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[{\n \"type\": \"section_unarchive\",\n \"uuid\": \"cd3a4b4b-182e-4733-b6b5-20a621ba98b8\",\n \"args\": {\"id\": \"6X7FxXvX84jHphx2\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"cd3a4b4b-182e-4733-b6b5-20a621ba98b8\": \"ok\"},\n ...\n}\n```\n\nThis command is used to unarchive a section.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|-------------------------|\n| id _String_ | Yes | Section ID to unarchive |\n\n# Reminders\n\n> An example reminder:\n\n```\n{\n \"id\": \"6X7Vfq5rqPMM5j5q\",\n \"notify_uid\": \"2671355\",\n \"item_id\": \"6RP2hmPwM3q4WGfW\",\n \"type\": \"absolute\",\n \"due\": {\n \"date\": \"2016-08-05T07:00:00.000000Z\",\n \"timezone\": null,\n \"is_recurring\": false,\n \"string\": \"tomorrow at 10:00\",\n \"lang\": \"en\"\n },\n \"minute_offset\": 180,\n \"is_deleted\": false,\n \"is_urgent\": false\n}\n```\n\n_Availability of reminders functionality and the maximum number of stored reminders are dependent\non the current user plan. These values are indicated by the `reminders`, `max_reminders_time` and\n`max_reminders_location` properties of the [user plan limits](#tag/Sync/User/User-plan-limits) object._\n\n#### Properties\n\n| Property | Description |\n|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | The ID of the reminder. |\n| notify_uid _String_ | The user ID which should be notified of the reminder, typically the current user ID creating the reminder. |\n| item_id _String_ | The item ID for which the reminder is about. |\n| type _String_ | 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. |\n| due _Object_ | The due date of the reminder. See the [Due dates](#tag/Due-dates) section for more details. Note that reminders only support due dates with time, since full-day reminders don't make sense. |\n| minute_offset _Integer_ | 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. |\n| name _String_ | An alias name for the location. |\n| loc_lat _String_ | The location latitude. |\n| loc_long _String_ | The location longitude. |\n| loc_trigger _String_ | What should trigger the reminder: `on_enter` for entering the location, or `on_leave` for leaving the location. |\n| radius _Integer_ | The radius around the location that is still considered as part of the location (in meters). |\n| is_deleted _Boolean_ | Whether the reminder is marked as deleted (a `true` or `false` value). |\n| is_urgent _Boolean_ | Whether the reminder is an urgent reminder. Urgent reminders trigger an alarm notification on the user's designated urgent reminder device. Only present for time-based reminders (`relative` or `absolute`); omitted for `location` reminders. |\n\n## Add a reminder\n\n> Example of adding relative reminder:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"reminder_add\",\n \"temp_id\": \"e24ad822-a0df-4b7d-840f-83a5424a484a\",\n \"uuid\": \"41e59a76-3430-4e44-92b9-09d114be0d49\",\n \"args\": {\n \"item_id\": \"6RP2hmPwM3q4WGfW\",\n \"minute_offset\": 30,\n \"type\": \"absolute\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"41e59a76-3430-4e44-92b9-09d114be0d49\": \"ok\"},\n \"temp_id_mapping\": {\"e24ad822-a0df-4b7d-840f-83a5424a484a\": \"2992683215\"},\n ...\n}\n```\n\n> Example of adding an absolute reminder:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"reminder_add\",\n \"temp_id\": \"952a365e-4965-4113-b4f4-80cdfcada172u\",\n \"uuid\": \"e7c8be2d-f484-4852-9422-a9984c58b1cd\",\n \"args\": {\n \"item_id\": \"6RP2hmPwM3q4WGfW\",\n \"due\": {\n \"date\": \"2014-10-15T11:00:00.000000Z\"\n },\n \"type\": \"absolute\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"e7c8be2d-f484-4852-9422-a9984c58b1cd\": \"ok\"},\n \"temp_id_mapping\": {\"952a365e-4965-4113-b4f4-80cdfcada172\": \"2992683215\"},\n ...\n}\n```\n\n> Example of adding a location reminder:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"reminder_add\",\n \"temp_id\": \"7ad9609d-579f-4828-95c5-3600acdb2c81\",\n \"uuid\": \"830cf409-daba-479c-a624-68eb0c07d01c\",\n \"args\": {\n \"item_id\": \"6RP2hmPwM3q4WGfW\",\n \"type\": \"location\",\n \"name\": \"Aliados\",\n \"loc_lat\": \"41.148581\",\n \"loc_long\":\"-8.610945000000015\",\n \"loc_trigger\":\"on_enter\",\n \"radius\": 100\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"830cf409-daba-479c-a624-68eb0c07d01c\": \"ok\"},\n \"temp_id_mapping\": {\"7ad9609d-579f-4828-95c5-3600acdb2c81\": \"2992683215\"},\n ...\n}\n```\n\nAdd a new reminder to the user account related to the API credentials.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| item_id _String_ | Yes | The item ID for which the reminder is about. |\n| 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. |\n| notify_uid _String_ | No | The user ID which should be notified of the reminder, typically the current user ID creating the reminder. |\n| due _Object_ | No | The due date of the reminder. See the [Due dates](#tag/Due-dates) section for more details. Note that reminders only support due dates with time, since full-day reminders don't make sense. |\n| 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. |\n| name _String_ | No | An alias name for the location. |\n| loc_lat _String_ | No | The location latitude. |\n| loc_long _String_ | No | The location longitude. |\n| loc_trigger _String_ | No | What should trigger the reminder: `on_enter` for entering the location, or `on_leave` for leaving the location. |\n| radius _Integer_ | No | The radius around the location that is still considered as part of the location (in meters). |\n| is_urgent _Boolean_ | No | Whether the reminder is an urgent reminder (default `false`). Only supported for time-based reminders (`relative` or `absolute`). |\n\n## Update a reminder\n\n> Example update reminder request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"reminder_update\",\n \"uuid\": \"b0e7562e-ea9f-4c84-87ee-9cbf9c103234\",\n \"args\": {\n \"id\": \"6X7VrXrqjX6642cv\",\n \"due\": {\n \"date\": \"2014-10-10T15:00:00.000000\"\n }\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"b0e7562e-ea9f-4c84-87ee-9cbf9c103234\": \"ok\"},\n ...\n}\n```\n\nUpdate a reminder from the user account related to the API credentials.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | Yes | The ID of the reminder. |\n| notify_uid _String_ | No | The user ID which should be notified of the reminder, typically the current user ID creating the reminder. |\n| 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. |\n| due _Object_ | No | The due date of the reminder. See the [Due dates](#tag/Due-dates) section for more details. Note that reminders only support due dates with time, since full-day reminders don't make sense. |\n| 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. |\n| name _String_ | No | An alias name for the location. |\n| loc_lat _String_ | No | The location latitude. |\n| loc_long _String_ | No | The location longitude. |\n| loc_trigger _String_ | No | What should trigger the reminder: `on_enter` for entering the location, or `on_leave` for leaving the location. |\n| radius _Integer_ | No | The radius around the location that is still considered as part of the location (in meters). |\n| is_urgent _Boolean_ | No | Whether the reminder is an urgent reminder (default `false`). Only supported for time-based reminders (`relative` or `absolute`). |\n\n## Delete a reminder\n\n> Example delete reminder request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"reminder_delete\",\n \"uuid\": \"0896d03b-eb90-49f7-9020-5ed3fd09df2d\",\n \"args\": {\"id\": \"6X7VrXrqjX6642cv\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"0896d03b-eb90-49f7-9020-5ed3fd09df2d\": \"ok\"},\n ...\n}\n```\n\nDelete a reminder from the current user account.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|-----------------------|\n| id _String_ | Yes | The ID of the filter. |\n\n## Locations\n\nLocations are a top-level entity in the sync model. They contain a list of all\nlocations that are used within user's current location reminders.\n\n> An example location object\n\n```\n[\"Shibuya-ku, Japan\", \"35.6623001098633\", \"139.706527709961\"]\n```\n\n#### Properties\n\nThe location object is specific, as it's not an object, but an ordered array.\n\n| Array index | Description |\n|-------------|-----------------------|\n| 0 _String_ | Name of the location. |\n| 1 _String_ | Location latitude. |\n| 2 _String_ | Location longitude. |\n\n### Clear locations\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[{\"type\": \"clear_locations\", \"uuid\": \"d285ae02-80c6-477c-bfa9-45272d7bddfb\", \"args\": {}}]'\n\n{\n ...\n \"sync_status\": {\"d285ae02-80c6-477c-bfa9-45272d7bddfb\": \"ok\"},\n ...\n}\n```\n\nClears the locations list, which is used for location reminders.\n\n# Projects\n\n> An example project object:\n\n```\n{\n \"id\": \"6Jf8VQXxpwv56VQ7\",\n \"name\": \"Shopping List\",\n \"description\": \"Stuff to buy\",\n \"workspace_id\": 12345,\n \"is_invite_only\": false,\n \"status\": \"IN_PROGRESS\",\n \"is_link_sharing_enabled\": true,\n \"collaborator_role_default\": \"READ_WRITE\",\n \"color\": \"lime_green\",\n \"parent_id\": null,\n \"child_order\": 1,\n \"is_collapsed\": false,\n \"shared\": false,\n \"can_assign_tasks\": false,\n \"is_deleted\": false,\n \"is_archived\": false,\n \"is_favorite\": false,\n \"is_frozen\": false,\n \"view_style\": \"list\",\n \"role\": \"READ_WRITE\"\n \"inbox_project\": true,\n \"folder_id\": null,\n \"created_at\": \"2023-07-13T10:20:59Z\",\n \"updated_at\": \"2024-12-10T13:27:29Z\",\n \"is_pending_default_collaborator_invites: false,\n}\n```\n\n#### Properties\n\n| Property | Description |\n|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | The ID of the project. |\n| name _String_ | The name of the project. |\n| description _String_ | Description for the project. _Only used for teams_ |\n| workspace_id _String_ | Real or temp ID of the workspace the project. _Only used for teams_ |\n| is_invite_only _Boolean_ | 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_ |\n| status _String_ | The status of the project. Possible values: `PLANNED`, `IN_PROGRESS`, `PAUSED`, `COMPLETED`, `CANCELED`. _Only used for teams_ |\n| is_link_sharing_enabled _Boolean_ | 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_ |\n| collaborator_role_default _String_ | 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_ |\n| color _String_ | The color of the project icon. Refer to the `name` column in the [Colors](#tag/Colors) guide for more info. |\n| parent_id _String_ | The ID of the parent project. Set to `null` for root projects. |\n| child_order _Integer_ | The order of the project. Defines the position of the project among all the projects with the same `parent_id` |\n| is_collapsed _Boolean_ | Whether the project's sub-projects are collapsed (a `true` or `false` value). |\n| shared _Boolean_ | Whether the project is shared (a `true` or `false` value). |\n| can_assign_tasks _Boolean_ | Whether tasks in the project can be assigned to users (a `true` or `false` value). |\n| is_deleted _Boolean_ | Whether the project is marked as deleted (a `true` or `false` value). |\n| is_archived _Boolean_ | Whether the project is marked as archived (a `true` or `false` value). |\n| is_favorite _Boolean_ | Whether the project is a favorite (a `true` or `false` value). |\n| is_frozen _Boolean_ | Workspace or personal projects from a canceled subscription (a `true` or `false` value). |\n| view_style _Enum_ | The mode in which to render tasks in this project. One of `list`, `board`, or `calendar`. |\n| role _String_ | The role of the requesting user. Possible values: `CREATOR`, `ADMIN`, `READ_WRITE`, `EDIT_ONLY`, `COMPLETE_ONLY`. _Only used for teams_ |\n| inbox_project _Boolean_ | Whether the project is `Inbox` (`true` or otherwise this property is not sent). |\n| folder_id _String_ | The ID of the folder which this project is in. |\n| created_at _String_ | Project creation date in the format YYYY-MM-DDTHH:MM:SSZ date. |\n| updated_at _String_ | Project update date in the format YYYY-MM-DDTHH:MM:SSZ date. |\n| is_pending_default_collaborator_invites _Boolean_ | If true, we are still adding default collaborators to the project in background. _Only used for teams_ |\n| access _Object_ | Project access configuration. Contains `visibility` (`\"restricted\"`, `\"team\"`, or `\"public\"`) and `configuration` object. For public projects, configuration includes `hide_collaborator_details` and `disable_duplication` booleans. _Only used for teams_ |\n| is_project_insights_enabled _Boolean_ | Whether Project Insights is enabled for this project. Defaults to `true` for new workspace projects. _Only used for teams_ |\n\n**Note:** `project.view_style` takes precedence over\n[`view_options.view_mode`](#tag/Sync/View-Options) for projects in Todoist\nclients. The former is set per project, while the latter is set per user.\n\n## Add a project\n\n> Example add project request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"project_add\",\n \"temp_id\": \"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\",\n \"uuid\": \"32774db9-a1da-4550-8d9d-910372124fa4\",\n \"args\": {\n \"name\": \"Shopping List\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"32774db9-a1da-4550-8d9d-910372124fa4\": \"ok\"},\n \"temp_id_mapping\": {\"4ff1e388-5ca6-453a-b0e8-662ebf373b6b\": \"6Jf8VQXxpwv56VQ7\"},\n ...\n}\n```\n\nAdd a new project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| name _String_ | Yes | The name of the project (a string value). |\n| color _String_ | No | The color of the project icon. Refer to the `name` column in the [Colors](#tag/Colors) guide for more info. |\n| parent_id _String_ | No | The ID of the parent project. Set to `null` for root projects |\n| folder_id _String_ | No | The ID of the folder, when creating projects in workspaces. Set to `null` for root projects |\n| child_order _Integer_ | No | The order of the project. Defines the position of the project among all the projects with the same `parent_id` |\n| is_favorite _Boolean_ | No | Whether the project is a favorite (a `true` or `false` value). |\n| 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. |\n| description _String_ | No | Description for the project (up to 1024 characters). _Only used for teams_ |\n| workspace_id _String_ | No | Real or temp ID of the workspace the project should belong to |\n| 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_ |\n| status _String_ | No | The status of the project. Possible values: `PLANNED`, `IN_PROGRESS`, `PAUSED`, `COMPLETED`, `CANCELED`. _Only used for teams_ |\n| 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_ |\n| 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_ |\n| 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_ |\n| is_project_insights_enabled _Boolean_ | No | Whether Project Insights is enabled for this project. Defaults to `true`. _Only used for teams_ |\n\n## Update a project\n\n> Example update project request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_update\",\n \"uuid\": \"1ca42128-d12f-4a66-8413-4d6ff2838fde\",\n \"args\": {\n \"id\": \"6Jf8VQXxpwv56VQ7\",\n \"name\": \"Shopping\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"1ca42128-d12f-4a66-8413-4d6ff2838fde\": \"ok\"},\n ...\n}\n```\n\nUpdate an existing project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | Yes | The ID of the project (could be temp id). |\n| name _String_ | No | The name of the project (a string value). |\n| color _String_ | No | The color of the project icon. Refer to the `name` column in the [Colors](#tag/Colors) guide for more info. |\n| is_collapsed _Boolean_ | No | Whether the project's sub-projects are collapsed (a `true` or `false` value). |\n| is_favorite _Boolean_ | No | Whether the project is a favorite (a `true` or `false` value). |\n| view_style _String_ | No | A string value (either `list` or `board`). This determines the way the project is displayed within the Todoist clients. |\n| description _String_ | No | Description for the project (up to 1024 characters). _Only used for teams_ |\n| status _String_ | No | The status of the project. Possible values: `PLANNED`, `IN_PROGRESS`, `PAUSED`, `COMPLETED`, `CANCELED`. _Only used for teams_ |\n| 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_ |\n| 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_ |\n| 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_ |\n| is_project_insights_enabled _Boolean_ | No | Whether Project Insights is enabled for this project. _Only used for teams_ |\n\n## Move a project\n\n> Example move project request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_move\",\n \"uuid\": \"1ca42128-d12f-4a66-8413-4d6ff2838fde\",\n \"args\": {\n \"id\": \"6Jf8VQXxpwv56VQ7\",\n \"parent_id\": \"6X7fphhgwcXVGccJ\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"1ca42128-d12f-4a66-8413-4d6ff2838fde\": \"ok\"},\n ...\n}\n```\n\nUpdate parent project relationships of the project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|--------------------|----------|-----------------------------------------------------------------------------------------------------------|\n| id _String_ | Yes | The ID of the project (could be a temp id). |\n| 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. |\n\n## Move a Project to a Workspace\n\n> Example move project to workspace request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_move_to_workspace\",\n \"uuid\": \"1ca42128-d12f-4a66-8413-4d6ff2838fde\",\n \"args\": {\n \"project_id\": \"6Jf8VQXxpwv56VQ7\",\n \"workspace_id\": \"220325187\",\n \"is_invite_only\": false,\n \"folder_id\": null\n }\n }]'\n```\n\n> Example response (with `use_lro=true`):\n\n```shell\n{\n ...\n \"sync_status\": {\n \"1ca42128-d12f-4a66-8413-4d6ff2838fde\": {\n \"operation\": {\n \"id\": \"2147483707\",\n \"operation_type\": \"MOVE_PROJECT_TO_WORKSPACE\",\n \"status\": \"ONGOING\",\n \"args\": {\n \"project_id\": \"6Jf8VQXxpwv56VQ7\",\n \"workspace_id\": \"220325187\"\n },\n \"error\": null,\n \"created_at\": \"2026-01-15T12:00:00.000000Z\",\n \"updated_at\": \"2026-01-15T12:00:00.000000Z\"\n }\n }\n },\n ...\n}\n```\n\nMoves a personal project into the target workspace.\n\nWhen `use_lro=true` is passed, this command creates a Long Running Operation (LRO) and\nprocesses the move in the background. The `sync_status` will contain an `operation`\nobject instead of `\"ok\"`.\n\n**Deprecation notice:** The synchronous behavior (without `use_lro`) is deprecated and\nwill be removed in a future version. In that version, this command will always use LRO.\nClients should migrate to using `use_lro=true`.\n\nA few notes about moving projects to a workspace:\n\n- Moving a parent project to a workspace will also move all its child projects to that workspace.\n- If no folder_id is supplied, child projects will be moved into a folder with the same name as the parent project being moved\n- If a folder_id is supplied, the parent and child projects will be moved into that folder.\n- At the moment, it is not possible to move a project to another workspace (changing its `workspace_id`), or to the user's personal workspace.\n- Moving a project to a workspace affects all its collaborators. Collaborators who are not members of the target workspace will be added as guests, if guest members are allowed in the target workspace\n\n#### Command arguments\n\n| Argument | Required | Description |\n|--------------------------|----------|------------------------------------------------------------------------------------------------------------------|\n| project_id _String_ | Yes | The ID of the project (can be a temp id). |\n| workspace_id _String_ | Yes | The ID of the workspace the project will be moved into |\n| is_invite_only _Boolean_ | No | If true the project will be restricted access, otherwise any workspace member could join it |\n| folder_id _String_ | No | If supplied, the project and any child projects will be moved into this workspace folder |\n| use_lro _Boolean_ | No | If true, process as a Long Running Operation. Recommended; will become the default behavior in a future version. |\n\n## Move a Project out of a Workspace\n\n> Example move project out of a workspace request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_move_to_personal\",\n \"uuid\": \"1ca42128-d12f-4a66-8413-4d6ff2838fde\",\n \"args\": {\n \"project_id\": \"6Jf8VQXxpwv56VQ7\"\n }\n }]'\n```\n\n> Example response (with `use_lro=true`):\n\n```shell\n{\n ...\n \"sync_status\": {\n \"1ca42128-d12f-4a66-8413-4d6ff2838fde\": {\n \"operation\": {\n \"id\": \"2147483708\",\n \"operation_type\": \"MOVE_PROJECT_TO_PERSONAL\",\n \"status\": \"ONGOING\",\n \"args\": {\n \"project_id\": \"6Jf8VQXxpwv56VQ7\"\n },\n \"error\": null,\n \"created_at\": \"2026-01-15T12:00:00.000000Z\",\n \"updated_at\": \"2026-01-15T12:00:00.000000Z\"\n }\n }\n },\n ...\n}\n```\n\nMoves a project inside a workspace out back into a user's personal space.\n\nWhen `use_lro=true` is passed, this command creates a Long Running Operation (LRO) and\nprocesses the move in the background. The `sync_status` will contain an `operation`\nobject instead of `\"ok\"`.\n\n**Deprecation notice:** The synchronous behavior (without `use_lro`) is deprecated and\nwill be removed in a future version. In that version, this command will always use LRO.\nWe recommend migrating to only rely on `use_lro=true`.\n\nOnly the original creator of the project has permissions to do this, and only if they\nare still currently an admin of said workspace.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|---------------------|----------|----------------------------------------------------------------------------------------------------------------------------|\n| project_id _String_ | Yes | The ID of the project being moved back (can be a temp id). |\n| use_lro _Boolean_ | No | If true, process as a Long Running Operation. **Recommended**, as it will become the default behavior in a future version. |\n\n## Leave a project\n\n> Example leave project request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_leave\",\n \"uuid\": \"1ca42128-d12f-4a66-8413-4d6ff2838fde\",\n \"args\": {\n \"project_id\": \"6Jf8VQXxpwv56VQ7\",\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"1ca42128-d12f-4a66-8413-4d6ff2838fde\": \"ok\"},\n ...\n}\n```\n\n_Only used for teams_\n\nThis command is used to remove self from a workspace project. As this is a\nv2-only command, it will only accept v2 project id.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|---------------------|----------|------------------------------------------------------------------------------|\n| project_id _String_ | Yes | The ID (`v2_id`) of the project to leave. It only accepts `v2_id` as the id. |\n\n## Delete a project\n\n> Example delete project request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_delete\",\n \"uuid\": \"367182ba-125f-4dbb-bff6-c1343fd751e4\",\n \"args\": {\n \"id\": \"6X7fphhgwcXVGccJ\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"367182ba-125f-4dbb-bff6-c1343fd751e4\": \"ok\"},\n ...\n}\n```\n\nDelete an existing project and all its descendants.\nWorkspace projects can only be deleted by `ADMIN`s and it must be archived first.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|---------------------------------------------------|\n| id _String_ | Yes | ID of the project to delete (could be a temp id). |\n\n## Archive a project\n\n> Example archive project request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_archive\",\n \"uuid\": \"bbec1a60-2bdd-48ac-a623-c8eb968e1697\",\n \"args\": {\n \"id\": \"6X7fphhgwcXVGccJ\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"bbec1a60-2bdd-48ac-a623-c8eb968e1697\": \"ok\"},\n ...\n}\n```\n\nArchive a project and its descendants.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|----------------------------------------------------|\n| id _String_ | Yes | ID of the project to archive (could be a temp id). |\n\n## Unarchive a project\n\n> Example unarchive project request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_unarchive\",\n \"uuid\": \"7d86f042-e098-4fa6-9c1f-a61fe8c39d74\",\n \"args\": {\n \"id\": \"6X7fphhgwcXVGccJ\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"7d86f042-e098-4fa6-9c1f-a61fe8c39d74\": \"ok\"},\n ...\n}\n```\n\nUnarchive a project. No ancestors will be unarchived along with the unarchived\nproject. Instead, the project is unarchived alone, loses any parent relationship\n(becomes a root project), and is placed at the end of the list of other root\nprojects.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|------------------------------------------------------|\n| id _String_ | Yes | ID of the project to unarchive (could be a temp id). |\n\n## Reorder projects\n\n> Example reorder projects request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_reorder\",\n \"uuid\": \"bf0855a3-0138-4b76-b895-88cad8db9edc\",\n \"args\": {\n \"projects\": [\n {\n \"id\": \"6Jf8VQXxpwv56VQ7\",\n \"child_order\": 1\n },\n {\n \"id\": \"6X7fphhgwcXVGccJ\",\n \"child_order\": 2\n }\n ]\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"bf0855a3-0138-4b76-b895-88cad8db9edc\": \"ok\"},\n ...\n}\n```\n\nThe command updates `child_order` properties of projects in bulk.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-----------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------|\n| 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. |\n\n## Change project role\n\n> Example change project role request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands=[\n {\n \"type\": \"project_change_role\",\n \"uuid\": \"bbec1a60-2bdd-48ac-a623-c8eb968e1697\",\n \"args\": {\n \"id\": \"6X7fphhgwcXVGccJ\",\n \"user_id\": 12345678,\n \"role\": \"EDIT_ONLY\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"bbec1a60-2bdd-48ac-a623-c8eb968e1697\": \"ok\"},\n ...\n}\n```\n\nChange the role a project member has within the project.\n\n#### Command arguments\n\n| Argument | Required | Description |\n|---------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | Yes | ID of the project to change the role for (could be a temp id). |\n| user_id _Int_ | Yes | ID of the user whose role to change. |\n| 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. |\n\n# Comments\n\n## Task comments\n\n> An example task comment:\n\n```\n{\n \"id\": \"6X7gfQHG59V8CJJV\",\n \"posted_uid\": \"2671355\",\n \"item_id\": \"6X7gfV9G7rWm5hW8\",\n \"content\": \"Note\",\n \"file_attachment\": {\n \"file_type\": \"text/plain\",\n \"file_name\": \"File1.txt\",\n \"file_size\": 1234,\n \"file_url\": \"https://example.com/File1.txt\",\n \"upload_state\": \"completed\"\n },\n \"uids_to_notify\": [\n \"84129\"\n ]\n \"is_deleted\": false,\n \"posted_at\": \"2014-10-01T14:54:55.000000Z\",\n \"reactions\": { \"\u2764\ufe0f\": [\"2671362\"], \"\ud83d\udc4d\": [\"2671362\", \"2671366\"] }\n}\n```\n\n_Availability of comments functionality is dependent on the current user plan.\nThis value is indicated by the `comments` property of the\n[user plan limits](#tag/Sync/User/User-plan-limits) object._\n\n#### Properties\n\n| Property | Description |\n|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | The ID of the note. |\n| posted_uid _String_ | The ID of the user that posted the note. |\n| item_id _String_ | The item which the note is part of. |\n| content _String_ | The content of the note. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the [Text Formatting article](https://www.todoist.com/help/articles/format-text-in-a-todoist-task-e5dHw9) in the Help Center. |\n| file_attachment _Object_ | A file attached to the note (see the [File Attachments](#tag/Sync/Comments/File-Attachments) section for details). |\n| uids_to_notify _Array of String_ | A list of user IDs to notify. |\n| is_deleted _Boolean_ | Whether the note is marked as deleted (a `true` or `false` value). |\n| posted_at _String_ | The date when the note was posted. |\n| reactions _Object_ | List of emoji reactions and corresponding user IDs. |\n\n### Add a task comment\n\n> Example add comment request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"note_add\",\n \"temp_id\": \"59fe4461-287b-4b00-bacc-ee771137a732\",\n \"uuid\": \"e1005f08-acd6-4172-bab1-4338f8616e49\",\n \"args\": {\n \"item_id\": \"6X7gfV9G7rWm5hW8\",\n \"content\": \"Note1\"\n }\n }]'\n\n# or adding a comment with a file attached:\n\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"note_add\",\n \"temp_id\": \"6149e689-1a54-48d6-a8c2-0ee5425554a9\",\n \"uuid\": \"554a65e9-56d9-478e-b35b-520c419e37d9\",\n \"args\": {\n \"item_id\": \"6X7gfV9G7rWm5hW8\",\n \"content\": \"Note1\",\n \"file_attachment\": {\n \"file_type\": \"image\\/gif\",\n \"file_name\": \"image.gif\",\n \"image\": \"https:\\/\\/domain\\/image.gif\",\n \"file_url\": \"https:\\/\\/domain\\/image.gif\",\n \"image_width\":90,\n \"image_height\":76,\n \"file_size\":7962\n }\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"e1005f08-acd6-4172-bab1-4338f8616e49\": \"ok\"},\n \"temp_id_mapping\": {\"59fe4461-287b-4b00-bacc-ee771137a732\": \"6X7gfQHG59V8CJJV\"},\n ...\n}\n```\n\n#### Command arguments\n\n| Argument | Required | Description |\n|----------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| item_id _String_ | Yes | The item which the note is part of (a unique number or temp id). |\n| content _String_ | Yes | The content of the note. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the [Text Formatting article](https://www.todoist.com/help/articles/format-text-in-a-todoist-task-e5dHw9) in the Help Center. |\n| file_attachment _Object_ | No | A file attached to the note (see the [File Attachments](#tag/Sync/Comments/File-Attachments) section for details, and learn how to upload a file in the [Uploads section](#tag/Uploads)). |\n| uids_to_notify _Array of String_ | No | A list of user IDs to notify. |\n\n### Update a task comment\n\n> Example update comment request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"note_update\",\n \"uuid\": \"8a38f9c5-2cd0-4da5-87c1-26d617b354e0\",\n \"args\": {\n \"id\": \"6X7gfQHG59V8CJJV\",\n \"content\": \"Updated Note1\"\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"8a38f9c5-2cd0-4da5-87c1-26d617b354e0\": \"ok\"},\n ...\n}\n```\n\n#### Command arguments\n\n| Argument | Required | Description |\n|--------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | Yes | The ID of the note. |\n| content _String_ | Yes | The content of the note. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the [Text Formatting article](https://www.todoist.com/help/articles/format-text-in-a-todoist-task-e5dHw9) in the Help Center. |\n| file_attachment _Object_ | No | A file attached to the note (see the [File Attachments](#tag/Sync/Comments/File-Attachments) section for details, and learn how to upload a file in the [Uploads section](#tag/Uploads)). |\n\n### Delete a task comment\n\n> Example delete comment request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"note_delete\",\n \"uuid\": \"8d666fda-73c3-4677-8b04-5d223632c24f\",\n \"args\": {\"id\": \"6X7hH7Gpwr3w7jX9\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{ ...\n \"sync_status\": {\"8d666fda-73c3-4677-8b04-5d223632c24f\": \"ok\"},\n ...\n}\n```\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|---------------------|\n| id _String_ | Yes | The ID of the note. |\n\n## Project Comments\n\n> An example project comment:\n\n```\n{\n \"content\": \"Hello 2\",\n \"id\": \"6X7hH9GWrqWhF69Q\",\n \"is_deleted\": false,\n \"posted_at\": \"2018-08-14T10:56:50.000000Z\",\n \"posted_uid\": \"2671355\",\n \"project_id\": \"6Jf8VQXxpwv56VQ7\",\n \"reactions\": null,\n \"uids_to_notify\": [\"2671362\"],\n \"reactions\": { \"\u2764\ufe0f\": [\"2671362\"], \"\ud83d\udc4d\": [\"2671362\", \"2671366\"] },\n \"file_attachment\": {\n \"file_type\": \"text/plain\",\n \"file_name\": \"File1.txt\",\n \"file_size\": 1234,\n \"file_url\": \"https://example.com/File1.txt\",\n \"upload_state\": \"completed\"\n }\n}\n```\n\n_Availability of comments functionality is dependent on the current user plan.\nThis value is indicated by the `comments` property of the\n[user plan limits](#tag/Sync/User/User-plan-limits) object._\n\n#### Properties\n\n| Property | Description |\n|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | The ID of the note. |\n| posted_uid _Integer_ | The ID of the user that posted the note. |\n| project_id _String_ | The project which the note is part of. |\n| content _String_ | The content of the note. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the [Text Formatting article](https://www.todoist.com/help/articles/format-text-in-a-todoist-task-e5dHw9) in the Help Center. |\n| file_attachment _Object_ | A file attached to the note (see the [File Attachments](#tag/Sync/Comments/File-Attachments) section for details). |\n| uids_to_notify _Array of String_ | A list of user IDs to notify. |\n| is_deleted _Boolean_ | Whether the note is marked as deleted (a `true` or `false` value). |\n| posted_at _String_ | The date when the note was posted. |\n| reactions _Object_ | List of emoji reactions and corresponding user IDs. |\n\n### Add a project comment\n\n> Example add comment request:\n\n```shell\ncurl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"note_add\",\n \"temp_id\": \"59fe4461-287b-4b00-bacc-ee771137a732\",\n \"uuid\": \"e1005f08-acd6-4172-bab1-4338f8616e49\",\n \"args\": {\n \"project_id\": \"6Jf8VQXxpwv56VQ7\",\n \"content\": \"Note1\"\n }\n }]'\n\n# or adding a note with a file attached:\n\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"note_add\",\n \"temp_id\": \"6149e689-1a54-48d6-a8c2-0ee5425554a9\",\n \"uuid\": \"554a65e9-56d9-478e-b35b-520c419e37d9\",\n \"args\": {\n \"project_id\": \"6Jf8VQXxpwv56VQ7\",\n \"content\": \"Note1\",\n \"file_attachment\": {\n \"file_type\": \"image\\/gif\",\n \"file_name\": \"image.gif\",\n \"image\": \"https:\\/\\/domain\\/image.gif\",\n \"file_url\": \"https:\\/\\/domain\\/image.gif\",\n \"image_width\":90,\n \"image_height\":76,\n \"file_size\":7962\n }\n }\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"e1005f08-acd6-4172-bab1-4338f8616e49\": \"ok\"},\n \"temp_id_mapping\": {\"59fe4461-287b-4b00-bacc-ee771137a732\": \"6X7hH9GWrqWhF69Q\"},\n ...\n}\n```\n\n| Argument | Required | Description |\n|--------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| project_id _String_ | Yes | The project which the note is part of. |\n| content _String_ | Yes | The content of the note. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the [Text Formatting article](https://www.todoist.com/help/articles/format-text-in-a-todoist-task-e5dHw9) in the Help Center. |\n| file_attachment _Object_ | No | A file attached to the note (see the [File Attachments](#tag/Sync/Comments/File-Attachments) section for details, and learn how to upload a file in the [Uploads section](#tag/Uploads)). |\n\n### Update a project comment\n\n> Example update comment request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"note_update\",\n \"uuid\": \"8a38f9c5-2cd0-4da5-87c1-26d617b354e0\",\n \"args\": {\"id\": \"6X7hH9GWrqWhF69Q\", \"content\": \"Updated Note 1\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"8a38f9c5-2cd0-4da5-87c1-26d617b354e0\": \"ok\"},\n ...\n}\n```\n\n#### Command arguments\n\n| Argument | Required | Description |\n|--------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id _String_ | Yes | The ID of the note. |\n| content _String_ | Yes | The content of the note. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the [Text Formatting article](https://www.todoist.com/help/articles/format-text-in-a-todoist-task-e5dHw9) in the Help Center. |\n| file_attachment _Object_ | No | A file attached to the note (see the [File Attachments](#tag/Sync/Comments/File-Attachments) section for details, and learn how to upload a file in the [Uploads section](#tag/Uploads)). |\n\n### Delete a project comment\n\n> Example delete comment request:\n\n```shell\n$ curl https://api.todoist.com/api/v1/sync \\\n -H \"Authorization: Bearer 0123456789abcdef0123456789abcdef01234567\" \\\n -d commands='[\n {\n \"type\": \"note_delete\",\n \"uuid\": \"8a38f9c5-2cd0-4da5-87c1-26d617b354e0\",\n \"args\": {\"id\": \"6X7hH9GWrqWhF69Q\"}\n }]'\n```\n\n> Example response:\n\n```shell\n{\n ...\n \"sync_status\": {\"8d666fda-73c3-4677-8b04-5d223632c24f\": \"ok\"},\n ...\n}\n```\n\n#### Command arguments\n\n| Argument | Required | Description |\n|-------------|----------|---------------------|\n| id _String_ | Yes | The ID of the note. |\n\n## File Attachments\n\nA file attachment is represented as a JSON object. The file attachment may point\nto a document previously uploaded by the `uploads/add` API call, or by any\nexternal resource.\n\n#### Base file properties\n\n| Attribute | Description |\n|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| file_name _String_ | The name of the file. |\n| file_size _Integer_ | The size of the file in bytes. |\n| file_type _String_ | MIME type (for example `text/plain` or `image/png`). The `file_type` is important for Todoist to render the proper preview for the given attachment. |\n| file_url _String_ | The URL where the file is located. Note that we don't cache the remote content on our servers and stream or expose files directly from third party resources. In particular this means that you should avoid providing links to non-encrypted (plain HTTP) resources, as exposing this files in Todoist may issue a browser warning. |\n| upload_state _String_ | Upload completion state (for example `pending` or `completed`). |\n\n#### Image file properties\n\nIf you upload an image, you may provide thumbnail paths to ensure Todoist\nhandles them appropriately. Valid thumbnail information is a JSON array with\nURL, width in pixels, height in pixels. Ex.:\n[\"https://example.com/img.jpg\",400,300]. \"Canonical\" thumbnails (ones we create\nby `uploads/add` API call) have the following sizes: `96x96`, `288x288`,\n`528x528`.\n\n| Attribute | Description |\n|-------------|---------------------------------------------------------------------------------------------|\n| tn_l _List_ | Large thumbnail (a list that contains the URL, the width and the height of the thumbnail). |\n| tn_m _List_ | Medium thumbnail (a list that contains the URL, the width and the height of the thumbnail). |\n| tn_s _List_ | Small thumbnail (a list that contains the URL, the width and the height of the thumbnail). |\n\n#### Audio file properties\n\nIf you upload an audio file, you may provide an extra attribute `file_duration`\n(duration of the audio file in seconds, which takes an integer value). In the\nweb interface the file is rendered with a `