Todoist
Extend the Todoist platform with our APIs.
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 two 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). projects_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:
projects_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 projects_timestamps then all the projects will be fetched. If you specify projects_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=...&projects_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': { ... },
                        'UserId':   User's id
                    }
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:
                        { 
                            "GMAIL_DOMAIN":null, "START_PAGE":"7 days, overdue",
                            "AMPM":false, "SORT_ORDER":0, "US_DATES":false,
                            "TIMEZONE":"America/Santiago" 
                        }
UserId:
Includes the id of the user we are fetching data from. Do note that other user data is returned on login from /API/Users/login.

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

Apart from syncing changes 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
                    }

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"
                      }
                    }