# Table of Contents
- [Todoist API](#todoist-api)
---
# Todoist API
* Developing with Todoist
* Our API
* Our SDKs
* Pagination
* Integrations
* Authorization
* OAuth
* Cross Origin Resource Sharing
* postMigrate Personal Token
* delRevoke Access Token Api
* Sync
* Overview
* Read resources
* Write resources
* Command UUID
* Temporary resource ID
* Response / Error
* Response status codes
* Batching commands
* Incremental sync
* Workspace
* Add a workspace
* Update a workspace
* Leave a workspace
* Delete a workspace
* Workspace users
* Change user role
* Delete workspace user
* Invite Users to a Workspace
* View Options
* Set a view option
* Delete view option
* User
* Update user's properties
* Update karma goals
* User plan limits
* User settings
* Sharing
* Collaborators
* Collaborator states
* Share a project
* Delete a collaborator
* Accept an invitation
* Reject an invitation
* Delete an invitation
* Sections
* Add a section
* Update a section
* Move a section
* Reorder sections
* Delete a section
* Archive a section
* Unarchive a section
* Reminders
* Add a reminder
* Update a reminder
* Delete a reminder
* Locations
* Projects
* Add a project
* Update a project
* Move a project
* Move a Project to a Workspace
* Move a Project out of a Workspace
* Leave a project
* Delete a project
* Archive a project
* Unarchive a project
* Reorder projects
* Comments
* Task comments
* Project Comments
* File Attachments
* Live notifications
* Set last known
* Mark as read
* Mark all as read
* Mark as unread
* Labels
* Add a personal label
* Update a personal label
* Delete a personal label
* Rename a shared label
* Delete shared label occurrences
* Update multiple label orders
* Tasks
* Add a task
* Update a task
* Move a task
* Reorder tasks
* Delete tasks
* Complete task
* Uncomplete item
* Complete a recurring task
* Close task
* Update day orders
* Filters
* Add a filter
* Update a filter
* Delete a filter
* Update multiple filter orders
* Ids
* getId Mappings
* Workspace
* postDelete Invitation
* getAll Invitations
* putAccept Invitation
* putReject Invitation
* getArchived Projects
* getActive Projects
* getPlan Details
* getInvitations
* getGet Workspaces Users
* postJoin
* postUpdate Logo
* Projects
* getGet Archived
* postCreate Project
* getGet Projects
* getGet Project Collaborators
* postUnarchive Project
* postArchive Project
* postJoin
* getGet Project
* postUpdate Project
* delDelete Project
* Colors
* Comments
* postCreate Comment
* getGet Comments
* getGet Comment
* postUpdate Comment
* delDelete Comment
* Templates
* postImport Into Project From Template Id
* postImport Into Project From File
* postCreate Project From File
* getExport As File
* getExport As Url
* Sections
* postCreate Section
* getGet Sections
* getGet Section
* postUpdate Section
* delDelete Section
* Tasks
* postCreate Task
* getGet Tasks
* getTasks Completed By Completion Date
* getTasks Completed By Due Date
* getGet Tasks By Filter
* postQuick Add
* postReopen Task
* postClose Task
* postMove Task
* getGet Task
* postUpdate Task
* delDelete Task
* Labels
* getShared Labels
* getGet Labels
* postCreate Label
* postShared Labels Remove
* postShared Labels Rename
* delDelete Label
* getGet Label
* postUpdate Label
* Uploads
* delDelete Upload
* postUpload File
* Filters
* Reminders
* Due dates
* Full-day dates
* Floating due dates with time
* Due dates with time and fixed timezone
* Create or update due dates
* Deadlines
* Example deadline object
* Create or update deadlines
* User
* getUser Info
* getGet Productivity Stats
* putUpdate Notification Setting
* Activity
* getGet Activity Logs
* Backups
* getDownload Backup
* getGet Backups
* Emails
* delEmail Disable
* putEmail Get Or Create
* Webhooks
* Configuration
* Request Format
* Request limits
* Url schemes
* Mobile app URL schemes
* Views
* Projects
* Desktop app URL schemes
* Migrating from v9
* General changes
* IDs
* Lowercase endpoints
* Pagination
* Previous REST API endpoints error responses
* Object renames
* URL renames
* Deprecated endpoints
* /sync endpoint changes
* Sections
* User
* Other endpoints
* Workspace projects
* /tasks
* /projects
* /sections
* /comments
* Webhooks
[API docs by Redocly](https://redocly.com/redoc/)
Todoist API (1)
===============
Download OpenAPI specification:[Download](blob:https://developer.todoist.com/f2223161-abf2-4361-8c1a-f62359e64f6a)
[](https://developer.todoist.com/api/v1#section/Developing-with-Todoist)
Developing with Todoist
------------------------------------------------------------------------------------------------
Thanks for your interest in developing apps with Todoist. In this section we will provide an overview of the API we offer and cover some common topics for application development using them.
You can use our API for free, but depending on your Todoist account plan (or that of the authenticated user), some features may be restricted.
Please consider subscribing to the [Todoist API mailing list](https://groups.google.com/a/doist.com/g/todoist-api)
to get important updates.
[](https://developer.todoist.com/api/v1#section/Developing-with-Todoist/Our-API)
Our API
----------------------------------------------------------------------------------------
Our API uses an approach that should be familiar to anyone with experience calling [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer)
APIs.
We also have a special endpoint called `/sync`, which is used by our first-party clients to keep the data updated locally without having to make many separate requests to the API. Anyone can use it, and some actions will only be available via `/sync`. The format is unconventional compared to current API standards, but it is our main driver for first-party apps.
[](https://developer.todoist.com/api/v1#section/Developing-with-Todoist/Our-SDKs)
Our SDKs
------------------------------------------------------------------------------------------
Our Python and JavaScript SDKs streamline working with the Todoist API, and can be installed from the main package registries for each ecosystem.
For instructions, examples, and reference documentation, visit their pages:
* [Todoist Python SDK](https://doist.github.io/todoist-api-python/)
* [Todoist TypeScript SDK](https://doist.github.io/todoist-api-typescript/)
[](https://developer.todoist.com/api/v1#section/Developing-with-Todoist/Pagination)
Pagination
----------------------------------------------------------------------------------------------
Paginated endpoints are marked by having the `next_cursor` attribute in the response.
When a response comes back with `next_cursor: null`, it means the endpoint is paginated but there are no more pages to request data from.
If the cursor is `non-null`, there are more objects to return, and a new request is necessary to get the next page.
The `next_cursor` contains an _opaque_ string that shouldn't be modified in any way. It should be sent **as-is** in the `cursor` parameter along with the same parameters used in the previous request.
[](https://developer.todoist.com/api/v1#section/Developing-with-Todoist/Integrations)
Integrations
--------------------------------------------------------------------------------------------------
Integrations can be created and updated [here](https://app.todoist.com/app/settings/integrations/app-management)
.
Once done, they can also be submitted for evaluation and inclusion in [our official integrations list](https://www.todoist.com/integrations)
. This not only serves as an opportunity to market your integration to our audience, but will also serve as a way to help users get set up and familiar with your app quickly.
To get your integration evaluated, please submit it via [this page](https://doist.typeform.com/to/Vvq7kNcl?typeform-source=todoist.com/api/v1/docs)
.
Lost? Reach out to us at [submissions@doist.com](mailto:submissions@doist.com)
anytime.
[](https://developer.todoist.com/api/v1#tag/Authorization)
Authorization
------------------------------------------------------------------------
> An authenticated request with authorization header:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d sync_token='*' \
-d resource_types='["all"]'
In order to make authorized calls to the Sync API, your application must provide an [authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)
with the appropriate `Bearer $token`. For working through the examples, you can obtain your personal API token from the [integrations settings](https://todoist.com/prefs/integrations)
for your account.
To authenticate other users, your application will need to obtain a token from them using the OAuth protocol. For information on how to obtain a token from our service using OAuth, please see the [authorization guide](https://developer.todoist.com/guides/#authorization)
.
For the sake of simplicity the token is not listed on every parameter table but please note that the **token parameter is required for every resource**.
[](https://developer.todoist.com/api/v1#tag/Authorization/OAuth)
OAuth
----------------------------------------------------------------------
OAuth is also available for token generation. It's especially useful for external applications to obtain a user authorized API token via the OAuth2 protocol. Before getting started, developers need to create their applications in the [App Management Console](https://app.todoist.com/app/settings/integrations/app-management)
and configure a valid OAuth2 redirect URL. A registered Todoist application is assigned a unique `Client ID` and `Client Secret` which are needed for the OAuth2 flow.
This procedure is comprised of 3 steps.
### Step 1: Authorization request
> An example of the URL to the authorization endpoint:
https://todoist.com/oauth/authorize?client_id=0123456789abcdef&scope=data:read,data:delete&state=secretstring
Redirect users to the authorization URL at the endpoint `https://todoist.com/oauth/authorize`, with the specified request parameters.
#### Required parameters
| Name | Description |
| --- | --- |
| client\_id | The unique Client ID of the Todoist application that you registered. |
| 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. |
| state | A unique and unguessable string. It is used to protect you against cross-site request forgery attacks. |
#### Permission scopes
| Name | Description |
| --- | --- |
| task:add | Grants permission to add new tasks (the application cannot read or modify any existing data). |
| data:read | Grants read-only access to application data, including tasks, projects, labels, and filters. |
| 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. |
| data:delete | Grants permission to delete application data, including tasks, labels, and filters. |
| project:delete | Grants permission to delete projects. |
| backups:read | Grants permission to list backups bypassing MFA requirements. |
#### Potential errors
| Error | Description |
| --- | --- |
| 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`. |
| 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. |
| 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`. |
| 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`. |
### Step 2: Redirection to your application site
When the user grants your authorization request, the user will be redirected to the redirect URL configured for your application. The redirect request will come with two query parameters attached: `code` and `state`.
The `code` parameter contains the authorization code that you will use to exchange for an access token. The `state` parameter should match the `state` parameter that you supplied in the previous step. If the `state` is unmatched, your request has been compromised by other parties, and the process should be aborted.
### Step 3: Token exchange
> An example of exchanging the token:
$ curl "https://todoist.com/oauth/access_token" \
-d "client_id=0123456789abcdef" \
-d "client_secret=secret" \
-d "code=abcdef" \
-d "redirect_uri=https://example.com"
> On success, Todoist returns HTTP 200 with token in JSON object format:
{
"access_token": "0123456789abcdef0123456789abcdef01234567",
"token_type": "Bearer"
}
Once you have the authorization `code`, you can exchange it for the access token by sending a `POST` request to the following endpoint:
`https://todoist.com/oauth/access_token`.
#### Required parameters
| Name | Description |
| --- | --- |
| client\_id | The Client ID of the Todoist application that you registered. |
| client\_secret | The Client Secret of the Todoist application that you registered. |
| code | The code that was sent in the query string to the redirect URL in the previous step. |
#### Potential errors
| Error | Description |
| --- | --- |
| 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"}` |
| Incorrect Client Credentials Error | Occurs when the `client_id` or `client_secret` parameters are incorrect: `{"error": "incorrect_application_credentials"}` |
[](https://developer.todoist.com/api/v1#tag/Authorization/Cross-Origin-Resource-Sharing)
Cross Origin Resource Sharing
----------------------------------------------------------------------------------------------------------------------
> CORS headers example:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-H "Origin: http://example.com"
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
All API endpoints not related to the initial OAuth2 flow support Cross Origin Resource Sharing (CORS) for requests from any origin. The header `Access-Control-Allow-Origin: *` is set for successfully authenticated requests.
[](https://developer.todoist.com/api/v1#tag/Authorization/operation/migrate_personal_token_api_v1_access_tokens_migrate_personal_token_post)
Migrate Personal Token
-------------------------------------------------------------------------------------------------------------------------------------------------------------------
Tokens obtained via the old email/password authentication method can be migrated to the new OAuth access token. Migrating your users' personal tokens will allow users to see your app in their Todoist Settings page and give them the ability to manage their app authorization.
A successful response has `200 OK` status and `application/json` Content-Type.
##### Request Body schema: application/json
required
| | |
| --- | --- |
| client\_id
required | string (Client Id)
The unique Client ID of the Todoist application that you registered |
| client\_secret
required | string (Client Secret)
The unique Client Secret of the Todoist application that you registered |
| personal\_token
required | string (Personal Token)
Token obtained from the email/password authentication |
| scope
required | string (Scope)
Scopes of the OAuth token. Please refer to the [Authorization](https://developer.todoist.com/api/v1#tag/Authorization) guide for the detailed list of available scopes. |
### Responses
**200**
Successful Response
**400**
Bad Request
**401**
Unauthorized
**403**
Forbidden
**404**
Not Found
post/api/v1/access\_tokens/migrate\_personal\_token
https://api.todoist.com/api/v1/access\_tokens/migrate\_personal\_token
### Request samples
* Payload
Content type
application/json
Copy
`{ * "client_id": "string", * "client_secret": "string", * "personal_token": "string", * "scope": "string" }`
### Response samples
* 200
Content type
application/json
Copy
`{ * "access_token": "0123456789abcdef0123456789abcdef01234567", * "token_type": "Bearer" }`
[](https://developer.todoist.com/api/v1#tag/Authorization/operation/revoke_access_token_api_api_v1_access_tokens_delete)
Revoke Access Token Api
------------------------------------------------------------------------------------------------------------------------------------------------
Revoke the access tokens obtained via OAuth
##### query Parameters
| | |
| --- | --- |
| client\_id
required | string (Client Id)
The unique Client ID of the Todoist application that you registered |
| client\_secret
required | string (Client Secret)
The unique Client Secret of the Todoist application that you registered |
| access\_token
required | string (Access Token)
Access token obtained from OAuth authentication |
### Responses
**200**
Successful Response
**400**
Bad Request
**401**
Unauthorized
**403**
Forbidden
**404**
Not Found
delete/api/v1/access\_tokens
https://api.todoist.com/api/v1/access\_tokens
### Response samples
* 200
Content type
application/json
Copy
`null`
[](https://developer.todoist.com/api/v1#tag/Sync)
Sync
------------------------------------------------------
The Todoist Sync endpoint is specially designed for efficient data sync between clients (e.g. our mobile apps) and Todoist.
Sync requests should be made in HTTP POST (`application/x-www-form-urlencoded`). Sync responses, including errors, will be returned in JSON.
The Sync endpoint supports the following features:
* [Batching](https://developer.todoist.com/api/v1#tag/Sync/Overview/Batching-commands)
: reading and writing of multiple resources can be done in a single HTTP request. Batch requests help clients reduce the number of network calls needed to sync resources.
* [Incremental sync](https://developer.todoist.com/api/v1#tag/Sync/Overview/Incremental-sync)
: You only retrieve data that is updated since the last time you performed a sync request.
_Refer to [Request Limits](https://developer.todoist.com/api/v1#tag/Request-limits)
to learn more about the number of requests/commands you have for the Sync API_
[](https://developer.todoist.com/api/v1#tag/Sync/Overview)
Overview
-------------------------------------------------------------------
[](https://developer.todoist.com/api/v1#tag/Sync/Overview/Read-resources)
Read resources
----------------------------------------------------------------------------------------
> Example read resources request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d sync_token='*' \
-d resource_types='["all"]'
> Example response:
{
"completed_info": [ ... ],
"collaborators": [ ... ],
"collaborator_states": [ ... ],
"day_orders": { ... },
"filters": [ ... ],
"full_sync": true,
"items": [ ... ],
"labels": [ ... ],
"live_notifications": [ ... ],
"live_notifications_last_read_id": "0",
"locations": [ ... ],
"notes": [ ... ],
"project_notes": [ ... ],
"projects": [ ... ],
"reminders": [ ... ],
"sections": [ ... ],
"stats": { ... },
"settings_notifications": { ... },
"sync_token": "TnYUZEpuzf2FMA9qzyY3j4xky6dXiYejmSO85S5paZ_a9y1FI85mBbIWZGpW",
"temp_id_mapping": { ... },
"user": { ... },
"user_plan_limits": { ... },
"user_settings": { ... },
"workspace_users": { ... }
}
To retrieve your user resources, make a Sync API request with the following parameters:
#### Parameters
| Parameter | Required | Description |
| --- | --- | --- |
| 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. |
| 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`. 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` |
In order to fetch both types of reminders you must include both resource types in your request, for example: `resource_types=["reminders", "reminders_location"]` .
The `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.
#### Response
When the request succeeds, an HTTP 200 response will be returned with a JSON object containing the requested resources and a new `sync_token`.
| Field | Description |
| --- | --- |
| sync\_token | A new synchronization token. Used by the client in the next sync request to perform an incremental sync. |
| full\_sync | Whether the response contains all data (a full synchronization) or just the incremental updates since the last sync. |
| 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](https://developer.todoist.com/api/v1#tag/Sync/Overview/Incremental-sync) to get up-to-date data. |
| user | A user object. |
| projects | An array of [project](https://developer.todoist.com/api/v1#tag/Sync/Projects) objects. |
| items | An array of [item](https://developer.todoist.com/api/v1#tag/Sync/Items) objects. |
| notes | An array of [task comments](https://developer.todoist.com/api/v1#tag/Sync/Comments/Task-Comments) objects. |
| project\_notes | An array of [project comments](https://developer.todoist.com/api/v1#tag/Sync/Comments/Project-Comments) objects. |
| sections | An array of [section](https://developer.todoist.com/api/v1#tag/Sync/Sections) objects. |
| labels | An array of [personal label](https://developer.todoist.com/api/v1#tag/Sync/Labels) objects. |
| filters | An array of [filter](https://developer.todoist.com/api/v1#tag/Sync/Filters) objects. |
| day\_orders | A JSON object specifying the order of items in daily agenda. |
| reminders | An array of [reminder](https://developer.todoist.com/api/v1#tag/Sync/Reminders) objects. |
| collaborators | A JSON object containing all [collaborators](https://developer.todoist.com/api/v1#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. |
| collaborators\_states | An array specifying the state of each collaborator in each project. The state can be invited, active, inactive, deleted. |
| 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. |
| live\_notifications | An array of `live_notification` objects. |
| live\_notifications\_last\_read | What is the last live notification the user has seen? This is used to implement unread notifications. |
| user\_settings | A JSON object containing [user settings](https://developer.todoist.com/api/v1#tag/Sync/User/User-settings) . |
| user\_plan\_limits | A JSON object containing [user plan limits](https://developer.todoist.com/api/v1#tag/Sync/User/User-plan-limits) . |
| workspaces | A JSON object containing [workspace](https://developer.todoist.com/api/v1#tag/Sync/Workspace) objects. |
| workspace\_users | A JSON object containing [workspace\_user](https://developer.todoist.com/api/v1#tag/Sync/Workspace-users) objects. Only in incremental sync. |
[](https://developer.todoist.com/api/v1#tag/Sync/Overview/Write-resources)
Write resources
------------------------------------------------------------------------------------------
> Example create project request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "project_add",\
"temp_id": "381e601f-0ef3-4ed6-bf95-58f896d1a314",\
"uuid": "ed1ce597-e4c7-4a88-ba48-e048d827c067",\
"args": {\
"name": "Shopping List",\
"color": "berry_red"\
}\
}]'
> Example response:
{
"sync_token": "cdTUEvJoChiaMysD7vJ14UnhN-FRdP-IS3aisOUpl3aGlIQA9qosBgvMmhbn",
"sync_status": {"ed1ce597-e4c7-4a88-ba48-e048d827c067": "ok"},
"temp_id_mapping": {"381e601f-0ef3-4ed6-bf95-58f896d1a314": "6HWcc9PJCvPjCxC9"}
}
To write to your user's Todoist resources, make a Sync API request with the following parameters:
#### Parameters
| Parameter | Required | Description |
| --- | --- | --- |
| commands _JSON_ | Yes | A JSON array of Command objects. Each command will be processed in the specified order. |
#### Command object
| Field | Description |
| --- | --- |
| type _String_ | The type of the command. |
| args _Object_ | The parameters of the command. |
| uuid _String_ | Command UUID. More details about this below. |
| 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. |
[](https://developer.todoist.com/api/v1#tag/Sync/Overview/Command-UUID)
Command UUID
------------------------------------------------------------------------------------
Clients should generate a unique string ID for each command and specify it in the `uuid` field. The Command UUID will be used for two purposes:
1. Command result mapping: Each command's result will be stored in the `sync_status` field of the response JSON object. The `sync_status` object has its key mapped to a command's `uuid` and its value containing the result of a command.
2. Command idempotency: Todoist will not execute a command that has same UUID as a previously executed command. This will allow clients to safely retry each command without accidentally performing the action twice.
[](https://developer.todoist.com/api/v1#tag/Sync/Overview/Temporary-resource-ID)
Temporary resource ID
------------------------------------------------------------------------------------------------------
> An example that shows how temporary IDs can be used and referenced:
[\
{\
"type": "project_add",\
"temp_id": "c7beb07f-b226-4eb1-bf63-30d782b07b1a",\
"args": {\
"name": "Shopping List"\
},\
"uuid": "ac417051-1cdc-4dc3-b4f8-14526d5bfd16"\
},\
{\
"type": "item_add",\
"temp_id": "43f7ed23-a038-46b5-b2c9-4abda9097ffa",\
"args": {\
"content": "Buy Milk",\
"project_id": "c7beb07f-b226-4eb1-bf63-30d782b07b1a"\
},\
"uuid": "849fff4e-8551-4abb-bd2a-838d092775d7"\
}\
]
> You can see that the `project_add` command specified a `temp_id` property (`c7beb07f-b226-4eb1-bf63-30d782b07b1a`) as placeholder of the actual `project_id`. The `item_add` command can reference to this temporary project ID. The API will automatically resolve these IDs.
Some commands depend on the result of previous command. For instance, you have a command sequence: `"project_add"` and `"item_add"` which first creates a project and then add a new task to the newly created project. In order to run the later `item_add` command, we need to obtain the project ID returned from the previous command. Therefore, the normal approach would be to run these two commands in two separate HTTP requests.
The temporary resource ID feature allows you to run two or more dependent commands in a single HTTP request. For commands that are related to creation of resources (i.e. `item_add`, `project_add`), you can specify an extra `temp_id` as a placeholder for the actual ID of the resource. The other commands in the same sequence could directly refer to `temp_id` if needed.
[](https://developer.todoist.com/api/v1#tag/Sync/Overview/Response-Error)
Response / Error
------------------------------------------------------------------------------------------
> An example of a single request sync return value:
{
"sync_status": { "863aca2c-65b4-480a-90ae-af160129abbd": "ok" }
}
> An example of a multiple requests sync return value:
{
"sync_status": {
"32eaa699-e9d7-47ed-91ea-e58d475791f1": "ok",
"bec5b356-3cc1-462a-9887-fe145e3e1ebf": {
"error_code": 15,
"error": "Invalid temporary id"
}
}
}
The result of command executions will be stored in the following response JSON object field:
| Data | Description |
| --- | --- |
| temp\_id\_mapping _Object_ | A dictionary object that maps temporary resource IDs to real resource IDs. |
| 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. |
The status result of each command execution is in the `sync_status` dictionary object. The key is a command `uuid` and the value will be the result status of the command execution.
There are two possible values for each command status:
* An "ok" string which signals success of the command
* An error object containing error information of a command.
Please see the adjacent code examples for the possible format of the `sync_status`.
[](https://developer.todoist.com/api/v1#tag/Sync/Overview/Response-status-codes)
Response status codes
------------------------------------------------------------------------------------------------------
The server uses the HTTP status codes to indicate the success or failure of a request. As is customary in web servers, a 2xx code indicates - success, a 4xx code - an error due to incorrect user provided information, and a 5xx code - an internal, possibly temporary, error.
| Status code | Description |
| --- | --- |
| 200 OK | The request was processed successfully. |
| 400 Bad Request | The request was incorrect. |
| 401 Unauthorized | Authentication is required, and has failed, or has not yet been provided. |
| 403 Forbidden | The request was valid, but for something that is forbidden. |
| 404 Not Found | The requested resource could not be found. |
| 429 Too Many Requests | The user has sent too many requests in a given amount of time. |
| 500 Internal Server Error | The request failed due to a server error. |
| 503 Service Unavailable | The server is currently unable to handle the request. |
[](https://developer.todoist.com/api/v1#tag/Sync/Overview/Batching-commands)
Batching commands
----------------------------------------------------------------------------------------------
> Example of batching multiple commands:
curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "project_add",\
"temp_id": "0a57a3db-2ff1-4d2d-adf6-12490c13c712",\
"uuid": "2c0f6e03-c372-46ba-8e85-d94af56abcf3",\
"args": { "name": "Shopping List" }\
},\
{\
"type": "item_add",\
"temp_id": "ef3d840e-84c9-4433-9a32-86ae9a1e7d42",\
"uuid": "49ede211-12f3-42e9-8345-4c0d2b29c08d",\
"args": { "content": "Buy Milk", "project_id": "0a57a3db-2ff1-4d2d-adf6-12490c13c712" }\
},\
{\
"type": "item_add",\
"temp_id": "8a23c8cb-1d76-469d-a2c0-80a28b3ea6f6",\
"uuid": "46619250-ae02-4ab0-bd31-3c9ab0307e53",\
"args": { "content": "Buy Coffee", "project_id": "0a57a3db-2ff1-4d2d-adf6-12490c13c712" }\
},\
{\
"type": "item_add",\
"temp_id": "bf087eaf-aea9-4cb1-ab57-85188a2d428f",\
"uuid": "d0a1666b-d615-4250-aac5-65c7ea89091a",\
"args": { "content": "Buy Sugar", "project_id": "0a57a3db-2ff1-4d2d-adf6-12490c13c712" }\
}]'
> Example response:
{
"sync_status": {
"2c0f6e03-c372-46ba-8e85-d94af56abcf3": "ok",
"49ede211-12f3-42e9-8345-4c0d2b29c08d": "ok",
"d0a1666b-d615-4250-aac5-65c7ea89091a": "ok",
"46619250-ae02-4ab0-bd31-3c9ab0307e53": "ok"
},
"temp_id_mapping": {
"8a23c8cb-1d76-469d-a2c0-80a28b3ea6f6": "6X6HrfVQvQq5WCXH",
"0a57a3db-2ff1-4d2d-adf6-12490c13c712": "6X6HrhXfQ9857XVG",
"bf087eaf-aea9-4cb1-ab57-85188a2d428f": "6X6HrjHFgc3jQM8H",
"ef3d840e-84c9-4433-9a32-86ae9a1e7d42": "6X6HrmjgW88crvMC"
},
"full_sync": true,
"sync_token": "GSg4kDBAKWU7TZA_a-gcuSpxmO1lXT5bhLqUGd1F-AH69_qKEdkN_fJoBq3c"
}
When working with the Sync API, changes can be **batched** into one commit. In our example, we're batching the creation of a 'Shopping List' project with three different items.
As we've committed the changes all at once, we’re significantly reducing the amount of network calls that have to be made, as well as ensuring we’re not running into any rate limiting issues.
[](https://developer.todoist.com/api/v1#tag/Sync/Overview/Incremental-sync)
Incremental sync
--------------------------------------------------------------------------------------------
The Sync API allows clients to retrieve only updated resources, and this is done by using the `sync_token` in your Sync API request.
On your initial sync request, specify `sync_token=*` in your request, and all the user's active resource data will be returned. The server will also return a new `sync_token` in the Sync API response.
In your subsequent Sync request, use the `sync_token` that you received from your previous sync response, and the Todoist API server will return only the updated resource data.
### Full sync data delay
For big accounts, the data in the initial sync may be returned with some delay, and newer objects and updates may seem to be missing. The `full_sync_date_utc` attribute should be the same or very close to the current UTC date. If you notice a bigger time difference, it's recommended to do an incremental sync using the `sync_token` included in that initial sync response to get the latest updates.
[](https://developer.todoist.com/api/v1#tag/Sync/Workspace)
Workspace
---------------------------------------------------------------------
> An example workspace object:
{
"created_at": "2024-10-19T10:00:00.123456Z",
"creator_id": "123",
"current_active_projects": 5,
"current_member_count": 2,
"current_template_count": 0,
"description": "Workspace description",
"domain_discovery": false,
"domain_name": null,
"id": "1234",
"invite_code": "ptoh4SICUu4",
"is_collapsed": false,
"is_deleted": false,
"is_guest_allowed": true,
"is_link_sharing_enabled": true,
"is_trial_pending": false,
"limits": {
"current": {
"admin_tools": false,
"advanced_permissions": false,
"automatic_backups": false,
"calendar_layout": false,
"durations": false,
"max_collaborators": 250,
"max_folders_per_workspace": 1000,
"max_guests_per_workspace": 1000,
"max_projects": 5,
"max_workspace_templates": 100,
"max_workspace_users": 1000,
"max_workspaces": 50,
"plan_name": "teams_workspaces_starter",
"reminders": false,
"reminders_at_due": true,
"security_controls": false,
"team_activity": true,
"team_activity_plus": false,
"upload_limit_mb": 5
},
"next": {
"admin_tools": true,
"advanced_permissions": true,
"automatic_backups": true,
"max_collaborators": 250,
"max_guests_per_workspace": 1000,
"max_projects": 1000,
"max_workspace_users": 1000,
"plan_name": "teams_workspaces_business",
"reminders": true,
"security_controls": true,
"upload_limit_mb": 100
}
},
"logo_big": "https://...",
"logo_medium": "https://...",
"logo_s640": "https://...",
"logo_small": "https://...",
"member_count_by_type": {
"admin_count": 2,
"guest_count": 0,
"member_count": 0
},
"name": "Workspace name",
"pending_invitations": [\
"pending@doist.com"\
],
"pending_invites_by_type": {
"admin_count": 1,
"guest_count": 0,
"member_count": 0
},
"plan": "STARTER",
"properties": {},
"restrict_email_domains": false,
"role": "MEMBER"
}
#### Properties
| Property | Description |
| --- | --- |
| id _String_ | The ID of the workspace. |
| name _String_ | The name of the workspace (up to 255 characters). |
| description _String_ | The description of the workspace. |
| plan _String_ | The subscription plan this workspace is currently on, either `STARTER` or `BUSINESS`. |
| 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._ |
| 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. |
| 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._ |
| 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. |
| logo\_big _String_ | The URL for the big workspace logo image. |
| logo\_medium _String_ | The URL for the medium workspace logo image. |
| logo\_small _String_ | The URL for the small workspace logo image. |
| logo\_s640 _String_ | The URL for the square 640px workspace logo image. |
| limits _Object_ | A list of restrictions for the workspace based on it's current plan, denoting what features are enabled and limits are imposed. |
| creator\_id _String_ | The ID of the user who created the workspace. |
| created\_at _String_ | The date when the workspace was created. |
| is\_deleted _Boolean_ | True if it is a deleted workspace. |
| is\_collapsed _Boolean_ | True if the workspace is collapsed. This is a user-specific attribute and will reflect the requesting user’s `is_collapsed` state. |
| domain\_name _String_ | The domain name of the workspace. |
| domain\_discovery _Boolean_ | True if users with e-mail addresses in the workspace domain can join the workspace without an invitation. |
| restrict\_email\_domains _Boolean_ | True if only users with e-mail addresses in the workspace domain can join the workspace. |
[](https://developer.todoist.com/api/v1#tag/Sync/Workspace/Add-a-workspace)
Add a workspace
-------------------------------------------------------------------------------------------
> Example add workspace request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "workspace_add",\
"temp_id": "4ff1e388-5ca6-453a-b0e8-662ebf373b6b",\
"uuid": "32774db9-a1da-4550-8d9d-910372124fa4",\
"args": {\
"name": "Fellowship Workspace"\
}\
}]'
> Example response:
{
...
"sync_status": {"32774db9-a1da-4550-8d9d-910372124fa4": "ok"},
"temp_id_mapping": {"4ff1e388-5ca6-453a-b0e8-662ebf373b6b": "6X6WMG4rmqx6FXQ9"},
...
}
Add a new workspace.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| name _String_ | Yes | The name of the workspace. |
| description _String_ | No | The description of the workspace (up to 1024 characters). |
| is\_link\_sharing\_enabled _Boolean_ | No | Indicates if users are allowed to join the workspace using an invitation link. Default value is True. |
| is\_guest\_allowed _Boolean_ | No | Indicates if users from outside the workspace are allowed to join or be invited to workspace projects. Default value is True. |
| domain\_name _String_ | No | The domain name of the workspace. |
| domain\_discovery _Boolean_ | No | True if users with e-mail addresses in the workspace domain can join the workspace without an invitation. |
| restrict\_email\_domains _Boolean_ | No | True if only users with e-mail addresses in the workspace domain can join the workspace. |
[](https://developer.todoist.com/api/v1#tag/Sync/Workspace/Update-a-workspace)
Update a workspace
-------------------------------------------------------------------------------------------------
> Example update workspace request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "workspace_update",\
"temp_id": "4ff1e388-5ca6-453a-b0e8-662ebf373b6b",\
"uuid": "32774db9-a1da-4550-8d9d-910372124fa4",\
"args": {\
"id": "12345",\
"description": "Where magic happens"\
}\
}]'
> Example response:
{
...
"sync_status": {"32774db9-a1da-4550-8d9d-910372124fa4": "ok"},
"temp_id_mapping": {"4ff1e388-5ca6-453a-b0e8-662ebf373b6b": "6X6WMMqgq2PWxjCX"},
...
}
Update an existing workspace.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | Real or temp ID of the workspace |
| name _String_ | No | The name of the workspace. |
| description _String_ | No | The description of the workspace (up to 1024 characters). |
| is\_collapsed _Boolean_ | No | The collapsed state of the workspace for the current user |
| is\_link\_sharing\_enabled _Boolean_ | No | Indicates if users are allowed to join the workspace using an invitation link. |
| is\_guest\_allowed _Boolean_ | No | Indicates if users from outside the workspace are allowed to join or be invited to workspace projects. Default value is True. |
| invite\_code _String_ | No | Regenerate the invite\_code for the workspace. Any non-empty string value will regenerate a new code, the provided value with this argument is not significant, only an indication to regenerate the code. |
| domain\_name _String_ | No | The domain name of the workspace. |
| domain\_discovery _Boolean_ | No | True if users with e-mail addresses in the workspace domain can join the workspace without an invitation. |
| restrict\_email\_domains _Boolean_ | No | True if only users with e-mail addresses in the workspace domain can join the workspace. |
[](https://developer.todoist.com/api/v1#tag/Sync/Workspace/Leave-a-workspace)
Leave a workspace
-----------------------------------------------------------------------------------------------
> Example leave workspace request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "workspace_leave",\
"temp_id": "4ff1e388-5ca6-453a-b0e8-662ebf373b6b",\
"uuid": "32774db9-a1da-4550-8d9d-910372124fa4",\
"args": {\
"id": "6X6WMMqgq2PWxjCX",\
}\
}]'
> Example response:
{
...
"sync_status": {"32774db9-a1da-4550-8d9d-910372124fa4": "ok"},
...
}
Remove self from a workspace. The user is also removed from any workspace project previously joined.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | Real or temp ID of the workspace |
_All workspace\_users can leave a workspace by themselves._
[](https://developer.todoist.com/api/v1#tag/Sync/Workspace/Delete-a-workspace)
Delete a workspace
-------------------------------------------------------------------------------------------------
> Example delete workspace request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "workspace_delete",\
"temp_id": "4ff1e388-5ca6-453a-b0e8-662ebf373b6b",\
"uuid": "32774db9-a1da-4550-8d9d-910372124fa4",\
"args": {\
"id": "6X6WMRPC43g2gHVx"\
}\
}]'
> Example response:
{
...
"sync_status": {"32774db9-a1da-4550-8d9d-910372124fa4": "ok"},
...
}
Delete an existing workspace.
_This command is only usable by workspace admins. Other users will get a “forbidden” error._
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the workspace |
[](https://developer.todoist.com/api/v1#tag/Sync/Workspace-users)
Workspace users
---------------------------------------------------------------------------------
**`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](https://developer.todoist.com/api/v1#tag/Workspace/operation/get_workspaces_users_api_v1_workspaces_users_get)
, then use incremental sync to update that initial list as needed.
`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 “see” each other in `workspace_users` but not in collaborators.
Guests will not receive `workspace_users` sync events or resources.
> An example workspace\_users object:
{
"user_id": "1855581",
"workspace_id": "424876",
"user_email": "you@example.com",
"full_name": "Example User",
"timezone": "GMT +3:00",
"avatar_big": "https://*.cloudfront.net/*_big.jpg",
"avatar_medium": "https://*.cloudfront.net/*_medium.jpg",
"avatar_s640": "https://*.cloudfront.net/*_s640.jpg",
"avatar_small": "https://*.cloudfront.net/*_small.jpg",
"image_id": "d160009dfd52b991030d55227003450f",
"role": "MEMBER"
"is_deleted": false,
}
#### Properties
| Property | Description |
| --- | --- |
| user\_id _String_ | The user ID. |
| workspace\_id _String_ | The workspace ID for this user. |
| user\_email _String_ | The user email. |
| full\_name _String_ | The full name of the user. |
| timezone _String_ | The timezone of the user. |
| image\_id _String_ | The ID of the user's avatar. |
| 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. |
| avatar\_big _String_ | The link to a 195x195 pixels image of the user's avatar. |
| avatar\_medium _String_ | The link to a 60x60 pixels image of the user's avatar. |
| avatar\_s640 _String_ | The link to a 640x640 pixels image of the user's avatar. |
| avatar\_small _String_ | The link to a 35x35 pixels image of the user's avatar. |
| is\_deleted _Boolean_ | Whether the workspace user is marked as deleted. |
Avatar URLs are only available if the user has an avatar, in other words, when the `image_id` is not `null`.
[](https://developer.todoist.com/api/v1#tag/Sync/Workspace-users/Change-user-role)
Change user role
---------------------------------------------------------------------------------------------------
> Example role change for a workspace user request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "workspace_update_user",\
"temp_id": "4ff1e388-5ca6-453a-b0e8-662ebf373b6b",\
"uuid": "32774db9-a1da-4550-8d9d-910372124fa4",\
"args": {\
"workspace_id": "12345,\
"user_email": "user@acme.com",\
"role": "ADMIN"\
}\
}]'
> Example response:
{
...
"sync_status": {"32774db9-a1da-4550-8d9d-910372124fa4": "ok"},
"temp_id_mapping": {"4ff1e388-5ca6-453a-b0e8-662ebf373b6b": "12345"},
...
}
Change the role of a workspace user.
_Admins or members can not be downgraded to guests._
_This command is only usable by workspace admins. Other users will get a “forbidden” error._
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | Real or temp ID of the workspace |
| user\_email _String_ | Yes | The new member's email |
| role _String_ | Yes | The role to be assigned to the new member. Valid values are `GUEST`, `MEMBER` and `ADMIN`. |
[](https://developer.todoist.com/api/v1#tag/Sync/Workspace-users/Delete-workspace-user)
Delete workspace user
-------------------------------------------------------------------------------------------------------------
> Example delete workspace user request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "workspace_delete_user",\
"temp_id": "4ff1e388-5ca6-453a-b0e8-662ebf373b6b",\
"uuid": "32774db9-a1da-4550-8d9d-910372124fa4",\
"args": {\
"workspace_id": "12345",\
"user_email": "user@acme.com"\
}\
}]'
> Example response:
{
...
"sync_status": {"32774db9-a1da-4550-8d9d-910372124fa4": "ok"},
...
}
Remove a user from a workspace. That user is also removed from any workspace project they joined.
_This command is only usable by workspace admins. Other users will get a “forbidden” error._
_Admins can use this command to remove themselves from a workspace, unless they are the last admin in the workspace. In that case, a “forbidden” error will be returned._
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | Real or temp ID of the workspace |
| user\_email _String_ | Yes | The email of the member to be deleted |
[](https://developer.todoist.com/api/v1#tag/Sync/Workspace-users/Invite-Users-to-a-Workspace)
Invite Users to a Workspace
-------------------------------------------------------------------------------------------------------------------------
> Example request to invite users to a workspace through the Sync API:
$ curl https://api.todoist.com/sync/v10/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "workspace_invite",\
"uuid": "32774db9-a1da-4550-8d9d-910372124fa4",\
"args": {\
"id": "12345",\
"email_list": ["foo@example.com", "bar@example.com"],\
"role": "MEMBER"\
}\
}]
'
> Example response:
{
...
"sync_status": {"32774db9-a1da-4550-8d9d-910372124fa4": "ok"},
...
}
This will create workspace invitations for a list of email addresses. Usable by all workspace members and admins.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | ID of the workspace. |
| email\_list _List of String_ | Yes | A list of emails to be invited to the workspace. |
| role _String_ | No | The role the user will be given if they accept the invite. Possible values are `ADMIN`, `MEMBER`, and `GUEST`. If not provided, the default value according to the plan will be used. For Starter plans, the default is ADMIN and for Business plans, the default is MEMBER. |
[](https://developer.todoist.com/api/v1#tag/Sync/View-Options)
View Options
---------------------------------------------------------------------------
> An example view option object:
{
"view_type": "project",
"object_id": "6Jf8VQXxpwv56VQ7",
"filtered_by": "!assigned",
"grouped_by": "priority",
"sorted_by": "added_date",
"sort_order": "asc",
"show_completed_tasks": false,
"view_mode": "calendar",
"calendar_settings": { "layout": "month" },
"is_deleted": false,
"deadline": "no deadline"
}
#### Properties
| Property | Description |
| --- | --- |
| 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, or `filter` for a filter. |
| object\_id _String_ | The ID of the object referred to by `view_type`, when `view_type` is `project`, `label`, or `filter`. |
| 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. |
| grouped\_by _Enum_ | Grouping criteria for this view customization. One of `assignee`, `added_date`, `due_date`, `deadline`, `label`, `priority`, `project`, or `workspace`. |
| sorted\_by _Enum_ | Sorting criteria for this view customization. One of `alphabetically`, `assignee`, `added_date`, `due_date`, `deadline`, `label`, `priority`, `project`, `workspace`, or `manual`. |
| sort\_order _Enum_ | Sorting order for this view customization. `asc` for ascending, `desc` for descending. |
| show\_completed\_tasks _Boolean_ | Whether completed tasks should be shown automatically in this view customization. |
| 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.** |
| 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. |
| calendar\_settings _JSON_ | The settings for the calendar when `view_mode` is set to `calendar`. Currently, only `{"layout": "week"}` and `{"layout": "month"}` are supported. |
| is\_deleted _Boolean_ | Whether the view option is marked as deleted. |
**Note:** `view_options.view_mode` is secondary to [`project.view_style`](https://developer.todoist.com/api/v1#tag/Sync/View-Options)
for projects in Todoist clients. The former is set per user, while the latter is set per project.
[](https://developer.todoist.com/api/v1#tag/Sync/View-Options/Set-a-view-option)
Set a view option
--------------------------------------------------------------------------------------------------
| Argument | Required | Description |
| --- | --- | --- |
| 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, or `filter` for a filter. |
| object\_id _String_ | Yes | ID of the object referred to by `view_type`, required when `view_type` is `project`, `label`, or `filter`. |
| 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. |
| grouped\_by _Enum_ | No | Grouping criteria. One of `assignee`, `added_date`, `due_date`, `deadline`, `label`, `priority`, `project`, or `workspace`. |
| sorted\_by _Enum_ | No | Sorting criteria. One of `alphabetically`, `assignee`, `added_date`, `due_date`, `deadline`, `label`, `priority`, `project`, `workspace`, or `manual`. |
| sort\_order _Enum_ | No | Sorting order. `asc` for ascending, `desc` for descending. |
| show\_completed\_tasks _Boolean_ | No | Whether completed tasks should be shown automatically in this view customization. |
| view\_mode _Enum_ | No | The mode in which to render tasks. One of `list`, `board`, or `calendar`. |
| 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. |
| calendar\_settings _JSON_ | No | The settings for the calendar when `view_mode` is set to `calendar`. Currently, only `{"layout": "week"}` and `{"layout": "month"}` are supported. |
> Example set view option request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "view_options_set",\
"uuid": "997d4b43-55f1-48a9-9e66-de5785dfd696",\
"args": {\
"view_type": "project",\
"object_id": "6Jf8VQXxpwv56VQ7",\
"view_mode": "board",\
"grouped_by": "assignee"\
}\
}]'
> Example response:
{
...
"sync_status": {"997d4b43-55f1-48a9-9e66-de5785dfd696": "ok"},
...
}
[](https://developer.todoist.com/api/v1#tag/Sync/View-Options/Delete-view-option)
Delete view option
----------------------------------------------------------------------------------------------------
| Argument | Required | Description |
| --- | --- | --- |
| 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. |
| object\_id _String_ | Yes | ID of the object referred to by `view_type`, required when `view_type` is `project`, `label`, or `filter`. |
> Example delete view option request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "view_options_delete",\
"uuid": "f8539c77-7fd7-4846-afad-3b201f0be8a6",\
"args": {\
"view_type": "today"\
}\
}]'
> Example response:
{
...
"sync_status": {"f8539c77-7fd7-4846-afad-3b201f0be8a6": "ok"},
...
}
[](https://developer.todoist.com/api/v1#tag/Sync/User)
User
-----------------------------------------------------------
> An example user:
{
"activated_user": false,
"auto_reminder": 0,
"avatar_big": "https://*.cloudfront.net/*_big.jpg",
"avatar_medium": "https://*.cloudfront.net/*_medium.jpg",
"avatar_s640": "https://*.cloudfront.net/*_s640.jpg",
"avatar_small": "https://*.cloudfront.net/*_small.jpg",
"business_account_id": "1",
"daily_goal": 15,
"date_format": 0,
"days_off": [6, 7],
"email": "me@example.com",
"feature_identifier": "2671355_0123456789abcdef70123456789abcdefe0123456789abcdefd0123456789abc",
"features": {
"beta": 1,
"dateist_inline_disabled": false,
"dateist_lang": null,
"global.teams": true,
"has_push_reminders": true,
"karma_disabled": false,
"karma_vacation": false,
"kisa_consent_timestamp": null,
"restriction": 3
},
"full_name": "Example User",
"has_password": true,
"id": "2671355",
"image_id": "d160009dfd52b991030d55227003450f",
"inbox_project_id": "6X7fqH39MwjmwV4q",
"is_celebrations_enabled": true,
"is_premium": true,
"joinable_workspace": null,
"joined_at": "2015-07-31T18:32:06.000000Z",
"karma": 37504,
"karma_trend": "up",
"lang": "en",
"mfa_enabled": false,
"next_week": 1,
"premium_status": "current_personal_plan",
"premium_until": null,
"share_limit": 51,
"sort_order": 0,
"start_day": 1,
"start_page": "project?id=2203306141",
"theme_id": "11",
"time_format": 0,
"token": "0123456789abcdef0123456789abcdef01234567",
"tz_info": {
"gmt_string": "-03:00",
"hours": -3,
"is_dst": 0,
"minutes": 0,
"timezone": "America/Sao_Paulo"
},
"verification_status": "legacy",
"weekend_start_day": 6,
"weekly_goal": 30
}
A Todoist user is represented by a JSON object. The dates will be in the UTC timezone. Typically, a user object will have the following properties:
#### Properties
| Property | Description |
| --- | --- |
| auto\_reminder _Integer_ | The default time in minutes for the automatic reminders set, whenever a due date has been specified for a task. |
| avatar\_big _String_ | The link to a 195x195 pixels image of the user's avatar. |
| avatar\_medium _String_ | The link to a 60x60 pixels image of the user's avatar. |
| avatar\_s640 _String_ | The link to a 640x640 pixels image of the user's avatar. |
| avatar\_small _String_ | The link to a 35x35 pixels image of the user's avatar. |
| business\_account\_id _String_ | The ID of the user's business account. |
| daily\_goal _Integer_ | The daily goal number of completed tasks for karma. |
| 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`). |
| 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`. |
| days\_off _Array_ | Array of integers representing user's days off (between `1` and `7`, where `1` is `Monday` and `7` is `Sunday`). |
| email _String_ | The user's email. |
| feature\_identifier _String_ | An opaque id used internally to handle features for the user. |
| 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. |
| full\_name _String_ | The user's real name formatted as `Firstname Lastname`. |
| 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.) |
| id _String_ | The user's ID. |
| image\_id _String_ | The ID of the user's avatar. |
| inbox\_project\_id _String_ | The ID of the user's `Inbox` project. |
| is\_premium _Boolean_ | Whether the user has a Todoist Pro subscription (a `true` or `false` value). |
| joined\_at _String_ | The date when the user joined Todoist. |
| karma _Integer_ | The user's karma score. |
| karma\_trend _String_ | The user's karma trend (for example `up`). |
| 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`. |
| 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`). |
| premium\_status _String_ | Outlines why a user is premium, possible values are: `not_premium`, `current_personal_plan`, `active_business_account` or `teams_business_member`. |
| 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. |
| 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`). |
| start\_day _Integer_ | The first day of the week (between `1` and `7`, where `1` is `Monday` and `7` is `Sunday`). |
| 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, or `filter?id=1234` to open a filter. |
| theme\_id _String_ | The currently selected Todoist theme (a number between `0` and `10`). |
| 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`). |
| token _String_ | The user's token that should be used to call the other API methods. |
| 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`. |
| 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). |
| verification\_status _String_ | Describes if the user has verified their e-mail address or not. Possible values are: |
* `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.
* `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.
* `blocked`, for users that have failed to verify themselves in 7 days. Those users will have restricted usage of Todoist.
* `legacy`, for users that have signed up before August, 2022 weekly\_goal _Integer_ | The target number of tasks to complete per week.
[](https://developer.todoist.com/api/v1#tag/Sync/User/Update-user's-properties)
Update user's properties
--------------------------------------------------------------------------------------------------------
> Example update user request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "user_update",\
"uuid": "52f83009-7e27-4b9f-9943-1c5e3d1e6889",\
"args": {\
"current_password": "fke4iorij",\
"email": "mynewemail@example.com"\
}\
}]'
> Example response:
{
...
"sync_status": {"52f83009-7e27-4b9f-9943-1c5e3d1e6889": "ok"},
...
}
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| 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](https://developer.todoist.com/api/v1#tag/Sync/User) object). For amending other properties this is not required. |
| email _String_ | No | The user's email. |
| full\_name _String_ | No | The user's name. |
| password _String_ | No | The user's updated password. Must contain at least 8 characters and not be a common or easily guessed password. |
| timezone _String_ | No | The user's timezone (a string value such as `UTC`, `Europe/Lisbon`, `US/Eastern`, `Asia/Taipei`). |
| start\_page _String_ | No | The user's default view on Todoist. The start page can be one of the following: `inbox`, `teaminbox`, `today`, `next7days`, `project?id=1234` to open a project, `label?name=abc` to open a label, or `filter?id=1234` to open a filter. |
| start\_day _Integer_ | No | The first day of the week (between `1` and `7`, where `1` is `Monday` and `7` is `Sunday`). |
| next\_week _Integer_ | No | The day of the next week, that tasks will be postponed to (between `1` and `7`, where `1` is `Monday` and `7` is `Sunday`). |
| time\_format _Integer_ | No | Whether to use a `24h` format such as `13:00` (if set to `0`) when displaying time, or a `12h` format such as `1:00pm` (if set to `1`). |
| date\_format _Integer_ | No | Whether to use the `DD-MM-YYYY` date format (if set to `0`), or the `MM-DD-YYYY` format (if set to `1`). |
| sort\_order _Integer_ | No | Whether to show projects in an `oldest dates first` order (if set to `0`, or a `oldest dates last` order (if set to `1`). |
| auto\_reminder _Integer_ | No | The default time in minutes for the automatic reminders set, whenever a due date has been specified for a task. |
| theme _Integer_ | No | The currently selected Todoist theme (between `0` and `10`). |
| weekend\_start\_day _Integer_ | No | The day used when a user chooses to schedule a task for the 'Weekend' (between 1 and 7, where 1 is Monday and 7 is Sunday). |
| beta _Boolean_ | No | Whether the user is included in the beta testing group. |
#### Error codes
| Error Tag | Description |
| --- | --- |
| `PASSWORD_REQUIRED` | The command attempted to modify `password` or `email`, but no value was provided for `current_password`. |
| `AUTHENTICATION_ERROR` | The value for `current_password` was incorrect. |
| `PASSWORD_TOO_SHORT` | The value for `password` was shorter than the minimum 8 characters. |
| `COMMON_PASSWORD` | The value for `password` was matched against a common password list and rejected. |
| `PASSWORD_CONTAINS_EMAIL` | The value for password was matched against the user's email address or a part of the address. |
| `INVALID_EMAIL` | The value for `email` was not a valid email address. |
[](https://developer.todoist.com/api/v1#tag/Sync/User/Update-karma-goals)
Update karma goals
--------------------------------------------------------------------------------------------
> Example update karma goals request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "update_goals",\
"uuid": "b9bbeaf8-9db6-452a-a843-a192f1542892",\
"args": {"vacation_mode": 1}\
}]'
> Example response:
{
...
"sync_status": {"b9bbeaf8-9db6-452a-a843-a192f1542892": "ok"},
...
}
Update the karma goals of the user.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| daily\_goal _Integer_ | No | The target number of tasks to complete per day. |
| weekly\_goal _Integer_ | No | The target number of tasks to complete per week. |
| ignore\_days _Integer_ | No | A list with the days of the week to ignore (`1` for `Monday` and `7` for `Sunday`). |
| vacation\_mode _Integer_ | No | Marks the user as being on vacation (where `1` is true and `0` is false). |
| karma\_disabled _Integer_ | No | Whether to disable the karma and goals measuring altogether (where `1` is true and `0` is false). |
[](https://developer.todoist.com/api/v1#tag/Sync/User/User-plan-limits)
User plan limits
----------------------------------------------------------------------------------------
> An example user plan limits sync response
{
"user_plan_limits": {
"current": {
"plan_name": "free",
...details of the current user plan
},
"next": {
"plan_name": "pro",
...details of a potential upgrade
}
}
}
The `user_plan_limits` sync resource type describes the available features and limits applicable to the current user plan. The user plan info object (detailed in the next section) returned within the `current` property shows the values that are currently applied to the user.
If there is an upgrade available, the `next` property will show the values that will apply if the user chooses to upgrade. If there is no available upgrade, the `next` value will be null.
#### Properties
| Property | Description |
| --- | --- |
| current _Object_ | A user plan info object representing the available functionality and limits for the user's current plan. |
| next _Object_ | A user plan info object representing the plan available for upgrade. If there is no available upgrade, this value will be null. |
### User plan info
> An example user plan info object
{
"activity_log": true,
"activity_log_limit": 7,
"advanced_permissions": true,
"automatic_backups": false,
"calendar_feeds": true,
"calendar_layout": true,
"comments": true,
"completed_tasks": true,
"customization_color": false,
"deadlines": true,
"durations": true,
"email_forwarding": true,
"filters": true,
"labels": true,
"max_calendar_accounts": 1,
"max_collaborators": 5,
"max_filters": 3,
"max_folders_per_workspace": 25,
"max_free_workspaces_created": 1,
"max_guests_per_workspace": 25,
"max_labels": 500,
"max_projects": 5,
"max_projects_joined": 500,
"max_reminders_location": 300,
"max_reminders_time": 700,
"max_sections": 20,
"max_tasks": 300,
"max_user_templates": 100,
"plan_name": "free",
"reminders": false,
"reminders_at_due": true,
"templates": true,
"upload_limit_mb": 5,
"uploads": true,
"weekly_trends": true
}
The user plan info object describes the availability of features and any limitations applied for a given user plan.
#### Properties
| Property | Description |
| --- | --- |
| plan\_name _String_ | The name of the plan. |
| activity\_log _Boolean_ | Whether the user can view the [activity log](https://developer.todoist.com/api/v1#tag/Activity) . |
| 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`. |
| automatic\_backups _Boolean_ | Whether [backups](https://developer.todoist.com/api/v1#tag/Backups) will be automatically created for the user's account and available for download. |
| calendar\_feeds _Boolean_ | Whether calendar feeds can be enabled for the user's projects. |
| comments _Boolean_ | Whether the user can add [comments](https://developer.todoist.com/api/v1#tag/Sync/Comments) . |
| completed\_tasks _Boolean_ | Whether the user can search in the completed tasks archive or access the completed tasks overview. |
| customization\_color _Boolean_ | Whether the user can use special themes or other visual customization such as custom app icons. |
| email\_forwarding _Boolean_ | Whether the user can add tasks or comments via [email](https://developer.todoist.com/api/v1#tag/Emails) . |
| filters _Boolean_ | Whether the user can add and update [filters](https://developer.todoist.com/api/v1#tag/Sync/Filters) . |
| max\_filters _Integer_ | The maximum number of filters a user can have. |
| labels _Boolean_ | Whether the user can add [labels](https://developer.todoist.com/api/v1#tag/Sync/Labels) . |
| max\_labels _Integer_ | The maximum number of labels a user can have. |
| reminders _Boolean_ | Whether the user can add [reminders](https://developer.todoist.com/api/v1#tag/Sync/Reminders) . |
| max\_reminders\_location _Integer_ | The maximum number of location reminders a user can have. |
| max\_reminders\_time _Integer_ | The maximum number of time-based reminders a user can have. |
| templates _Boolean_ | Whether the user can import and export [project templates](https://developer.todoist.com/api/v1#tag/Templates) . |
| uploads _Boolean_ | Whether the user can [upload attachments](https://developer.todoist.com/api/v1#tag/Uploads) . |
| upload\_limit\_mb _Integer_ | The maximum size of an individual file the user can upload. |
| weekly\_trends _Boolean_ | Whether the user can view [productivity stats](https://developer.todoist.com/api/v1#tag/Sync/User) . |
| max\_projects _Integer_ | The maximum number of active [projects](https://developer.todoist.com/api/v1#tag/Sync/Projects) a user can have. |
| max\_sections _Integer_ | The maximum number of active [sections](https://developer.todoist.com/api/v1#tag/Sync/Sections) a user can have. |
| max\_tasks _Integer_ | The maximum number of active [tasks](https://developer.todoist.com/api/v1#tag/Sync/Tasks) a user can have. |
| max\_collaborators _Integer_ | The maximum number of [collaborators](https://developer.todoist.com/api/v1#tag/Sync/Sharing/Collaborators) a user can add to a project. |
[](https://developer.todoist.com/api/v1#tag/Sync/User/User-settings)
User settings
----------------------------------------------------------------------------------
> Example user settings object:
{
"reminder_push": true,
"reminder_desktop": true,
"reminder_email": true,
"completed_sound_desktop": true,
"completed_sound_mobile": true
}
_Availability of reminders functionality is dependent on the current user plan. This value is indicated by the `reminders` property of the [user plan limits](https://developer.todoist.com/api/v1#tag/Sync/User/User-plan-limits)
object. These settings will have no effect if the user is not eligible for reminders._
#### Properties
| Property | Description |
| --- | --- |
| reminder\_push _Boolean_ | Set to true to send reminders as push notifications. |
| reminder\_desktop _Boolean_ | Set to true to show reminders in desktop applications. |
| reminder\_email _Boolean_ | Set to true to send reminders by email. |
| completed\_sound\_desktop _Boolean_ | Set to true to enable sound when a task is completed in Todoist desktop clients. |
| completed\_sound\_mobile _Boolean_ | Set to true to enable sound when a task is completed in Todoist mobile clients. |
### Update user settings
> Example update user settings request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "user_settings_update",\
"temp_id": "e24ad822-a0df-4b7d-840f-83a5424a484a",\
"uuid": "41e59a76-3430-4e44-92b9-09d114be0d49",\
"args": {"reminder_desktop": false}\
}]'
> Example response:
{
...
"sync_status": {"41e59a76-3430-4e44-92b9-09d114be0d49": "ok"},
...
}
Update one or more user settings.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| reminder\_push _Boolean_ | No | Set to true to send reminders as push notifications. |
| reminder\_desktop _Boolean_ | No | Set to true to show reminders in desktop applications. |
| reminder\_email _Boolean_ | No | Set to true to send reminders by email. |
| completed\_sound\_desktop _Boolean_ | No | Set to true to enable sound when a task is completed in Todoist desktop clients. |
| completed\_sound\_mobile _Boolean_ | No | Set to true to enable sound when a task is completed in Todoist mobile clients. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sharing)
Sharing
-----------------------------------------------------------------
Projects can be shared with other users, which are then referred to as collaborators. This section describes the different commands that are related to sharing.
[](https://developer.todoist.com/api/v1#tag/Sync/Sharing/Collaborators)
Collaborators
-------------------------------------------------------------------------------------
> An example collaborator object:
{
"id": "2671362",
"email": "you@example.com",
"full_name": "Example User",
"timezone": "GMT +3:00",
"image_id": null
}
There are two types of objects to get information about a user’s collaborators, and their participation in shared projects: `collaborators` and `collaborator_states`
Every user who shares at least one project with another user, has a collaborators record in the API response. The record contains a restricted subset of user-specific properties.
| Property | Description |
| --- | --- |
| id _String_ | The user ID of the collaborator. |
| email _String_ | The email of the collaborator. |
| full\_name _String_ | The full name of the collaborator. |
| timezone _String_ | The timezone of the collaborator. |
| 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. |
Partial sync returns updated collaborator objects for users that have changed their attributes, such as their name or email.
[](https://developer.todoist.com/api/v1#tag/Sync/Sharing/Collaborator-states)
Collaborator states
-------------------------------------------------------------------------------------------------
> An example collaborator state:
{
"project_id": "6H2c63wj7x9hFJfX",
"user_id": "2671362",
"state": "active",
"is_deleted": false,
"role": "READ_WRITE",
}
The list of collaborators don’t contain any information on how users are connected to shared projects. To provide information about these connections, the `collaborator_states` field should be used. Every collaborator state record is a mere "user to shared project" mapping.
| Property | Description |
| --- | --- |
| project\_id _String_ | The shared project ID of the user. |
| user\_id _String_ | The user ID of the collaborator. |
| state _String_ | The status of the collaborator state, either `active` or `invited`. |
| is\_deleted _Boolean_ | Set to `true` when the collaborator leaves the shared project. |
| role | The role of the collaborator in the project. _Only available for teams_ |
[](https://developer.todoist.com/api/v1#tag/Sync/Sharing/Share-a-project)
Share a project
-----------------------------------------------------------------------------------------
> Example share project request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "share_project",\
"temp_id": "854be9cd-965f-4ddd-a07e-6a1d4a6e6f7a",\
"uuid": "fe6637e3-03ce-4236-a202-8b28de2c8372",\
"args": {\
"project_id": "6H2c63wj7x9hFJfX",\
"email": "you@example.com"\
}\
}]'
> Example response:
{
...
"sync_status": {"fe6637e3-03ce-4236-a202-8b28de2c8372": "ok"},
...
}
Share a project with another user.
_When sharing a teams project_
Workspace projects with `is_invite_only` set to true can only be shared by workspace admins, or by project members with `ADMIN` or `CREATOR` role. Other users will get a “forbidden” error. The role for the new collaborator cannot be greater than the role of the person sharing the project.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| project\_id _String_ | Yes | The project to be shared. |
| email _String_ | Yes | The user email with whom to share the project. |
| role _String_ | No | The role of the new collaborator in the workspace project. If missing, the workspace `collaborator_role_default` will be used. _Only used for teams_ |
[](https://developer.todoist.com/api/v1#tag/Sync/Sharing/Delete-a-collaborator)
Delete a collaborator
-----------------------------------------------------------------------------------------------------
> Example delete collaborator request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "delete_collaborator",\
"uuid": "0ae55ac0-3b8d-4835-b7c3-59ba30e73ae4",\
"args": {\
"project_id": "6H2c63wj7x9hFJfX",\
"email": "you@example.com"\
}\
}]'
> Example response:
{
...
"sync_status": {"0ae55ac0-3b8d-4835-b7c3-59ba30e73ae4": "ok"},
...
}
Remove a user from a shared project. In Teams, only workspace admins or project members with `ADMIN` or `CREATOR` role can delete a collaborator. Other users will get a “forbidden” error.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| project\_id _String_ | Yes | The project to be affected. |
| email _String_ | Yes | The user email with whom the project was shared. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sharing/Accept-an-invitation)
Accept an invitation
---------------------------------------------------------------------------------------------------
> Example accept invitation request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "accept_invitation",\
"uuid": "4b254da4-fa2b-4a88-9439-b27903a90f7f",\
"args": {\
"invitation_id": "1234",\
"invitation_secret": "abcdefghijklmno"\
}\
}]'
> Example response:
{
...
"sync_status": {"4b254da4-fa2b-4a88-9439-b27903a90f7f": "ok"},
...
}
Accept an invitation to join a shared project.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| invitation\_id _String_ | Yes | The invitation ID. |
| invitation\_secret _String_ | Yes | The secret fetched from the live notification. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sharing/Reject-an-invitation)
Reject an invitation
---------------------------------------------------------------------------------------------------
> Example reject invitation request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "reject_invitation",\
"uuid": "284fd900-c36f-44e5-ab92-ee93455e50e0",\
"args": {\
"invitation_id": "1234",\
"invitation_secret": "abcdefghijklmno"\
}\
}]'
> Example response:
{
...
"sync_status": {"284fd900-c36f-44e5-ab92-ee93455e50e0": "ok"},
...
}
Reject an invitation to join a shared project.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| invitation\_id _String_ | Yes | The invitation ID. |
| invitation\_secret _String_ | Yes | The secret fetched from the live notification. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sharing/Delete-an-invitation)
Delete an invitation
---------------------------------------------------------------------------------------------------
> Example delete invitation request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "delete_invitation",\
"uuid": "399f6a8d-ddea-4146-ae8e-b41fb8ff6945",\
"args": {"invitation_id": "1234"}\
}]'
> Example response:
{
...
"sync_status": {"399f6a8d-ddea-4146-ae8e-b41fb8ff6945": "ok"},
...
}
Delete an invitation to join a shared project.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| invitation\_id _String_ | Yes | The invitation to be deleted. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sections)
Sections
-------------------------------------------------------------------
> An example section object
{
"id": "6Jf8VQXxpwv56VQ7",
"name": "Groceries",
"project_id": "9Bw8VQXxpwv56ZY2",
"section_order": 1,
"is_collapsed": false,
"user_id": "2671355",
"is_deleted": false,
"is_archived": false,
"archived_at": null,
"added_at": "2019-10-07T07:09:27.000000Z",
"updated_at": "2019-10-07T07:09:27.000000Z"
}
#### Properties
| Property | Description |
| --- | --- |
| id _String_ | The ID of the section. |
| name _String_ | The name of the section. |
| project\_id _String_ | Project that the section resides in |
| section\_order _Integer_ | The order of the section. Defines the position of the section among all the sections in the project. |
| is\_collapsed _Boolean_ | Whether the section's tasks are collapsed (a `true` or `false` value). |
| sync\_id _String_ | A special ID for shared sections (a number or `null` if not set). Used internally and can be ignored. |
| is\_deleted _Boolean_ | Whether the section is marked as deleted (a `true` or `false` value). |
| is\_archived _Boolean_ | Whether the section is marked as archived (a `true` or `false` value). |
| archived\_at _String_ | The date when the section was archived (or `null` if not archived). |
| added\_at _String_ | The date when the section was created. |
| updated\_at _String_ | The date when the section was updated. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sections/Add-a-section)
Add a section
--------------------------------------------------------------------------------------
> Example add section request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[{\
"type": "section_add",\
"temp_id": "69ca86df-5ffe-4be4-9c3a-ad14fe98a58a",\
"uuid": "97b68ab2-f524-48da-8288-476a42cccf28",\
"args": {"name": "Groceries", "project_id": "9Bw8VQXxpwv56ZY2"}\
}]'
> Example response:
{
...
"sync_status": {"97b68ab2-f524-48da-8288-476a42cccf28": "ok"},
"temp_id_mapping": {"69ca86df-5ffe-4be4-9c3a-ad14fe98a58a": "6X7FxXvX84jHphx2"},
...
}
Add a new section to a project.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| name _String_ | Yes | The name of the section. |
| project\_id _String_ | Yes | The ID of the parent project. |
| section\_order _Integer_ | No | The order of the section. Defines the position of the section among all the sections in the project. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sections/Update-a-section)
Update a section
--------------------------------------------------------------------------------------------
> Example update section request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[{\
"type": "section_update",\
"uuid": "afda2f29-319c-4d09-8162-f2975bed3124",\
"args": {"id": "6X7FxXvX84jHphx2", "name": "Supermarket"}\
}]'
> Example response:
{
...
"sync_status": {"afda2f29-319c-4d09-8162-f2975bed3124": "ok"},
...
}
Updates section attributes.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the section. |
| name _String_ | No | The name of the section. |
| is\_collapsed _Boolean_ | No | Whether the section's tasks are collapsed (a `true` or `false` value). |
[](https://developer.todoist.com/api/v1#tag/Sync/Sections/Move-a-section)
Move a section
----------------------------------------------------------------------------------------
> Example move section request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[{\
"type": "section_move",\
"uuid": "a8583f66-5885-4729-9e55-462e72d685ff",\
"args": {"id": "6X7FxXvX84jHphx2", "project_id": "9Bw8VQXxpwv56ZY2"}\
}]'
> Example response:
{
...
"sync_status": {"a8583f66-5885-4729-9e55-462e72d685ff": "ok"},
...
}
Move section to a different location.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the section. |
| project\_id _String_ | No | ID of the destination project. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sections/Reorder-sections)
Reorder sections
--------------------------------------------------------------------------------------------
> Example reorder sections request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[{\
"type": "section_reorder",\
"uuid": "109af205-6ff7-47fa-a5f8-1f13e59744ef",\
"args": {\
"sections": [\
{"id": "6X7FxXvX84jHphx2", "section_order": 1},\
{"id": "6X9FxXvX64jjphx3", "section_order": 2}\
]\
}\
}]'
> Example response:
{
...
"sync_status": {"109af205-6ff7-47fa-a5f8-1f13e59744ef": "ok"},
...
}
The command updates `section_order` properties of sections in bulk.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| 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. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sections/Delete-a-section)
Delete a section
--------------------------------------------------------------------------------------------
> Example delete section request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[{\
"type": "section_delete",\
"uuid": "cebb5267-3e3c-40da-af44-500649281936",\
"args": {"id": "6X7FxXvX84jHphx2"}\
}]'
> Example response:
{
...
"sync_status": {"cebb5267-3e3c-40da-af44-500649281936": "ok"},
...
}
Delete a section and all its child tasks.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | ID of the section to delete. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sections/Archive-a-section)
Archive a section
----------------------------------------------------------------------------------------------
> Example archive section request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[{\
"type": "section_archive",\
"uuid": "2451f267-46ab-4f0e-8db7-82a9cd576f72",\
"args": {"id": "6X7FxXvX84jHphx2"}\
}]'
> Example response:
{
...
"sync_status": {"2451f267-46ab-4f0e-8db7-82a9cd576f72": "ok"},
...
}
Archive a section and all its child tasks.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | Section ID to archive. |
[](https://developer.todoist.com/api/v1#tag/Sync/Sections/Unarchive-a-section)
Unarchive a section
--------------------------------------------------------------------------------------------------
> Example unarchive section request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[{\
"type": "section_unarchive",\
"uuid": "cd3a4b4b-182e-4733-b6b5-20a621ba98b8",\
"args": {"id": "6X7FxXvX84jHphx2"}\
}]'
> Example response:
{
...
"sync_status": {"cd3a4b4b-182e-4733-b6b5-20a621ba98b8": "ok"},
...
}
This command is used to unarchive a section.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | Section ID to unarchive |
[](https://developer.todoist.com/api/v1#tag/Sync/Reminders)
Reminders
---------------------------------------------------------------------
> An example reminder:
{
"id": "6X7Vfq5rqPMM5j5q",
"notify_uid": "2671355",
"item_id": "6RP2hmPwM3q4WGfW",
"type": "absolute",
"due": {
"date": "2016-08-05T07:00:00.000000Z",
"timezone": null,
"is_recurring": false,
"string": "tomorrow at 10:00",
"lang": "en"
},
"minute_offset": 180,
"is_deleted": false
}
_Availability of reminders functionality and the maximum number of stored reminders are dependent on the current user plan. These values are indicated by the `reminders`, `max_reminders_time` and `max_reminders_location` properties of the [user plan limits](https://developer.todoist.com/api/v1#tag/Sync/User/User-plan-limits)
object._
#### Properties
| Property | Description |
| --- | --- |
| id _String_ | The ID of the reminder. |
| notify\_uid _String_ | The user ID which should be notified of the reminder, typically the current user ID creating the reminder. |
| item\_id _String_ | The item ID for which the reminder is about. |
| 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. |
| due _Object_ | The due date of the reminder. See the [Due dates](https://developer.todoist.com/api/v1#tag/Due-dates) section for more details. Note that reminders only support due dates with time, since full-day reminders don't make sense. |
| minute\_offset _Integer_ | The relative time in minutes before the due date of the item, in which the reminder should be triggered. Note that the item should have a due date with time set in order to add a relative reminder. |
| name _String_ | An alias name for the location. |
| loc\_lat _String_ | The location latitude. |
| loc\_long _String_ | The location longitude. |
| loc\_trigger _String_ | What should trigger the reminder: `on_enter` for entering the location, or `on_leave` for leaving the location. |
| radius _Integer_ | The radius around the location that is still considered as part of the location (in meters). |
| is\_deleted _Boolean_ | Whether the reminder is marked as deleted (a `true` or `false` value). |
[](https://developer.todoist.com/api/v1#tag/Sync/Reminders/Add-a-reminder)
Add a reminder
-----------------------------------------------------------------------------------------
> Example of adding relative reminder:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "reminder_add",\
"temp_id": "e24ad822-a0df-4b7d-840f-83a5424a484a",\
"uuid": "41e59a76-3430-4e44-92b9-09d114be0d49",\
"args": {\
"item_id": "6RP2hmPwM3q4WGfW",\
"minute_offset": 30,\
"type": "absolute"\
}\
}]'
> Example response:
{
...
"sync_status": {"41e59a76-3430-4e44-92b9-09d114be0d49": "ok"},
"temp_id_mapping": {"e24ad822-a0df-4b7d-840f-83a5424a484a": "2992683215"},
...
}
> Example of adding an absolute reminder:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "reminder_add",\
"temp_id": "952a365e-4965-4113-b4f4-80cdfcada172u",\
"uuid": "e7c8be2d-f484-4852-9422-a9984c58b1cd",\
"args": {\
"item_id": "6RP2hmPwM3q4WGfW",\
"due": {\
"date": "2014-10-15T11:00:00.000000Z"\
},\
"type": "absolute"\
}\
}]'
> Example response:
{
...
"sync_status": {"e7c8be2d-f484-4852-9422-a9984c58b1cd": "ok"},
"temp_id_mapping": {"952a365e-4965-4113-b4f4-80cdfcada172": "2992683215"},
...
}
> Example of adding a location reminder:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "reminder_add",\
"temp_id": "7ad9609d-579f-4828-95c5-3600acdb2c81",\
"uuid": "830cf409-daba-479c-a624-68eb0c07d01c",\
"args": {\
"item_id": "6RP2hmPwM3q4WGfW",\
"type": "location",\
"name": "Aliados",\
"loc_lat": "41.148581",\
"loc_long":"-8.610945000000015",\
"loc_trigger":"on_enter",\
"radius": 100\
}\
}]'
> Example response:
{
...
"sync_status": {"830cf409-daba-479c-a624-68eb0c07d01c": "ok"},
"temp_id_mapping": {"7ad9609d-579f-4828-95c5-3600acdb2c81": "2992683215"},
...
}
Add a new reminder to the user account related to the API credentials.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| item\_id _String_ | Yes | The item ID for which the reminder is about. |
| type _String_ | Yes | The type of the reminder: `relative` for a time-based reminder specified in minutes from now, `absolute` for a time-based reminder with a specific time and date in the future, and `location` for a location-based reminder. |
| notify\_uid _String_ | No | The user ID which should be notified of the reminder, typically the current user ID creating the reminder. |
| due _Object_ | No | The due date of the reminder. See the [Due dates](https://developer.todoist.com/api/v1#tag/Due-dates) section for more details. Note that reminders only support due dates with time, since full-day reminders don't make sense. |
| minute\_offset _Integer_ | No | The relative time in minutes before the due date of the item, in which the reminder should be triggered. Note, that the item should have a due date with time set in order to add a relative reminder. |
| name _String_ | No | An alias name for the location. |
| loc\_lat _String_ | No | The location latitude. |
| loc\_long _String_ | No | The location longitude. |
| loc\_trigger _String_ | No | What should trigger the reminder: `on_enter` for entering the location, or `on_leave` for leaving the location. |
| radius _Integer_ | No | The radius around the location that is still considered as part of the location (in meters). |
[](https://developer.todoist.com/api/v1#tag/Sync/Reminders/Update-a-reminder)
Update a reminder
-----------------------------------------------------------------------------------------------
> Example update reminder request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "reminder_update",\
"uuid": "b0e7562e-ea9f-4c84-87ee-9cbf9c103234",\
"args": {\
"id": "6X7VrXrqjX6642cv",\
"due": {\
"date": "2014-10-10T15:00:00.000000"\
}\
}\
}]'
> Example response:
{
...
"sync_status": {"b0e7562e-ea9f-4c84-87ee-9cbf9c103234": "ok"},
...
}
Update a reminder from the user account related to the API credentials.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the reminder. |
| notify\_uid _String_ | No | The user ID which should be notified of the reminder, typically the current user ID creating the reminder. |
| type _String_ | No | The type of the reminder: `relative` for a time-based reminder specified in minutes from now, `absolute` for a time-based reminder with a specific time and date in the future, and `location` for a location-based reminder. |
| due _Object_ | No | The due date of the reminder. See the [Due dates](https://developer.todoist.com/api/v1#tag/Due-dates) section for more details. Note that reminders only support due dates with time, since full-day reminders don't make sense. |
| minute\_offset _Integer_ | No | The relative time in minutes before the due date of the item, in which the reminder should be triggered. Note, that the item should have a due date with time set in order to add a relative reminder. |
| name _String_ | No | An alias name for the location. |
| loc\_lat _String_ | No | The location latitude. |
| loc\_long _String_ | No | The location longitude. |
| loc\_trigger _String_ | No | What should trigger the reminder: `on_enter` for entering the location, or `on_leave` for leaving the location. |
| radius _Integer_ | No | The radius around the location that is still considered as part of the location (in meters). |
[](https://developer.todoist.com/api/v1#tag/Sync/Reminders/Delete-a-reminder)
Delete a reminder
-----------------------------------------------------------------------------------------------
> Example delete reminder request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "reminder_delete",\
"uuid": "0896d03b-eb90-49f7-9020-5ed3fd09df2d",\
"args": {"id": "6X7VrXrqjX6642cv"}\
}]'
> Example response:
{
...
"sync_status": {"0896d03b-eb90-49f7-9020-5ed3fd09df2d": "ok"},
...
}
Delete a reminder from the current user account.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the filter. |
[](https://developer.todoist.com/api/v1#tag/Sync/Reminders/Locations)
Locations
-------------------------------------------------------------------------------
Locations are a top-level entity in the sync model. They contain a list of all locations that are used within user's current location reminders.
> An example location object
["Shibuya-ku, Japan", "35.6623001098633", "139.706527709961"]
#### Properties
The location object is specific, as it's not an object, but an ordered array.
| Array index | Description |
| --- | --- |
| 0 _String_ | Name of the location. |
| 1 _String_ | Location latitude. |
| 2 _String_ | Location longitude. |
### Clear locations
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[{"type": "clear_locations", "uuid": "d285ae02-80c6-477c-bfa9-45272d7bddfb", "args": {}}]'
{
...
"sync_status": {"d285ae02-80c6-477c-bfa9-45272d7bddfb": "ok"},
...
}
Clears the locations list, which is used for location reminders.
[](https://developer.todoist.com/api/v1#tag/Sync/Projects)
Projects
-------------------------------------------------------------------
> An example project object:
{
"id": "6Jf8VQXxpwv56VQ7",
"name": "Shopping List",
"description": "Stuff to buy",
"workspace_id": 12345,
"is_invite_only": false,
"status": "IN_PROGRESS",
"is_link_sharing_enabled": true,
"collaborator_role_default": "READ_WRITE",
"color": "lime_green",
"parent_id": null,
"child_order": 1,
"is_collapsed": false,
"shared": false,
"can_assign_tasks": false,
"is_deleted": false,
"is_archived": false,
"is_favorite": false,
"is_frozen": false,
"view_style": "list",
"role": "READ_WRITE"
"inbox_project": true,
"folder_id": null,
"created_at": "2023-07-13T10:20:59Z",
"updated_at": "2024-12-10T13:27:29Z",
}
#### Properties
| Property | Description |
| --- | --- |
| id _String_ | The ID of the project. |
| name _String_ | The name of the project. |
| description _String_ | Description for the project. _Only used for teams_ |
| workspace\_id _String_ | Real or temp ID of the workspace the project. _Only used for teams_ |
| 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_ |
| status _String_ | The status of the project. Possible values: `PLANNED`, `IN_PROGRESS`, `PAUSED`, `COMPLETED`, `CANCELED`. _Only used for teams_ |
| 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_ |
| collaborator\_role\_default _String_ | The role a user can have. Possible values: `CREATOR`, `ADMIN`, `READ_WRITE`, `READ_AND_COMMENT`, `READ_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_ |
| color _String_ | The color of the project icon. Refer to the `name` column in the [Colors](https://developer.todoist.com/api/v1#tag/Colors) guide for more info. |
| parent\_id _String_ | The ID of the parent project. Set to `null` for root projects. |
| child\_order _Integer_ | The order of the project. Defines the position of the project among all the projects with the same `parent_id` |
| is\_collapsed _Boolean_ | Whether the project's sub-projects are collapsed (a `true` or `false` value). |
| shared _Boolean_ | Whether the project is shared (a `true` or `false` value). |
| can\_assign\_tasks _Boolean_ | Whether tasks in the project can be assigned to users (a `true` or `false` value). |
| is\_deleted _Boolean_ | Whether the project is marked as deleted (a `true` or `false` value). |
| is\_archived _Boolean_ | Whether the project is marked as archived (a `true` or `false` value). |
| is\_favorite _Boolean_ | Whether the project is a favorite (a `true` or `false` value). |
| is\_frozen _Boolean_ | Workspace or personal projects from a cancelled subscription (a `true` or `false` value). |
| view\_style _Enum_ | The mode in which to render tasks in this project. One of `list`, `board`, or `calendar`. |
| role _String_ | The role of the requesting user. Possible values: `CREATOR`, `ADMIN`, `READ_WRITE`, `READ_AND_COMMENT`, `READ_ONLY`. _Only used for teams_ |
| inbox\_project _Boolean_ | Whether the project is `Inbox` (`true` or otherwise this property is not sent). |
| folder\_id _String_ | The ID of the folder which this project is in. |
| created\_at _String_ | Project creation date in the format YYYY-MM-DDTHH:MM:SSZ date. |
| updated\_at _String_ | Project update date in the format YYYY-MM-DDTHH:MM:SSZ date. |
**Note:** `project.view_style` takes precedence over [`view_options.view_mode`](https://developer.todoist.com/api/v1#tag/Sync/View-Options)
for projects in Todoist clients. The former is set per project, while the latter is set per user.
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Add-a-project)
Add a project
--------------------------------------------------------------------------------------
> Example add project request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "project_add",\
"temp_id": "4ff1e388-5ca6-453a-b0e8-662ebf373b6b",\
"uuid": "32774db9-a1da-4550-8d9d-910372124fa4",\
"args": {\
"name": "Shopping List"\
}\
}]'
> Example response:
{
...
"sync_status": {"32774db9-a1da-4550-8d9d-910372124fa4": "ok"},
"temp_id_mapping": {"4ff1e388-5ca6-453a-b0e8-662ebf373b6b": "6Jf8VQXxpwv56VQ7"},
...
}
Add a new project.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| name _String_ | Yes | The name of the project (a string value). |
| color _String_ | No | The color of the project icon. Refer to the `name` column in the [Colors](https://developer.todoist.com/api/v1#tag/Colors) guide for more info. |
| parent\_id _String_ | No | The ID of the parent project. Set to `null` for root projects |
| folder\_id _String_ | No | The ID of the folder, when creating projects in workspaces. Set to `null` for root projects |
| child\_order _Integer_ | No | The order of the project. Defines the position of the project among all the projects with the same `parent_id` |
| is\_favorite _Boolean_ | No | Whether the project is a favorite (a `true` or `false` value). |
| view\_style _String_ | No | A string value (either `list` or `board`, default is `list`). This determines the way the project is displayed within the Todoist clients. |
| description _String_ | No | Description for the project (up to 1024 characters). _Only used for teams_ |
| workspace\_id _String_ | No | Real or temp ID of the workspace the project should belong to |
| is\_invite\_only _Boolean_ | No | Indicates if the project is invite-only or if it should be visible for everyone in the workspace. If missing or null, the default value from the workspace `is_invite_only_default` will be used. _Only used for teams_ |
| status _String_ | No | The status of the project. Possible values: `PLANNED`, `IN_PROGRESS`, `PAUSED`, `COMPLETED`, `CANCELED`. _Only used for teams_ |
| is\_link\_sharing\_enabled _Boolean_ | No | If False, the project is invite-only and people can't join by link. If true, the project is visible to anyone with a link, and anyone can join it. _Only used for teams_ |
| collaborator\_role\_default _String_ | No | The role a user can have. Possible values: `CREATOR`, `ADMIN`, `READ_WRITE`, `READ_AND_COMMENT`, `READ_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_ |
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Update-a-project)
Update a project
--------------------------------------------------------------------------------------------
> Example update project request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands=[\
{\
"type": "project_update",\
"uuid": "1ca42128-d12f-4a66-8413-4d6ff2838fde",\
"args": {\
"id": "6Jf8VQXxpwv56VQ7",\
"name": "Shopping"\
}\
}]'
> Example response:
{
...
"sync_status": {"1ca42128-d12f-4a66-8413-4d6ff2838fde": "ok"},
...
}
Update an existing project.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the project (could be temp id). |
| name _String_ | No | The name of the project (a string value). |
| color _String_ | No | The color of the project icon. Refer to the `name` column in the [Colors](https://developer.todoist.com/api/v1#tag/Colors) guide for more info. |
| is\_collapsed _Boolean_ | No | Whether the project's sub-projects are collapsed (a `true` or `false` value). |
| is\_favorite _Boolean_ | No | Whether the project is a favorite (a `true` or `false` value). |
| view\_style _String_ | No | A string value (either `list` or `board`). This determines the way the project is displayed within the Todoist clients. |
| description _String_ | No | Description for the project (up to 1024 characters). _Only used for teams_ |
| status _String_ | No | The status of the project. Possible values: `PLANNED`, `IN_PROGRESS`, `PAUSED`, `COMPLETED`, `CANCELED`. _Only used for teams_ |
| is\_link\_sharing\_enabled _Boolean_ | No | If False, the project is invite-only and people can't join by link. If true, the project is visible to anyone with a link, and anyone can join it. _Only used for teams_ |
| collaborator\_role\_default _String_ | No | The role a user can have. Possible values: `CREATOR`, `ADMIN`, `READ_WRITE`, `READ_AND_COMMENT`, `READ_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_ |
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Move-a-project)
Move a project
----------------------------------------------------------------------------------------
> Example move project request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands=[\
{\
"type": "project_move",\
"uuid": "1ca42128-d12f-4a66-8413-4d6ff2838fde",\
"args": {\
"id": "6Jf8VQXxpwv56VQ7",\
"parent_id": "6X7fphhgwcXVGccJ"\
}\
}]'
> Example response:
{
...
"sync_status": {"1ca42128-d12f-4a66-8413-4d6ff2838fde": "ok"},
...
}
Update parent project relationships of the project.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the project (could be a temp id). |
| parent\_id _String_ | No | The ID of the parent project (could be a temp id). If set to null, the project will be moved to the root. |
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Move-a-Project-to-a-Workspace)
Move a Project to a Workspace
----------------------------------------------------------------------------------------------------------------------
> Example move project to workspace request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands=[\
{\
"type": "project_move_to_workspace",\
"uuid": "1ca42128-d12f-4a66-8413-4d6ff2838fde",\
"args": {\
"project_id": "6Jf8VQXxpwv56VQ7",\
"workspace_id": "220325187",\
"is_invite_only": false,\
"folder_id": null\
}\
}]'
> Example response:
{
...
"sync_status": {"1ca42128-d12f-4a66-8413-4d6ff2838fde": "ok"},
...
}
Moves a personal project into the target workspace.
A few notes about moving projects to a workspace:
* Moving a parent project to a workspace will also move all its child projects to that workspace.
* If no folder\_id is supplied, child projects will be moved into a folder with the same name as the parent project being moved
* If a folder\_id is supplied, the parent and child projects will be moved into that folder.
* 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.
* 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
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| project\_id _String_ | Yes | The ID of the project (can be a temp id). |
| workspace\_id _String_ | Yes | The ID of the workspace the project will be moved into |
| is\_invite\_only _Boolean_ | No | If true the project will be restricted access, otherwise any workspace member could join it |
| folder\_id _String_ | No | If supplied, the project and any child projects will be moved into this workspace folder |
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Move-a-Project-out-of-a-Workspace)
Move a Project out of a Workspace
------------------------------------------------------------------------------------------------------------------------------
> Example move project out of a workspace request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands=[\
{\
"type": "project_move_to_personal",\
"uuid": "1ca42128-d12f-4a66-8413-4d6ff2838fde",\
"args": {\
"project_id": "6Jf8VQXxpwv56VQ7",\
}\
}]'
> Example response:
{
...
"sync_status": {"1ca42128-d12f-4a66-8413-4d6ff2838fde": "ok"},
...
}
Moves a project inside a workspace out back into a users personal space.
Only the original creator of the workspace have permissions to do this, and only if they are still currently an admin of said workspace.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| project\_id _String_ | Yes | The ID of the project being moved back (can be a temp id). |
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Leave-a-project)
Leave a project
------------------------------------------------------------------------------------------
> Example leave project request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands=[\
{\
"type": "project_leave",\
"uuid": "1ca42128-d12f-4a66-8413-4d6ff2838fde",\
"args": {\
"project_id": "6Jf8VQXxpwv56VQ7",\
}\
}]'
> Example response:
{
...
"sync_status": {"1ca42128-d12f-4a66-8413-4d6ff2838fde": "ok"},
...
}
_Only used for teams_
This command is used to remove self from a workspace project. As this is a v2-only command, it will only accept v2 project id.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| project\_id _String_ | Yes | The ID (`v2_id`) of the project to leave. It only accepts `v2_id` as the id. |
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Delete-a-project)
Delete a project
--------------------------------------------------------------------------------------------
> Example delete project request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands=[\
{\
"type": "project_delete",\
"uuid": "367182ba-125f-4dbb-bff6-c1343fd751e4",\
"args": {\
"id": "6X7fphhgwcXVGccJ"\
}\
}]'
> Example response:
{
...
"sync_status": {"367182ba-125f-4dbb-bff6-c1343fd751e4": "ok"},
...
}
Delete an existing project and all its descendants. Workspace projects can only be deleted by `ADMIN`s and it must be archived first.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | ID of the project to delete (could be a temp id). |
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Archive-a-project)
Archive a project
----------------------------------------------------------------------------------------------
> Example archive project request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands=[\
{\
"type": "project_archive",\
"uuid": "bbec1a60-2bdd-48ac-a623-c8eb968e1697",\
"args": {\
"id": "6X7fphhgwcXVGccJ"\
}\
}]'
> Example response:
{
...
"sync_status": {"bbec1a60-2bdd-48ac-a623-c8eb968e1697": "ok"},
...
}
Archive a project and its descendants.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | ID of the project to archive (could be a temp id). |
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Unarchive-a-project)
Unarchive a project
--------------------------------------------------------------------------------------------------
> Example unarchive project request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands=[\
{\
"type": "project_unarchive",\
"uuid": "7d86f042-e098-4fa6-9c1f-a61fe8c39d74",\
"args": {\
"id": "6X7fphhgwcXVGccJ"\
}\
}]'
> Example response:
{
...
"sync_status": {"7d86f042-e098-4fa6-9c1f-a61fe8c39d74": "ok"},
...
}
Unarchive a project. No ancestors will be unarchived along with the unarchived project. Instead, the project is unarchived alone, loses any parent relationship (becomes a root project), and is placed at the end of the list of other root projects.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | ID of the project to unarchive (could be a temp id). |
[](https://developer.todoist.com/api/v1#tag/Sync/Projects/Reorder-projects)
Reorder projects
--------------------------------------------------------------------------------------------
> Example reorder projects request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands=[\
{\
"type": "project_reorder",\
"uuid": "bf0855a3-0138-4b76-b895-88cad8db9edc",\
"args": {\
"projects": [\
{\
"id": "6Jf8VQXxpwv56VQ7",\
"child_order": 1\
},\
{\
"id": "6X7fphhgwcXVGccJ",\
"child_order": 2\
}\
]\
}\
}]'
> Example response:
{
...
"sync_status": {"bf0855a3-0138-4b76-b895-88cad8db9edc": "ok"},
...
}
The command updates `child_order` properties of projects in bulk.
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| 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. |
[](https://developer.todoist.com/api/v1#tag/Sync/Comments)
Comments
-------------------------------------------------------------------
[](https://developer.todoist.com/api/v1#tag/Sync/Comments/Task-comments)
Task comments
--------------------------------------------------------------------------------------
> An example task comment:
{
"id": "6X7gfQHG59V8CJJV",
"posted_uid": "2671355",
"item_id": "6X7gfV9G7rWm5hW8",
"content": "Note",
"file_attachment": {
"file_type": "text/plain",
"file_name": "File1.txt",
"file_size": 1234,
"file_url": "https://example.com/File1.txt",
"upload_state": "completed"
},
"uids_to_notify": [\
"84129"\
]
"is_deleted": false,
"posted_at": "2014-10-01T14:54:55.000000Z",
"reactions": { "❤️": ["2671362"], "👍": ["2671362", "2671366"] }
}
_Availability of comments functionality is dependent on the current user plan. This value is indicated by the `comments` property of the [user plan limits](https://developer.todoist.com/api/v1#tag/Sync/User/User-plan-limits)
object._
#### Properties
| Property | Description |
| --- | --- |
| id _String_ | The ID of the note. |
| posted\_uid _String_ | The ID of the user that posted the note. |
| item\_id _String_ | The item which the note is part of. |
| 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. |
| file\_attachment _Object_ | A file attached to the note (see the [File Attachments](https://developer.todoist.com/api/v1#tag/Sync/Comments/File-Attachments) section for details). |
| uids\_to\_notify _Array of String_ | A list of user IDs to notify. |
| is\_deleted _Boolean_ | Whether the note is marked as deleted (a `true` or `false` value). |
| posted\_at _String_ | The date when the note was posted. |
| reactions _Object_ | List of emoji reactions and corresponding user IDs. |
### Add a task comment
> Example add comment request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "note_add",\
"temp_id": "59fe4461-287b-4b00-bacc-ee771137a732",\
"uuid": "e1005f08-acd6-4172-bab1-4338f8616e49",\
"args": {\
"item_id": "6X7gfV9G7rWm5hW8",\
"content": "Note1"\
}\
}]'
# or adding a comment with a file attached:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "note_add",\
"temp_id": "6149e689-1a54-48d6-a8c2-0ee5425554a9",\
"uuid": "554a65e9-56d9-478e-b35b-520c419e37d9",\
"args": {\
"item_id": "6X7gfV9G7rWm5hW8",\
"content": "Note1",\
"file_attachment": {\
"file_type": "image\/gif",\
"file_name": "image.gif",\
"image": "https:\/\/domain\/image.gif",\
"file_url": "https:\/\/domain\/image.gif",\
"image_width":90,\
"image_height":76,\
"file_size":7962\
}\
}\
}]'
> Example response:
{
...
"sync_status": {"e1005f08-acd6-4172-bab1-4338f8616e49": "ok"},
"temp_id_mapping": {"59fe4461-287b-4b00-bacc-ee771137a732": "6X7gfQHG59V8CJJV"},
...
}
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| item\_id _String_ | Yes | The item which the note is part of (a unique number or temp id). |
| 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. |
| file\_attachment _Object_ | No | A file attached to the note (see the [File Attachments](https://developer.todoist.com/api/v1#tag/Sync/Comments/File-Attachments) section for details, and learn how to upload a file in the [Uploads section](https://developer.todoist.com/api/v1#tag/Uploads) ). |
| uids\_to\_notify _Array of String_ | No | A list of user IDs to notify. |
### Update a task comment
> Example update comment request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "note_update",\
"uuid": "8a38f9c5-2cd0-4da5-87c1-26d617b354e0",\
"args": {\
"id": "6X7gfQHG59V8CJJV",\
"content": "Updated Note1"\
}\
}]'
> Example response:
{
...
"sync_status": {"8a38f9c5-2cd0-4da5-87c1-26d617b354e0": "ok"},
...
}
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the note. |
| 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. |
| file\_attachment _Object_ | No | A file attached to the note (see the [File Attachments](https://developer.todoist.com/api/v1#tag/Sync/Comments/File-Attachments) section for details, and learn how to upload a file in the [Uploads section](https://developer.todoist.com/api/v1#tag/Uploads) ). |
### Delete a task comment
> Example delete comment request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "note_delete",\
"uuid": "8d666fda-73c3-4677-8b04-5d223632c24f",\
"args": {"id": "6X7hH7Gpwr3w7jX9"}\
}]'
> Example response:
{ ...
"sync_status": {"8d666fda-73c3-4677-8b04-5d223632c24f": "ok"},
...
}
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the note. |
[](https://developer.todoist.com/api/v1#tag/Sync/Comments/Project-Comments)
Project Comments
--------------------------------------------------------------------------------------------
> An example project comment:
{
"content": "Hello 2",
"id": "6X7hH9GWrqWhF69Q",
"is_deleted": false,
"posted_at": "2018-08-14T10:56:50.000000Z",
"posted_uid": "2671355",
"project_id": "6Jf8VQXxpwv56VQ7",
"reactions": null,
"uids_to_notify": ["2671362"],
"reactions": { "❤️": ["2671362"], "👍": ["2671362", "2671366"] },
"file_attachment": {
"file_type": "text/plain",
"file_name": "File1.txt",
"file_size": 1234,
"file_url": "https://example.com/File1.txt",
"upload_state": "completed"
}
}
_Availability of comments functionality is dependent on the current user plan. This value is indicated by the `comments` property of the [user plan limits](https://developer.todoist.com/api/v1#tag/Sync/User/User-plan-limits)
object._
#### Properties
| Property | Description |
| --- | --- |
| id _String_ | The ID of the note. |
| posted\_uid _Integer_ | The ID of the user that posted the note. |
| project\_id _String_ | The project which the note is part of. |
| 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. |
| file\_attachment _Object_ | A file attached to the note (see the [File Attachments](https://developer.todoist.com/api/v1#tag/Sync/Comments/File-Attachments) section for details). |
| uids\_to\_notify _Array of String_ | A list of user IDs to notify. |
| is\_deleted _Boolean_ | Whether the note is marked as deleted (a `true` or `false` value). |
| posted\_at _String_ | The date when the note was posted. |
| reactions _Object_ | List of emoji reactions and corresponding user IDs. |
### Add a project comment
> Example add comment request:
curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "note_add",\
"temp_id": "59fe4461-287b-4b00-bacc-ee771137a732",\
"uuid": "e1005f08-acd6-4172-bab1-4338f8616e49",\
"args": {\
"project_id": "6Jf8VQXxpwv56VQ7",\
"content": "Note1"\
}\
}]'
# or adding a note with a file attached:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "note_add",\
"temp_id": "6149e689-1a54-48d6-a8c2-0ee5425554a9",\
"uuid": "554a65e9-56d9-478e-b35b-520c419e37d9",\
"args": {\
"project_id": "6Jf8VQXxpwv56VQ7",\
"content": "Note1",\
"file_attachment": {\
"file_type": "image\/gif",\
"file_name": "image.gif",\
"image": "https:\/\/domain\/image.gif",\
"file_url": "https:\/\/domain\/image.gif",\
"image_width":90,\
"image_height":76,\
"file_size":7962\
}\
}\
}]'
> Example response:
{
...
"sync_status": {"e1005f08-acd6-4172-bab1-4338f8616e49": "ok"},
"temp_id_mapping": {"59fe4461-287b-4b00-bacc-ee771137a732": "6X7hH9GWrqWhF69Q"},
...
}
| Argument | Required | Description |
| --- | --- | --- |
| project\_id _String_ | Yes | The project which the note is part of. |
| 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. |
| file\_attachment _Object_ | No | A file attached to the note (see the [File Attachments](https://developer.todoist.com/api/v1#tag/Sync/Comments/File-Attachments) section for details, and learn how to upload a file in the [Uploads section](https://developer.todoist.com/api/v1#tag/Uploads) ). |
### Update a project comment
> Example update comment request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "note_update",\
"uuid": "8a38f9c5-2cd0-4da5-87c1-26d617b354e0",\
"args": {"id": "6X7hH9GWrqWhF69Q", "content": "Updated Note 1"}\
}]'
> Example response:
{
...
"sync_status": {"8a38f9c5-2cd0-4da5-87c1-26d617b354e0": "ok"},
...
}
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the note. |
| 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. |
| file\_attachment _Object_ | No | A file attached to the note (see the [File Attachments](https://developer.todoist.com/api/v1#tag/Sync/Comments/File-Attachments) section for details, and learn how to upload a file in the [Uploads section](https://developer.todoist.com/api/v1#tag/Uploads) ). |
### Delete a project comment
> Example delete comment request:
$ curl https://api.todoist.com/api/v1/sync \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d commands='[\
{\
"type": "note_delete",\
"uuid": "8a38f9c5-2cd0-4da5-87c1-26d617b354e0",\
"args": {"id": "6X7hH9GWrqWhF69Q"}\
}]'
> Example response:
{
...
"sync_status": {"8d666fda-73c3-4677-8b04-5d223632c24f": "ok"},
...
}
#### Command arguments
| Argument | Required | Description |
| --- | --- | --- |
| id _String_ | Yes | The ID of the note. |
[](https://developer.todoist.com/api/v1#tag/Sync/Comments/File-Attachments)
File Attachments
--------------------------------------------------------------------------------------------
A file attachment is represented as a JSON object. The file attachment may point to a document previously uploaded by the `uploads/add` API call, or by any external resource.
#### Base file properties
| Attribute | Description |
| --- | --- |
| file\_name _String_ | The name of the file. |
| file\_size _Integer_ | The size of the file in bytes. |
| file\_type _String_ | MIME type (for example `text/plain` or `image/png`). |
| 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. |
| upload\_state _String_ | Upload completion state (for example `pending` or `completed`). |
#### Image file properties
If you upload an image, you may provide thumbnail paths to ensure Todoist handles them appropriately. Valid thumbnail information is a JSON array with URL, width in pixels, height in pixels. Ex.: \["[https://example.com/img.jpg",400,300\]](https://example.com/img.jpg%22,400,300%5D)
. "Canonical" thumbnails (ones we create by `uploads/add` API call) have the following sizes: `96x96`, `288x288`, `528x528`.
| Attribute | Description |
| --- | --- |
| tn\_l _List_ | Large thumbnail (a list that contains the URL, the width and the height of the thumbnail). |
| tn\_m _List_ | Medium thumbnail (a list that contains the URL, the width and the height of the thumbnail). |
| tn\_s _List_ | Small thumbnail (a list that contains the URL, the width and the height of the thumbnail). |
#### Audio file properties
If you upload an audio file, you may provide an extra attribute `file_duration` (duration of the audio file in seconds, which takes an integer value). In the web interface the file is rendered with a `