Todoist
Extend the Todoist platform with our powerful APIs.

Important! This version is deprecated! Use the neweset (v2) version instead!

Todoist Sync API makes it easy to retrieve and sync data with Todoist servers. It's great if you want to implement a client that stores all of the data locally and sync changes periodically.

Our Sync API has only three entry points:

Some common Sync API works-flows

The client fetches all the data and stores it locally:

The client makes changes locally without syncing them right away (maybe while being offline):

The client has local changes that need to be synced to Todoist's servers:

The client is unsure if the local model is fully synced and issues a command to only fetch updated data:

/TodoistSync/get

Used to retrieve data (both all and only updated data). project_timestamps can be used to only retrieve updated projects. Do note that at this time only Projects supports partially fetching, this is because only projects and items will grow a lot, the other data is small and does not change that much.
Optional parameters:
project_timestamps:
A JSON object containing a mapping from project ids to their last_updated timestamps. last_updated is a property of a project, it's an unix timestamp of when the project was last updated (name changed, tasks added, etc.)
If you omit project_timestamps then all the projects will be fetched. If you specify project_timestamps then only updated projects will be fetched (i.e. new projects or projects where last_updated is different).
                    { "121214": "1325774561.4", "132424": "1325888134.8", ... }
                    
api_token:
User's API token (returned on successful login from /API/Users/login)
Curl example:
                    curl -X POST -d "api_token=..." https://todoist.com/TodoistSync/get
                    curl -X POST -d 'api_token=...&project_timestamps={"15":"1325774561.4"}' https://todoist.com/TodoistSync/get
                    
Successful return:
HTTP 200 OK with a JSON object of the data:
                    {
                        'FetchedAllData': true/false,
                        'Projects': [ ... ],
                        'ActiveProjectIds': [ ... ],
                        'Labels':   [ ... ],
                        'Settings': { ... }
                    }
                    
Explanation of data returned:
FetchedAllData:
Is true if all the data has been fetched, otherwise false (indicates that only partial data has been retrieved).
Projects:
A list of JSON objects of projects.
                        Example:
                        [{
                          "user_id": 1,
                          "name": "Babu",
                          "color": "#ff8581",
                          "collapsed": 0,
                          "item_order": 1,
                          "cache_count": 13,
                          "indent": 1,
                          "id": 455831,
                          "last_updated": "1325774561.4",
                          "items": [...]
                        }, ...]
                        
Projects[X].items:
A list of items (tasks) from a project.
                        Example:
                        [{
                          "due_date": null,
                          "user_id": 1,
                          "collapsed": 0,
                          "in_history": 1,
                          "priority": 1,
                          "item_order": 2,
                          "content": "Fluffy ferret",
                          "indent": 1,
                          "project_id": 22073,
                          "id": 210873,
                          "checked": 1,
                          "date_string": ""
                        }, ...]
                        
ActiveProjectIds:
A complete list of currently active project ids. Can be used to sync client's local model (e.g. to remove projects from the local model that have been deleted).
                        Example:
                        [ 1212, 114131, 121241, ... ]
                        
Labels:
A JSON list of objects (including things like color, id etc.)
                        Example:
                        [ { "color":4, "count":0, "uid":1, "id":721, "name":"followup" }, ... ]
                        
Settings:
Includes user's settings as a JSON object, including things like start page query and timezone information.
                        Example:
                        { 
                            "START_PAGE":"7 days, overdue",
                            "AMPM":false, "SORT_ORDER":0, "US_DATES":false,
                            "TIMEZONE":"America/Santiago" 
                        }
                        

/TodoistSync/sync

/TodoistSync/sync takes a list of JSON object commands which specify which changes should be done to the model. These changes could be adding projects, deleting tasks etc.

It supports two big features which can make syncing easier:

Required parameters:
items:
A list of JSON object commands. These commands are specified later in the documentation.
                    Example:
                    [{
                         "type": "project_add",
                         "temp_id": "$1326467493134",
                         "timestamp": 1326467500523,
                         "args": {
                           "name": "Test",
                           "item_order": 1,
                           "indent": 1,
                           "color": 1
                         }
                      }, 
                      {
                         "type": "project_update",
                         "timestamp": 1326467500573,
                         "args": {
                           "id": "$1326467493134",
                           "name": "Test new",
                           "item_order": 5,
                           "color": 2
                         }
                    }]
                    
api_token:
User's API token (returned on successful login from /API/Users/login)
Curl example:
                    curl -X POST -d 'api_token=...&items=[{ "type": "project_add", "temp_id": "$1326467493134", "timestamp": 1326467500523, "args": { "name": "Test", "item_order": 1, "indent": 1, "color": 1 } }]' https://todoist.com/TodoistSync/sync
                    
Successful return:
HTTP 200 OK with a JSON object of temporary id to real id mappings:
                    {
                        "$1326467493134": 232323,
                        ...,
                        "$1326467493152": 2323234
                    }
                    

/TodoistSync/syncAndGet

syncAndGet is a combined call that syncs updates and fetches the latest data. This is useful because you don't have to do 2 requests. It takes the combined parameters of /sync and /get.
Required parameters:
api_token:
User's API token (returned on successful login from /API/Users/login)
Optional parameters:
items_to_sync:
A list of JSON object commands. It's the items parameter of /sync call.
project_timestamps:
A JSON object containing a mapping from project ids to their last_updated timestamps. It's the project_timestamps parameter of /get call.
Curl example:
                        curl -X POST -d 'api_token=...&items_to_sync=[{ "type": "project_add", "temp_id": "$1326467493134", "timestamp": 1326467500523, "args": { "name": "Test", "item_order": 1, "indent": 1, "color": 1 } }]' https://todoist.com/TodoistSync/syncAndGet
                    
Successful return:
HTTP 200 OK with a JSON object of temporary id to real id mappings:
                    {
                        "temporary_ids: {
                            "$1326467493134": 232323,
                        },

                        "data": {
                            ... Same data as /get ...
                        }
                    }
                    

Why do I need to supply timestamps?

timestamp should be a unix timestamp of when the command was created. This is used for duplication protection, i.e. we want to ensure that same data isn't added twice. This check works by keeping track of command types, temporary ids and timestamps. By just supplying timestamps the system does these checks automatically and will ignore duplicated commands.

How does temporary ids work?

An offline application will use temporary ids and the Sync API has special support for them. We suggest that you use unix timestamps to generate these ids to give them uniquness (maybe also prefixing them to ensure even more uniquness). An example shows how temporary ids can be used and referenced:

            [{
              "type": "project_add",
              "temp_id": "$1326467493134",
              "args": {
                "name": "Test",
                "item_order": 1,
                "indent": 1,
                "color": 1
              },
              "timestamp": 1326467500523
            }, 
            {
              "type": "project_update",
              "args": {
                "id": "$1326467493134",
                "name": "Test new",
                "color": 2
              },
              "timestamp": 1326467500573
            }]
            

In the above example you can see that project_add command has a temp_id property - - which specifies which temporary id this new project has. project_update command later references this temporary id. The API will automatically resolve these ids.

Additionally /TodoistSync/sync will return the real id of $1326467493134 in the result. Remember to update your local model with these real ids e.g.:

            {"$1326467493134": 21314212}
            

While the system remembers temporary ids and their mappings to real ids, it's important to use real ids when they are available to you (typically after a sync). This is important since the API only remembers the last 500 temporary ids for each user.

JSON object commands

project_add: Adding a project
                    {
                      "type": "project_add",
                      "temp_id": "$1326467493134",
                      "timestamp": 1326467500523,
                      "args": {
                        "name": "Test",
                        "color": 1,
                        "indent": 1,
                        "item_order": 1
                      }
                    }
                    
project_update: Updating a project
                    {
                      "type": "project_update",
                      "timestamp": 1326467976310,
                      "args": {
                        "name": "New name",
                        "indent": 1,
                        "color": 7,
                        "id": "$1326467493134"
                      }
                    }
                    
project_delete: Deleting projects
                    {
                      "type": "project_delete",
                      "timestamp": 1326468118911,
                      "args": {
                        "ids": [1272425]
                      }
                    }
                    
item_add: Adding a task
                    {
                      "type": "item_add",
                      "temp_id": "$1326468158202",
                      "timestamp": 1326468806307,
                      "args": {
                        "content": "Test",
                        "project_id": 1272426,
                        "indent": 1,
                        "priority": 1,
                        "date_string": "tom",
                        "due_date": "2012-3-24T23:59",
                        "item_order": 1
                      }
                    }
                    
When passing date_string and due_date they should be formatted as following: If you want to pass in due dates note that date_string is required, while due_date can be omitted.
item_update: Updating a task
                    {
                      "type": "item_update",
                      "timestamp": 1326470294735,
                      "args": {
                        "content": "New task text",
                        "project_id": 1272426,
                        "indent": 1,
                        "priority": 1,
                        "date_string": "",
                        "due_date": null,
                        "item_order": 5,
                        "id": "$1326468158202"
                      }
                    }
                    
item_delete: Deleting tasks
                    {
                      "type": "item_delete",
                      "timestamp": 1326470379977,
                      "args": {
                        "ids": [11466961],
                        "project_id": 1272426
                      }
                    }
                    
item_move: Moving a task from one project to another
                    {
                      "type": "item_move",
                      "timestamp": 1326470524258,
                      "args": {
                        "project_items": {
                          "1272426": [11466963]
                        },
                        "to_project": 1272419
                      }
                    }
                    
item_complete: Completing a task
                    {
                      "type": "item_complete",
                      "timestamp": 1326470662137,
                      "args": {
                        "project_id": 1272426,
                        "id": 11466964,
                        "ids": [11466964],
                        "force_history": 1
                      }
                    }
                    
item_uncomplete: Uncompleting a task
                    {
                      "type": "item_uncomplete",
                      "timestamp": 1326470707104,
                      "args": {
                        "project_id": 1272426,
                        "id": 11466964,
                        "ids": [11466964],
                        "force_history": 1
                      }
                    }
                    
label_register: Register a label
                    {
                      "type": "label_register",
                      "timestamp": 1326471017745,
                      "temp_id": "$1326470987640",
                      "args": {
                        "name": "home",
                        "color": 5
                      }
                    }
                    
label_delete: Delete a label
                    {
                      "type": "label_delete",
                      "timestamp": 1326471017756,
                      "args": {
                        "id": "$1326470987640"
                      }
                    }